Brunobkr/llama.cpp_AlgMor24_github

1# sade [![Build Status](https://travis-ci.org/lukeed/sade.svg?branch=master)](https://travis-ci.org/lukeed/sade)2 3> Smooth (CLI) Operator 🎶4 5Sade is a small but powerful tool for building command-line interface (CLI) applications for Node.js that are fast, responsive, and helpful!6 7It enables default commands, git-like subcommands, option flags with aliases, default option values with type-casting, required-vs-optional argument handling, command validation, and automated help text generation!8 9Your app's UX will be as smooth as butter... just like [Sade's voice](https://www.youtube.com/watch?v=4TYv2PhG89A). 😉10 11 12## Install13 14```15$ npm install --save sade16```17 18 19## Usage20 21***Input:***22 23```js24#!/usr/bin/env node25 26const sade = require('sade');27 28const prog = sade('my-cli');29 30prog31  .version('1.0.5')32  .option('--global, -g', 'An example global flag')33  .option('-c, --config', 'Provide path to custom config', 'foo.config.js');34 35prog36  .command('build <src> <dest>')37  .describe('Build the source directory. Expects an `index.js` entry file.')38  .option('-o, --output', 'Change the name of the output file', 'bundle.js')39  .example('build src build --global --config my-conf.js')40  .example('build app public -o main.js')41  .action((src, dest, opts) => {42    console.log(`> building from ${src} to ${dest}`);43    console.log('> these are extra opts', opts);44  });45 46prog.parse(process.argv);47```48 49***Output:***50 51```a52$ my-cli --help53 54  Usage55    $ my-cli <command> [options]56 57  Available Commands58    build    Build the source directory.59 60  For more info, run any command with the `--help` flag61    $ my-cli build --help62 63  Options64    -v, --version    Displays current version65    -g, --global     An example global flag66    -c, --config     Provide path to custom config  (default foo.config.js)67    -h, --help       Displays this message68 69 70$ my-cli build --help71 72  Description73    Build the source directory.74    Expects an `index.js` entry file.75 76  Usage77    $ my-cli build <src> [options]78 79  Options80    -o, --output    Change the name of the output file  (default bundle.js)81    -g, --global    An example global flag82    -c, --config    Provide path to custom config  (default foo.config.js)83    -h, --help      Displays this message84 85  Examples86    $ my-cli build src build --global --config my-conf.js87    $ my-cli build app public -o main.js88```89 90## Tips91 92- **Define your global/program-wide version, options, description, and/or examples first.**<br>93  _Once you define a Command, you can't access the global-scope again._94 95- **Define all commands & options in the order that you want them to appear.**<br>96  _Sade will not mutate or sort your CLI for you. Global options print before local options._97 98- **Required arguments without values will error & exit**<br>99  _An `Insufficient arguments!` error will be displayed along with a help prompt._100 101- **Don't worry about manually displaying help~!**<br>102  _Your help text is displayed automatically... including command-specific help text!_103 104- **Automatic default/basic patterns**<br>105  _Usage text will always append `[options]` & `--help` and `--version` are done for you._106 107- **Only define what you want to display!**<br>108  _Help text sections (example, options, etc) will only display if you provide values._109 110 111## Subcommands112 113Subcommands are defined & parsed like any other command! When defining their [`usage`](#usage-1), everything up until the first argument (`[foo]` or `<foo>`) is interpreted as the command string.114 115They should be defined in the order that you want them to appear in your general `--help` output.116 117Lastly, it is _not_ necessary to define the subcommand's "base" as an additional command. However, if you choose to do so, it's recommended that you define it first for better visibility.118 119```js120const prog = sade('git');121 122// Not necessary for subcommands to work, but it's here anyway!123prog124  .command('remote')125  .describe('Manage set of tracked repositories')126  .action(opts => {127    console.log('~> Print current remotes...');128  });129 130prog131  .command('remote add <name> <url>', 'Demo...')132  .action((name, url, opts) => {133    console.log(`~> Adding a new remote (${name}) to ${url}`);134  });135 136prog137  .command('remote rename <old> <new>', 'Demo...')138  .action((old, nxt, opts) => {139    console.log(`~> Renaming from ${old} to ${nxt}~!`);140  });141```142 143 144## Single Command Mode145 146In certain circumstances, you may only need `sade` for a single-command CLI application.147 148> **Note:** Until `v1.6.0`, this made for an awkward pairing.149 150To enable this, you may make use of the [`isSingle`](#issingle) argument. Doing so allows you to pass the program's entire [`usage` text](#usage-1) into the `name` argument.151 152With "Single Command Mode" enabled, your entire binary operates as one command. This means that any [`prog.command`](#progcommandusage-desc-opts) calls are disallowed & will instead throw an Error. Of course, you may still define a program version, a description, an example or two, and declare options. You are customizing the program's attributes as a whole.<sup>*</sup>153 154> <sup>*</sup> This is true for multi-command applications, too, up until your first `prog.command()` call!155 156***Example***157 158Let's reconstruct [`sirv-cli`](https://github.com/lukeed/sirv), which is a single-command application that (optionally) accepts a directory from which to serve files. It also offers a slew of option flags:159 160```js161sade('sirv [dir]', true)162  .version('1.0.0')163  .describe('Run a static file server')164  .example('public -qeim 31536000')165  .example('--port 8080 --etag')166  .example('my-app --dev')167  .option('-D, --dev', 'Enable "dev" mode')168  .option('-e, --etag', 'Enable "Etag" header')169  // There are a lot...170  .option('-H, --host', 'Hostname to bind', 'localhost')171  .option('-p, --port', 'Port to bind', 5000)172  .action((dir, opts) => {173    // Program handler174  })175  .parse(process.argv);176```177 178When `sirv --help` is run, the generated help text is trimmed, fully aware that there's only one command in this program:179 180```181  Description182    Run a static file server183 184  Usage185    $ sirv [dir] [options]186 187  Options188    -D, --dev        Enable "dev" mode189    -e, --etag       Enable "Etag" header190    -H, --host       Hostname to bind  (default localhost)191    -p, --port       Port to bind  (default 5000)192    -v, --version    Displays current version193    -h, --help       Displays this message194 195  Examples196    $ sirv public -qeim 31536000197    $ sirv --port 8080 --etag198    $ sirv my-app --dev199```200 201## Command Aliases202 203Command aliases are alternative names (aliases) for a command. They are often used as shortcuts or as typo relief!204 205The aliased names do not appear in the general help text.<br>206Instead, they only appear within the Command-specific help text under an "Aliases" section.207 208***Limitations***209 210* You cannot assign aliases while in [Single Command Mode](#single-command-mode)211* You cannot call [`prog.alias()`](#progaliasnames) before defining any Commands (via `prog.commmand()`)212* You, the developer, must keep track of which aliases have already been used and/or exist as Command names213 214***Example***215 216Let's reconstruct the `npm install` command as a Sade program:217 218```js219sade('npm')220  // ...221  .command('install [package]', 'Install a package', {222    alias: ['i', 'add', 'isntall']223  })224  .option('-P, --save-prod', 'Package will appear in your dependencies.')225  .option('-D, --save-dev', 'Package will appear in your devDependencies.')226  .option('-O, --save-optional', 'Package will appear in your optionalDependencies')227  .option('-E, --save-exact', 'Save exact versions instead of using a semver range operator')228  // ...229```230 231When we run `npm --help` we'll see this general help text:232 233```234  Usage235    $ npm <command> [options]236 237  Available Commands238    install    Install a package239 240  For more info, run any command with the `--help` flag241    $ npm install --help242 243  Options244    -v, --version    Displays current version245    -h, --help       Displays this message246```247 248When we run `npm install --help` &mdash; ***or*** the help flag with any of `install`'s aliases &mdash; we'll see this command-specific help text:249 250```251  Description252    Install a package253 254  Usage255    $ npm install [package] [options]256 257  Aliases258    $ npm i259    $ npm add260    $ npm isntall261 262  Options263    -P, --save-prod        Package will appear in your dependencies.264    -D, --save-dev         Package will appear in your devDependencies.265    -O, --save-optional    Package will appear in your optionalDependencies266    -E, --save-exact       Save exact versions instead of using a semver range operator267    -h, --help             Displays this message268```269 270 271 272## API273 274### sade(name, isSingle)275Returns: `Program`276 277Returns your chainable Sade instance, aka your `Program`.278 279#### name280Type: `String`<br>281Required: `true`282 283The name of your `Program` / binary application.284 285#### isSingle286Type: `Boolean`<br>287Default: `name.includes(' ');`288 289If your `Program` is meant to have ***only one command***.<br>290When `true`, this simplifies your generated `--help` output such that:291 292* the "root-level help" is your _only_ help text293* the "root-level help" does not display an `Available Commands` section294* the "root-level help" does not inject `$ name <command>` into the `Usage` section295* the "root-level help" does not display `For more info, run any command with the `--help` flag` text296 297You may customize the `Usage` of your command by modifying the `name` argument directly.<br>298Please read [Single Command Mode](#single-command-mode) for an example and more information.299 300> **Important:** Whenever `name` includes a custom usage, then `isSingle` is automatically assumed and enforced!301 302### prog.command(usage, desc, opts)303 304Create a new Command for your Program. This changes the current state of your Program.305 306All configuration methods (`prog.describe`, `prog.action`, etc) will apply to this Command until another Command has been created!307 308#### usage309 310Type: `String`311 312The usage pattern for your current Command. This will be included in the general or command-specific `--help` output.313 314_Required_ arguments are wrapped with `<` and `>` characters; for example, `<foo>` and `<bar>`.315 316_Optional_ arguments are wrapped with `[` and `]` characters; for example, `[foo]` and `[bar]`.317 318All arguments are ***positionally important***, which means they are passed to your current Command's [`handler`](#handler) function in the order that they were defined.319 320When optional arguments are defined but don't receive a value, their positionally-equivalent function parameter will be `undefined`.321 322> **Important:** You **must** define & expect required arguments _before_ optional arguments!323 324```js325sade('foo')326 327  .command('greet <adjective> <noun>')328  .action((adjective, noun, opts) => {329    console.log(`Hello, ${adjective} ${noun}!`);330  })331 332  .command('drive <vehicle> [color] [speed]')333  .action((vehicle, color, speed, opts) => {334    let arr = ['Driving my'];335    arr.push(color ? `${color} ${vehicle}` : vehicle);336    speed && arr.push(`at ${speed}`);337    opts.yolo && arr.push('...YOLO!!');338    let str = arr.join(' ');339    console.log(str);340  });341```342 343```sh344$ foo greet beautiful person345# //=> Hello, beautiful person!346 347$ foo drive car348# //=> Driving my car349 350$ foo drive car red351# //=> Driving my red card352 353$ foo drive car blue 100mph --yolo354# //=> Driving my blue car at 100mph ...YOLO!!355```356 357 358#### desc359 360Type: `String`<br>361Default: `''`362 363The Command's description. The value is passed directly to [`prog.describe`](#progdescribetext).364 365#### opts366 367Type: `Object`<br>368Default: `{}`369 370##### opts.alias371Type: `String|Array`372 373Optionally define one or more aliases for the current Command.<br>374When declared, the `opts.alias` value is passed _directly_ to the [`prog.alias`](#progaliasnames) method.375 376```js377// Program A is equivalent to Program B378// ---379 380const A = sade('bin')381  .command('build', 'My build command', { alias: 'b' })382  .command('watch', 'My watch command', { alias: ['w', 'dev'] });383 384const B = sade('bin')385  .command('build', 'My build command').alias('b')386  .command('watch', 'My watch command').alias('w', 'dev');387```388 389 390##### opts.default391 392Type: `Boolean`393 394Manually set/force the current Command to be the Program's default command. This ensures that the current Command will run if no command was specified.395 396> **Important:** If you run your Program without a Command _and_ without specifying a default command, your Program will exit with a `No command specified` error.397 398```js399const prog = sade('greet');400 401prog.command('hello');402//=> only runs if :: `$ greet hello`403 404// $ greet405//=> error: No command specified.406 407prog.command('howdy', '', { default:true });408//=> runs as `$ greet` OR `$ greet howdy`409 410// $ greet411//=> runs 'howdy' handler412 413// $ greet foobar414//=> error: Invalid command415```416 417 418### prog.describe(text)419 420Add a description to the current Command.421 422#### text423 424Type: `String|Array`425 426The description text for the current Command. This will be included in the general or command-specific `--help` output.427 428Internally, your description will be separated into an `Array` of sentences.429 430For general `--help` output, ***only*** the first sentence will be displayed. However, **all sentences** will be printed for command-specific `--help` text.431 432> **Note:** Pass an `Array` if you don't want internal assumptions. However, the first item is _always_ displayed in general help, so it's recommended to keep it short.433 434 435### prog.alias(...names)436 437Define one or more aliases for the current Command.438 439> **Important:** An error will be thrown if:<br>1) the program is in [Single Command Mode](#single-command-mode); or<br>2) `prog.alias` is called before any `prog.command`.440 441#### names442 443Type: `String`444 445The list of alternative names (aliases) for the current Command.<br>446For example, you may want to define shortcuts and/or common typos for the Command's full name.447 448> **Important:** Sade _does not_ check if the incoming `names` are already in use by other Commands or their aliases.<br>During conflicts, the Command with the same `name` is given priority, otherwise the first Command (according to Program order) with `name` as an alias is chosen.449 450The `prog.alias()` is append-only, so calling it multiple times within a Command context will _keep_ all aliases, including those initially passed via [`opts.alias`](#optsdefault).451 452```js453sade('bin')454  .command('hello <name>', 'Greet someone by their name', {455    alias: ['hey', 'yo']456  })457  .alias('hi', 'howdy')458  .alias('hola', 'oi');459//=> hello aliases: hey, yo, hi, howdy, hola, oi460```461 462 463### prog.action(handler)464 465Attach a callback to the current Command.466 467#### handler468 469Type: `Function`470 471The function to run when the current Command is executed.472 473Its parameters are based (positionally) on your Command's [`usage`](#usage-1) definition.474 475All options, flags, and extra/unknown values are included as the last parameter.476 477> **Note:** Optional arguments are also passed as parameters & may be `undefined`!478 479```js480sade('foo')481  .command('cp <src> <dest>')482  .option('-f, --force', 'Overwrite without confirmation')483  .option('-c, --clone-dir', 'Copy files to additional directory')484  .option('-v, --verbose', 'Enable verbose output')485  .action((src, dest, opts) => {486    console.log(`Copying files from ${src} --> ${dest}`);487    opts.c && console.log(`ALSO copying files from ${src} --> ${opts['clone-dir']}`);488    console.log('My options:', opts);489  })490 491// $ foo cp original my-copy -v492//=> Copying files from original --> my-copy493//=> My options: { _:[], v:true, verbose:true }494 495// $ foo cp original my-copy --clone-dir my-backup496//=> Copying files from original --> my-copy497//=> ALSO copying files from original --> my-backup498//=> My options: { _:[], c:'my-backup', 'clone-dir':'my-backup' }499```500 501 502### prog.example(str)503 504Add an example for the current Command.505 506#### str507 508Type: `String`509 510The example string to add. This will be included in the general or command-specific `--help` output.511 512> **Note:** Your example's `str` will be prefixed with your Program's [`name`](#sadename).513 514 515### prog.option(flags, desc, value)516 517Add an Option to the current Command.518 519#### flags520 521Type: `String`522 523The Option's flags, which may optionally include an alias.524 525You may use a comma (`,`) or a space (` `) to separate the flags.526 527> **Note:** The short & long flags can be declared in any order. However, the alias will always be displayed first.528 529> **Important:** If using hyphenated flag names, they will be accessible **as declared** within your [`action()`](#progactionhandler) handler!530 531```js532prog.option('--global'); // no alias533prog.option('-g, --global'); // alias first, comma534prog.option('--global -g'); // alias last, space535// etc...536```537 538#### desc539 540Type: `String`541 542The description for the Option.543 544#### value545 546Type: `String`547 548The **default** value for the Option.549 550Flags and aliases, if parsed, are `true` by default. See [`mri`](https://github.com/lukeed/mri#minimist) for more info.551 552> **Note:** You probably only want to define a default `value` if you're expecting a `String` or `Number` value type.553 554If you _do_ pass a `String` or `Number` value type, your flag value will be casted to the same type. See [`mri#options.default`](https://github.com/lukeed/mri#optionsdefault) for info~!555 556 557### prog.version(str)558 559The `--version` and `-v` flags will automatically output the Program version.560 561#### str562 563Type: `String`<br>564Default: `0.0.0`565 566The new version number for your Program.567 568> **Note:** Your Program `version` is `0.0.0` until you change it.569 570### prog.parse(arr, opts)571 572Parse a set of CLI arguments.573 574#### arr575 576Type: `Array`577 578Your Program's `process.argv` input.579 580> **Important:** Do not `.slice(2)`! Doing so will break parsing~!581 582#### opts583 584Type: `Object`<br>585Default: `{}`586 587Additional `process.argv` parsing config. See [`mri`'s options](https://github.com/lukeed/mri#mriargs-options) for details.588 589> **Important:** These values _override_ any internal values!590 591```js592prog593  .command('hello')594  .option('-f, --force', 'My flag');595//=> currently has alias pair: f <--> force596 597prog.parse(process.argv, {598  alias: {599    f: ['foo', 'fizz']600  },601  default: {602    abc: 123603  }604});605//=> ADDS alias pair: f <--> foo606//=> REMOVES alias pair: f <--> force607//=> ADDS alias pair: f <--> fizz608//=> ADDS default: abc -> 123 (number)609```610 611#### opts.unknown612 613Type: `Function`<br>614Default: `undefined`615 616Callback to run when an unspecified option flag has been found. This is [passed directly to `mri`](https://github.com/lukeed/mri#optionsunknown).617 618Your handler will receive the unknown flag (string) as its only argument.<br>619You may return a string, which will be used as a custom error message. Otherwise, a default message is displayed.620 621```js622sade('sirv')623  .command('start [dir]')624  .parse(process.argv, {625    unknown: arg => `Custom error message: ${arg}`626  });627 628/*629$ sirv start --foobar630 631  ERROR632    Custom error message: --foobar633 634  Run `$ sirv --help` for more info.635*/636```637 638#### opts.lazy639 640Type: `Boolean`<br>641Default: `false`642 643If true, Sade will not immediately execute the `action` handler. Instead, `parse()` will return an object of `{ name, args, handler }` shape, wherein the `name` is the command name, `args` is all arguments that _would be_ passed to the action handler, and `handler` is the function itself.644 645From this, you may choose when to run the `handler` function. You also have the option to further modify the `args` for any reason, if needed.646 647```js648let { name, args, handler } = prog.parse(process.argv, { lazy:true });649console.log('> Received command: ', name);650 651// later on...652handler.apply(null, args);653```654 655### prog.help(cmd)656 657Manually display the help text for a given command. If no command name is provided, the general/global help is printed.658 659Your general and command-specific help text is automatically attached to the `--help` and `-h` flags.660 661> **Note:** You don't have to call this directly! It's automatically run when you `bin --help`662 663#### cmd664Type: `String`<br>665Default: `null`666 667The name of the command for which to display help. Otherwise displays the general help.668 669 670## License671 672MIT © [Luke Edwards](https://lukeed.com)673