docs(examples): add examples

examples/command/action-handler.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+import { IFlags } from '../../packages/flags/lib/types.ts';
+
+await new Command()
+    .command( 'rm <dir>' )
+    .option( '-r, --recursive [recursive:boolean]', 'Remove recursively' )
+    .action( ( { recursive }: IFlags, dir: string ) => {
+        console.log( 'remove ' + dir + ( recursive ? ' recursively' : '' ) );
+    } )
+    .parse( Deno.args );

examples/command/action-options.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .version( '0.1.0' )
+    .option( '-i, --info [arg:boolean]', 'Print some info.', {
+        standalone: true,
+        action: () => {
+            console.log( 'Some info' );
+            Deno.exit( 0 );
+        }
+    } )
+    .parse( Deno.args );

examples/command/arguments-syntax-sub-command.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+import { IFlags } from '../../packages/flags/lib/types.ts';
+
+await new Command()
+    .version( '0.1.0' )
+    .command( 'rmdir <dirs...:string>' )
+    .action( ( options: IFlags, dirs: string[] ) => {
+        dirs.forEach( ( dir: string ) => {
+            console.log( 'rmdir %s', dir );
+        } );
+    } )
+    .parse( Deno.args );

examples/command/arguments-syntax.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options, args } = await new Command()
+    .version( '0.1.0' )
+    .arguments( '<cmd:string> [env:string] [dirs...:string]' )
+    .parse( Deno.args );
+
+console.log( 'command:', args[0] );
+console.log( 'environment:', args[1] || "no environment given");
+console.log( 'directories:', args[2] || "no directories given");

examples/command/common-option-types.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    // boolean with optional value
+    .option( '-d, --debug', 'output extra debugging.' )
+    // boolean with optional value
+    .option( '-s, --small [small:boolean]', 'Small pizza size.' )
+    // string with required value
+    .option( '-p, --pizza-type <type>', 'Flavour of pizza.' )
+    // string with required value
+    .option( '-n, --notes <note:string>', 'Notes.' )
+    // number with required value
+    .option( '-a, --amount <amount:number>', 'Pieces of pizza.' )
+    // parse arguments
+    .parse( Deno.args );
+
+if ( options.debug ) {
+    console.log( options );
+}
+
+console.log( 'pizza details:' );
+
+if ( options.small ) {
+    console.log( '- small pizza size' );
+}
+
+if ( options.pizzaType ) {
+    console.log( `- ${ options.pizzaType }` );
+}
+
+if ( options.amount ) {
+    console.log( '- %s pieces', options.amount );
+}
+
+if ( options.notes ) {
+    console.log( '- notes: %s', options.notes );
+}

examples/command/conflicting-options.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    .option( '-f, --file <file:string>', 'read from file ...' )
+    .option( '-i, --stdin [stdin:boolean]', 'read from stdin ...', { conflicts: [ 'file' ] } )
+    .parse( Deno.args );
+
+console.log( options );

examples/command/creating-a-program.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .version( '0.1.0' )
+    .description( 'Example description ...' )
+    .parse( Deno.args );

examples/command/custom-option-processing.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    .option( '-f, --float <value:number>', 'float argument' )
+    .option( '-i, --integer <value:number>', 'integer argument' )
+    .option( '-v, --variadic <value...:string>', 'repeatable value' )
+    .option( '-l, --list <items:string[]>', 'comma separated list' )
+    .option( '-o, --object <item:string>', 'map string to object', ( value: string ): { value: string } => {
+        return { value };
+    } )
+    .option( '-C, --color <item:string>', 'map string to object', {
+        collect: true,
+        value: ( value: string, previous: string[] = [] ): string[] => {
+
+            if ( [ 'blue', 'yellow', 'red' ].indexOf( value ) === -1 ) {
+                throw new Error( `Color must be one of blue, yellow or red but got: ${ value }` );
+            }
+
+            previous.push( value );
+
+            return previous;
+        }
+    } )
+    .parse( Deno.args );
+
+console.log( options );

examples/command/custom-option-type.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+import { IFlagArgument, IFlagOptions, ITypeHandler } from '../../packages/flags/lib/types.ts';
+
+const email = (): ITypeHandler<string> => {
+
+    const emailRegex: RegExp = /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+
+    return ( option: IFlagOptions, arg: IFlagArgument, value: string | false ): string | undefined => {
+
+        if ( value ) {
+            if ( !emailRegex.test( value.toLowerCase() ) ) {
+                throw new Error( `Option --${ option.name } must be a valid email but got: ${ value }` );
+            }
+            return value;
+        }
+    };
+};
+
+// Register email as global type:
+Command.type( 'email', email() );
+
+const { options } = await new Command()
+    // Register email as command specific type:
+    .type( 'email', email() )
+    .option( '-e, --email <value:email>', 'Your email address.', {
+        // Register email as option specific type:
+        // type: email()
+    } )
+    .parse( Deno.args );
+
+console.log( options );

examples/command/default-option-value.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    .option( '-c, --cheese [type:string]', 'add the specified type of cheese', { default: 'blue' } )
+    .parse( Deno.args );
+
+console.log( `cheese: ${ options.cheese }` );

examples/command/depending-options.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    .option( '-a, --audio-codec <type:string>', 'description ...' )
+    .option( '-v, --video-codec <type:string>', 'description ...', { requires: [ 'audio-codec' ] } )
+    .parse( Deno.args );
+
+console.log( options );

examples/command/environment-variables.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .env( 'SOME_ENV_VAR=<value:number>', 'Description ...' )
+    .parse( Deno.args );
+
+console.log( Deno.env().SOME_ENV_VAR );

examples/command/examples.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { red } from 'https://deno.land/std/fmt/colors.ts';
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .example( 'example name', `Description ...\n\nCan have mutliple lines and ${ red( 'colors' ) }.` )
+    .parse( Deno.args );

examples/command/git-style-executables.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .version( '0.1.0' )
+    .command( 'install [name]', 'install one or more packages' )
+    .command( 'search [query]', 'search with optional query' )
+    .command( 'update', 'update installed packages', { executableFile: 'myUpdateSubCommand' } )
+    .command( 'list', 'list packages installed', { isDefault: true } )
+    .parse( Deno.args );

examples/command/help-option-and-command.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .version( '0.1.0' )
+    .description( 'Sample description ...' )
+    .env( 'EXAMPLE_ENVIRONMENT_VARIABLE=<value:boolean>', 'Environment variable description ...' )
+    .example( 'Some example', 'Example content ...\n\nSome more example content ...' )
+    .parse( Deno.args );

examples/command/list-option-type.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    // comma separated list
+    .option( '-l, --list <items:number[]>', 'comma separated list of numbers.' )
+    // space separated list
+    .option( '-o, --other-list <items:string[]>', 'comma separated list of strings.', { separator: ' ' } )
+    .parse( Deno.args );
+
+console.log( options );

examples/command/negatable-options.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    .option( '--sauce [sauce:boolean]', 'Remove sauce', { default: true } )
+    .option( '--cheese [flavour:string]', 'cheese flavour', { default: 'mozzarella' } )
+    .parse( Deno.args );
+
+const sauceStr = options.sauce ? 'sauce' : 'no sauce';
+const cheeseStr = ( options.cheese === false ) ? 'no cheese' : `${ options.cheese } cheese`;
+
+console.log( `You ordered a pizza with ${ sauceStr } and ${ cheeseStr }` );

examples/command/override-exit-handling.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+try {
+    await new Command()
+        .throwErrors()
+        .version( '0.1.0' )
+        .option( '-p, --pizza-type <type>', 'Flavour of pizza.' )
+        .default('help')
+        .parse( Deno.args );
+} catch ( err ) {
+    // custom processing...
+    console.error( '[CUSTOM_ERROR]', err );
+}

examples/command/required-options.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .allowEmpty( false )
+    .option( '-c, --cheese [type:string]', 'pizza must have cheese', { required: true } )
+    .parse( Deno.args );

examples/command/standalone-options.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .option( '-s, --standalone [value:boolean]', 'Some standalone option.', { standalone: true } )
+    .option( '-o, --other [value:boolean]', 'Some other option.' )
+    .parse( Deno.args );

examples/command/sub-commands.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+// Sub-command implemented using action handler (description is supplied separately to `.command()`)
+await new Command()
+    .command( 'clone <source:string> [destination:string]' )
+    .description( 'Clone a repository into a newly created directory.' )
+    .action( ( source: string, destination: string ) => {
+        console.log( 'clone command called' );
+    } )
+    .parse( Deno.args );
+
+// Sub-command implemented using a command instance as second parameter.
+await new Command()
+    .command( 'clone', new Command()
+        .arguments( '<source:string> [destination:string]' )
+        .description( 'Clone a repository into a newly created directory.' )
+        .action( ( source: string, destination: string ) => {
+            console.log( 'clone command called' );
+        } ) )
+    .parse( Deno.args );
+
+// Command implemented using separate executable file (description is passes as second parameter to `.command()`)
+await new Command()
+    .command( 'start <service>', 'Start named service.' )
+    .command( 'stop [service]', 'Stop named service, or all if no name supplied.' )
+    .parse( Deno.args );

examples/command/variadic-options.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+const { options } = await new Command()
+    .version( '0.1.0' )
+    .option( '-d, --dir [otherDirs...:string]', 'Variadic option.' )
+    .parse( Deno.args );
+
+console.log( options );

examples/command/version-options.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env -S deno --allow-env
+
+import { Command } from '../../packages/command/lib/command.ts';
+
+await new Command()
+    .version( '0.1.0' )
+    .parse( Deno.args );