From 586242b7f6a1bfebb7b8df847d9935aac8429895 Mon Sep 17 00:00:00 2001 From: Jamon Holmgren Date: Sat, 24 Feb 2018 13:05:17 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9B=20Changes=20examples=20to=20use=20?= =?UTF-8?q?build('brandname')=20rather=20than=20.brand('brandname')?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/runtime.md | 102 +++++++++++++++++-------------------- readme.md | 3 +- src/cli/cli.ts | 5 +- src/domain/builder.test.ts | 7 ++- src/index.test.ts | 8 +-- 5 files changed, 59 insertions(+), 66 deletions(-) diff --git a/docs/runtime.md b/docs/runtime.md index 02586977..a2a513f2 100644 --- a/docs/runtime.md +++ b/docs/runtime.md @@ -2,13 +2,12 @@ With the gluegun API, you're able to load & execute commands. Check out the [sniff](./sniff.md) module for detecting if your environment is able to run. -Here's what we're about to cover. +Here's a kitchen sink version, which we're about to cover. ```js const { build } = 'gluegun' -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugin('~/.movie/movie-imdb') .plugins('./node_modules', { pattern: 'movie-' }) @@ -16,6 +15,7 @@ const cli = build() .version() .defaultCommand() .command({ name: 'hi', run: toolbox => toolbox.print.info('hi!') }) + .exclude(['filesystem', 'semver', 'system', 'prompt', 'http']) .create() await cli.run() @@ -32,47 +32,16 @@ const { build } = require('gluegun') Now let's build a `gluegun` cli environment by configuring various features. ```js -const cli = build() +const cli = build('mycli') ``` -But out of the box, it does very little. And by very little I mean nothing. So let's configure this. - -We'll be chaining the `build()` function from here. - -## brand - -**Brand** is used through-out the glue for things like configuration file names and folder names for plugins. +The `mycli` brand that you pass into `build` is used through-out gluegun for things like configuration file names and folder names for plugins. You can also set it later, like this: ```js const cli = build().brand('movie') ``` -The brand is most likely to share the same name of the CLI. - -## exclude - -If you don't need certain core extensions, you can skip loading them (thus improving startup time) by using `.exclude()`. Just pass in an array of string names for the core extensions you don't need. Just make sure this appears before the `.src()` command (documented below). - -```js -const cli = build() - .brand('movie') - .exclude(['meta', 'strings', 'print', 'filesystem', 'semver', 'system', 'prompt', 'http', 'template', 'patching']) -``` - -If you find you need one of these extensions for just _one_ command but don't want to load it for _all_ of your commands, you can always load it separately from the Gluegun toolbox, like this: - -```js -const { prompt } = require('gluegun/toolbox') -``` - -For reference, the core extensions that incur the biggest startup performance penalty are (timing varies per machine, but this gives some sense of scale): - -``` -prompt +100ms -print +45ms -http +30ms -system +10ms -``` +Out of the box, this CLI does very little. And by very little I mean nothing. So let's configure this. We'll be chaining the `build()` function from here. ## src @@ -80,9 +49,7 @@ This sets where the default commands and extensions are located, in `commands` and `extensions` folders, respectively. ```js -const cli = build() - .brand('movie') - .src(__dirname) +const cli = build('movie').src(__dirname) ``` When you run a command, it'll first load extensions in this folder and then check the commands in this folder for the right command. @@ -116,8 +83,7 @@ movie-credits You can load a plugin from a directory: ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugin('~/.movie/movie-imdb') ``` @@ -127,8 +93,7 @@ const cli = build() You can also load multiple plugins within a directory. ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugin('~/.movie/movie-imdb') .plugins('./node_modules', { pattern: 'movie-' }) @@ -154,8 +119,7 @@ Gluegun ships with a somewhat adequate `help` screen out of the box. Add it to y CLI easily by calling `.help()`. ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugins('./node_modules', { pattern: 'movie-' }) .plugin('~/.movie/movie-imdb') @@ -181,8 +145,7 @@ You usually like to be able to run `--version` to see your CLI's version from th line, so add it easily with `.version()`. ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugins('./node_modules', { pattern: 'movie-' }) .plugin('~/.movie/movie-imdb') @@ -199,8 +162,7 @@ instead. Note that you can do this by supplying a `.js` file in your `./c folder as well. ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugins('./node_modules', { pattern: 'movie-' }) .plugin('~/.movie/movie-imdb') @@ -217,8 +179,7 @@ you prefer more control. If you want to pass in arbitrary commands, you can do that with `.command()`. ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugins('./node_modules', { pattern: 'movie-' }) .plugin('~/.movie/movie-imdb') @@ -233,13 +194,46 @@ In this case, if you ran `movie hi`, it would run the function provided and prin You must provide an object with at least a `name` and a `run` function, which can be `async` or regular. +## exclude + +If you don't need certain core extensions, you can skip loading them (thus improving startup time) by using `.exclude()`. Just pass in an array of string names for the core extensions you don't need. + +```js +const cli = build('movie').exclude([ + 'meta', + 'strings', + 'print', + 'filesystem', + 'semver', + 'system', + 'prompt', + 'http', + 'template', + 'patching', +]) +``` + +If you find you need one of these extensions for just _one_ command but don't want to load it for _all_ of your commands, you can always load it separately from the Gluegun toolbox, like this: + +```js +const { prompt } = require('gluegun/toolbox') +``` + +For reference, the core extensions that incur the biggest startup performance penalty are (timing varies per machine, but this gives some sense of scale): + +``` +prompt +100ms +print +45ms +http +30ms +system +10ms +``` + ## create At this point, we've been configuring our CLI. When we're ready, we call `create()`: ```js -const cli = build() - .brand('movie') +const cli = build('movie') .src(__dirname) .plugins('./node_modules', { pattern: 'movie-' }) .plugin('~/.movie/movie-imdb') diff --git a/readme.md b/readme.md index 9b5af2a4..b12d21ad 100644 --- a/readme.md +++ b/readme.md @@ -64,8 +64,7 @@ Let's start with what a `gluegun` CLI looks like. const { build } = require('gluegun') // aim -const movieCLI = build() - .brand('movie') +const movieCLI = build('movie') .src(`${__dirname}/core-plugins`) .plugins('node_modules', { matching: 'movie-*' }) .help() diff --git a/src/cli/cli.ts b/src/cli/cli.ts index 91b13ef6..fbda117e 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -5,12 +5,11 @@ import { build, GluegunToolbox } from '../index' */ export async function run(argv?: string[] | string): Promise { // create a CLI runtime - const cli = build() - .brand('gluegun') - .exclude(['semver', 'prompt', 'http', 'patching']) + const cli = build('gluegun') .src(__dirname) .help() .version() + .exclude(['semver', 'prompt', 'http', 'patching']) .create() // and run it diff --git a/src/domain/builder.test.ts b/src/domain/builder.test.ts index 48d972c1..1c552798 100644 --- a/src/domain/builder.test.ts +++ b/src/domain/builder.test.ts @@ -3,9 +3,7 @@ import { build } from './builder' import { Toolbox } from './toolbox' test('the gauntlet', t => { - const brand = 'test' - const builder = build() - .brand(brand) + const builder = build('test') // plugins .src(`${__dirname}/../fixtures/good-plugins/threepack`) .help() @@ -21,11 +19,12 @@ test('the gauntlet', t => { const runtime = builder.create() t.truthy(runtime) + t.is(runtime.brand, 'test') t.is(runtime.commands.length, 26) t.is(runtime.extensions.length, 13) t.is(runtime.defaultPlugin.commands.length, 6) - t.is(runtime.defaultPlugin.commands[0].name, brand) + t.is(runtime.defaultPlugin.commands[0].name, 'test') t.is(runtime.defaultPlugin.commands[1].name, 'gimmedatversion') t.is(runtime.defaultPlugin.commands[1].run(new Toolbox()), 'it works') t.is(runtime.defaultPlugin.commands[2].name, 'help') diff --git a/src/index.test.ts b/src/index.test.ts index ad1abc57..5de9a5bc 100644 --- a/src/index.test.ts +++ b/src/index.test.ts @@ -5,8 +5,10 @@ test('create', t => { t.truthy(exported) t.is(typeof exported.build, 'function') const { build } = exported - const runtime = build() - .brand('test') - .create() + const runtime = build('test').create() t.is(runtime.brand, 'test') + const runtime2 = build() + .brand('test2') + .create() + t.is(runtime2.brand, 'test2') })