add example for option sharing

Author: eegli

.changeset/fluffy-trains-complain.md

@@ -0,0 +1,5 @@
+---
+"@eegli/tinyparse": patch
+---
+
+Update docs to with shared/global options example

.changeset/great-ducks-brake.md

@@ -0,0 +1,5 @@
+---
+"@eegli/tinyparse": minor
+---
+
+Rename `setGlobals` to `globals` and `setMeta` to `meta`

docs/advanced-example.md

@@ -41,14 +41,14 @@ const parserOptions = new Parser()
     description: 'Comma-separated list of file extensions to include',
   });
 
-const setGlobals = (opts: InferOptions<typeof parserOptions>) => {
+const globals = (opts: InferOptions<typeof parserOptions>) => {
   return {
     userName: 'me',
     extensions: opts.extensions.split(','),
   };
 };
 
-const baseParser = parserOptions.setGlobals(setGlobals);
+const baseParser = parserOptions.globals(globals);
 type BaseParser = typeof baseParser;
 
 // Define all subcommands
@@ -102,7 +102,7 @@ const handleDefault = ({ args, globals, options }: HandleDefaultArgs) => {
 
 // Bring it all together
 const parser = baseParser
-  .setMeta({
+  .meta({
     command: 'my-cli',
     summary: 'Work with files and folders',
     help: {

docs/quickstart.md

@@ -43,7 +43,7 @@ const parser = new Parser()
     shortFlag: '-v',
     defaultValue: false,
   })
-  .setGlobals((options) => ({
+  .globals((options) => ({
     getUserFromDB: (name: string) => `${name} Smith`,
     log: (message: string) => {
       if (options.verbose) {
@@ -62,7 +62,7 @@ const parser = new Parser()
     shortFlag: '-v',
     defaultValue: false,
   })
-  .setGlobals((options) => ({
+  .globals((options) => ({
     getUserFromDB: (name: string) => `${name} Smith`,
     log: (message: string) => {
       if (options.verbose) {
@@ -89,7 +89,7 @@ const parser = new Parser()
     shortFlag: '-v',
     defaultValue: false,
   })
-  .setGlobals((options) => ({
+  .globals((options) => ({
     getUserFromDB: (name: string) => `${name} Smith`,
     log: (message: string) => {
       if (options.verbose) {
@@ -105,7 +105,7 @@ const parser = new Parser()
       globals.log(`Hello, ${userName}!`);
     },
   })
-  .setMeta({
+  .meta({
     command: 'my-cli',
     summary: 'A brief description of my-cli',
     help: {
@@ -129,7 +129,7 @@ const parser = new Parser()
     shortFlag: '-v',
     defaultValue: false,
   })
-  .setGlobals((options) => ({
+  .globals((options) => ({
     getUserFromDB: (name: string) => `${name} Smith`,
     log: (message: string) => {
       if (options.verbose) {
@@ -145,7 +145,7 @@ const parser = new Parser()
       globals.log(`Hello, ${userName}!`);
     },
   })
-  .setMeta({
+  .meta({
     command: 'my-cli',
     summary: 'A brief description of my-cli',
     help: {

docs/reference/async-operations.md

@@ -23,7 +23,7 @@ const parser = new Parser()
     required: true,
     defaultValue: '',
   })
-  .setGlobals(async ({ token }) => {
+  .globals(async ({ token }) => {
     // Use the token to establish a connection
     return { database: async (name: string) => name };
   })

docs/reference/globals.md

@@ -4,7 +4,7 @@
 
 Often times, subcommands need access to a shared object such as a database connection or a logger. You can attach such an object in the building phase and it will be passed to the handler of each subcommand (and the default handler). Setting the globals is done via a function that has access to all the options that have been collected while parsing.
 
-Globals are expected to be static and should only be set once. _Calling `.setGlobals()` multiple times will override the previous value._
+Globals are expected to be static and should only be set once. _Calling `.globals()` multiple times will override the previous value._
 
 ```ts
 import { Parser } from '@eegli/tinyparse';
@@ -14,7 +14,7 @@ const globals = {
 };
 
 new Parser()
-  .setGlobals(() => globals)
+  .globals(() => globals)
   .defaultHandler(({ globals }) => {
     const user = globals.database('John');
     console.log(`Hello, ${user}!`);
@@ -48,5 +48,5 @@ const globalSetter = (options: Options) => ({
     }
   },
 });
-const parser = parserOptions.setGlobals(globalSetter).defaultHandler();
+const parser = parserOptions.globals(globalSetter).defaultHandler();
 ```

docs/reference/handlers.md

@@ -52,7 +52,7 @@ const baseParser = new Parser()
     longFlag: '--foo',
     defaultValue: 'default',
   })
-  .setGlobals(() => ({
+  .globals(() => ({
     bar: 'baz',
   }));
 

docs/reference/help-and-meta.md

@@ -4,13 +4,13 @@
 
 All good CLI apps have some way of providing help to the user. Tinyparse is no different. You can register usage information and tokens that, when present in the input, will trigger the help text to be printed to the console .
 
-You can register which a subcommand and flags trigger the help text and other metadata with the `.setMeta()` method. You need to do this _manually_. If you do not specify a help command or help flags, Tinyparse will not assume them for you.
+You can register which a subcommand and flags trigger the help text and other metadata with the `.meta()` method. You need to do this _manually_. If you do not specify a help command or help flags, Tinyparse will not assume them for you.
 
 ```ts
 import { Parser } from '@eegli/tinyparse';
 
 const parser = new Parser()
-  .setMeta({
+  .meta({
     command: 'my-cli',
     summary: 'A brief description of my-cli',
     help: {
@@ -71,4 +71,4 @@ Optional flags
   -V, --version             Print the version
 ```
 
-When you set your help and metadata configuration, Tinyparse will validate the arguments to make sure there are no conflicts with existing flags or subcommands. Note that subsequent calls to `.setMeta()` will overwrite the previous configuration.
+When you set your help and metadata configuration, Tinyparse will validate the arguments to make sure there are no conflicts with existing flags or subcommands. Note that subsequent calls to `.meta()` will overwrite the previous configuration.

docs/reference/subcommands.md

@@ -80,7 +80,7 @@ const baseParser = new Parser()
     shortFlag: '-u',
     defaultValue: false,
   })
-  .setGlobals(() => ({
+  .globals(() => ({
     flower: '🌸',
   }));
 

docs/reference/subparsers.md

@@ -15,45 +15,59 @@ Subparsers can be seen as an _extension_ to subcommands. Although they behave an
 
 Hence, if your app is rather complex and you want to have per-subcommand options (such as a dedicated help and options local to the subcommand), you should use a **subparser** rather than a subcommand. Note that both subcommands and subparsers are defined via a keyword and can live in the same parent parser. Subparsers can be nested arbitrarily deep.
 
-## Adding a Subparser
+## Adding a Subparser with Shared Options
 
-In the following example, we have a main and a subparser. The only difference between them is the version:
+By default - as mentioned above - a subparser acts in complete isolation and does not inherit any options from the parent. _Shared_ or _global_ options can still be achieved but they require a few manual type annotations. In the following example, we have a main and a subparser. They share the `--verbose` option.
+
+1. First, let's define a function to create the shared options. Because parsers are generic, we need to explicitly annotate that the returned parser has the `verbose` option:
 
 ```ts
-const subparser = new Parser()
-  .option('greeting', {
-    longFlag: '--greeting',
-    shortFlag: '-g',
-    defaultValue: '',
-  })
-  .defaultHandler(({ options }) => {
-    console.log(options.greeting);
+type CommonOptions = {
+  verbose: boolean;
+};
+
+const withCommonOptions = <O, G>(
+  parser: Parser<O, G>,
+): Parser<O & CommonOptions, G> => {
+  return parser.option('verbose', {
+    longFlag: '--verbose',
+    shortFlag: '-v',
+    defaultValue: false,
   });
+};
+```
 
-const parser = new Parser()
-  .option('greeting', {
-    longFlag: '--greeting',
-    shortFlag: '-g',
-    defaultValue: '',
-  })
+2. Next, we can create the main and subparser. Both are created with the shared options. Although not shown, each parser can of course have its own options:
+
+```ts
+const subparser = withCommonOptions(new Parser()).defaultHandler(
+  ({ options }) => {
+    console.log(`[subparser] Verbose mode: ${options.verbose}`);
+  },
+);
+
+const parser = withCommonOptions(new Parser())
   .subparser('v2', {
     parser: subparser,
     description: 'Version 2 of this CLI',
   })
   .defaultHandler(({ options }) => {
-    console.log(options.greeting);
+    console.log(`[main parser] Verbose mode: ${options.verbose}`);
   });
 ```
 
 If we append `v2` to the arguments, the subparser will be called. If the first positional argument (here, `v2`) identifies a subparser, then only the subparser will be in charge of validating and parsing all further arguments. The main parser simply delegates the call to the subparser:
 
 ```ts
-// hello from the main parser
-parser.parse(['-g', 'hello from the main parser']).call();
-// hello from the subparser
-parser.parse(['v2', '-g', 'hello from the subparser']).call();
+// [main parser] Verbose mode: true
+parser.parse(['-v']).call();
+
+// [subparser] Verbose mode: true
+parser.parse(['v2', '-v']).call();
 ```
 
+As you might have guessed by now, this example method of sharing global options is merely a way to **reduce code duplication**. Our goal was to have to define the `--verbose` option only once and use it in both the main and subparser.
+
 ## Caveats
 
-Subparsers are a bit more complex to setup and cannot access their parent parser's options (see table above). Hence, you might need to setup globals repeatedly for each parser and have some duplicated code here and there. However, this is a small price to pay for the added flexibility and control over your app's structure.
+Subparsers are a bit more complex to setup and, by default, cannot access their parent parser's options. It is still possible, though, and in some scenarios a small price to pay for the added flexibility and control over your app's structure.