@flowscripter/dynamic-cli-framework 1.4.19 → 1.5.0

package/README/implementation-details.md

@@ -1,474 +0,0 @@
-# Implementation
-
-The following diagram provides an overview of the main internal modules and
-classes:
-
-```mermaid
-classDiagram
-
-    class parser {
-    }
-
-    class scanner {
-    }
-
-    class Context {
-        <<interface>>
-    }
-
-    class CLI {
-        <<interface>>
-    }
-
-    class runner {
-    }
-
-    class BaseCLI {
-    }
-
-    class Command {
-        <<interface>>
-    }
-
-    class DefaultCommandRegistry {
-    }
-
-    class launcher {
-    }
-
-    class DefaultServiceProviderRegistry {
-    }
-
-    class ServiceProvider {
-        <<interface>>
-    }
-
-    class DefaultContext {
-    }
-
-    class CommandRegistry {
-        <<interface>>
-    }
-
-    class ServiceProviderRegistry {
-        <<interface>>
-    }
-
-    class DefaultRuntimeCLI {
-    }
-
-    class CLIConfig {
-    }
-
-    class ServiceXYZ {
-    }
-
-    runner --> scanner
-
-    runner --> parser
-
-    CLI <|.. BaseCLI
-
-    BaseCLI <|-- DefaultRuntimeCLI
-
-    runner --> Context
-
-    runner --> CommandRegistry
-
-    runner --> ServiceProviderRegistry
-
-    ServiceProviderRegistry <|.. DefaultServiceProviderRegistry
-
-    ServiceProviderRegistry --> "0..*" ServiceProvider : registers
-
-    BaseCLI --> DefaultCommandRegistry
-
-    CommandRegistry <|.. DefaultCommandRegistry
-
-    CommandRegistry --> "0..*" Command : registers
-
-    runner --> "0..1" Command : defaultCommand
-
-    Context <|.. DefaultContext
-
-    BaseCLI --> DefaultContext
-
-    BaseCLI --> DefaultServiceProviderRegistry
-
-    Context --> CLIConfig
-
-    BaseCLI --> CLIConfig
-
-    Context --> ServiceProviderRegistry
-
-    ServiceProvider --> ServiceXYZ : provides
-
-    Context --> ServiceXYZ : access to
-
-    DefaultRuntimeCLI <-- launcher
-```
-
-### `launcher`
-
-The standard way to make use of the framework is to import `launcher` and use
-one of the two helper functions it provides:
-
-- `launchSingleCommandCLI`
-- `launchMultiCommandCLI`
-
-These allow a CLI implementor to specify `Command` instances to use together
-with basic CLI details such as name and description.
-
-### `CLI`
-
-The `CLI` interface has the simple responsibility of taking a `CLIConfig` and a
-list of user specified command line arguments which it should then parse and
-execute any valid specified `Command` it discovers.
-
-#### `BaseCLI`
-
-The `BaseCLI` class provides a base implementation of the `CLI` interface which
-supports both single command and multiple sub-command CLI scenarios. It provides
-the ability to add any number of `Command` and `ServiceProvider` instances.
-
-If only one command is provided, `BaseCLI` will operate as a single command CLI
-and the provided command will be set as a default command. If more than one
-command is added, `BaseCLI` will operate as a multi-command CLI. In this case
-the default command will be set to a help command. In the case of no command
-being specified or a parse error occurring, appropriate help will be displayed.
-
-By default the `BaseCLI` adds the following `ServiceProvider` implementations
-(these are documented in further detail below):
-
-- `ShutdownServiceProvider` allowing CLI shutdown hooks to be registered.
-- `ConfigurationServiceProvider` allowing argument value defaults to be loaded
-  from a configuration file or environment variables. This also provides a
-  key-value store service.
-- `PrinterServiceProvider` allowing CLI output to stdout and stderr writable
-  streams.
-
-By default the `BaseCLI` adds the following `Command` implementations (these are
-documented in further detail below):
-
-- Appropriate help commands depending on whether the CLI is configured with a
-  single command or multiple sub-command.
-- commands provided by the `ConfigurationServiceProvider`.
-- commands provided by the `PrinterServiceProvider`.
-- `VersionCommand`
-
-#### `DefaultRuntimeCLI`
-
-`DefaultRuntimeCLI` is a simple extension to `BaseCLI` which uses NodeJS
-specific APIs to access the command line arguments, stdout and stderr streams
-and to exit the process.
-
-### `runner`
-
-Core CLI behaviour is provided by a `runner` implementation which is responsible
-for parsing arguments, determining which `Command` instances to execute and then
-executing them.
-
-The `runner` implementation supports specification of a default command which
-should be executed if no command names are parsed on the command line. In this
-scenario, any arguments provided will also be parsed as possible arguments for
-the default command.
-
-The logic for the `runner` is somewhat complex as it allows for the prioritised
-execution of `GlobalModifierCommand` instances and the prioritised
-initialisation of `ServiceProvider` instances. One reason for this is to allow
-the `ConfigurationServiceProvider` to be initialised first and for the resulting
-configuration to be available to other `ServiceProvider` instances which are yet
-to be initialised.
-
-The following activity diagram illustrates the `runner` logic:
-
-```mermaid
-flowchart TD
-    A([start])
-
-    subgraph 1 [for each ServiceProvider in servicePriority order:]
-
-        B([scan args for provided\nGlobalModifierCommand clauses])
-
-        subgraph 2 [for each discovered clause:]
-            C([set default\narg values])
-            D([parse args])
-            E([add to list of\nGlobalModifierCommands\nclauses to execute])
-        end
-
-        F([scan default arg values for provided\nGlobalModifierCommand clauses])
-
-        subgraph 3 [for each discovered clause:]
-            G([parse args])
-            H([add to list of\nGlobalModifierCommands\nclauses to execute])
-        end
-
-        I([order GlobalModifierCommands\nclauses by executePriority])
-
-        subgraph 4 [for each discovered clause:]
-            J([execute GlobalModifierCommand])
-        end
-
-        K([init service provided by ServiceProvider])
-    end
-
-    L([scan args for non-ServiceProvider\nGlobalModifierCommand clauses])
-
-    subgraph 5 [for each discovered clause:]
-        M([set default\narg values])
-        N([parse args])
-        O([add to list of\nGlobalModifierCommands\nclauses to execute])
-    end
-
-    P([scan default arg values for non-ServiceProvider\nGlobalModifierCommand clauses])
-
-    subgraph 6 [for each discovered clause:]
-        Q([parse args])
-        R([add to list of\nGlobalModifierCommands\nclauses to execute])
-    end
-
-    S([order GlobalModifierCommands\nclauses by executePriority])
-
-    subgraph 7 [for each discovered clause:]
-        T([execute GlobalModifierCommand])
-    end
-
-    U([scan args for non-modifier Command clause])
-
-    V{clause found?}
-        V1([set default\narg values])
-        V2([parse args])
-        V3([execute\nnon-modifier Command])
-    W{default\nnon-modifier Command\nprovided?}
-        W1([scan args for\nnon-modifier Command clause])
-        W2{clause\nfound?}
-            W21([set default\narg values])
-            W22([parse args])
-            W23{valid?}
-                W24([execute\nnon-modifier Command])
-        W3([set default\narg values])
-        W31{valid?}
-            W32([execute\nnon-modifier Command])
-
-    Z([end])
-
-    C --> D
-    D --> E
-
-    G --> H
-
-    M --> N
-    N --> O
-
-    Q --> R
-
-    A --> 1
-    B --> 2
-    2 --> F
-    F --> 3
-    3 --> I
-    I --> 4
-    4 --> K
-    1 --> L
-    L --> 5
-    5 --> P
-    P --> 6
-    6 --> S
-    S --> 7
-    7 --> U
-    U --> V
-    V --> |yes|V1
-    V --> |no|W
-    W --> |yes|W1
-    W --> |no|Z
-
-    V1 --> V2
-    V2 --> V3
-    V3 --> Z
-
-    W1 --> W2
-    W2 --> |yes|W21
-    W2 --> |no|W3
-
-    W21 --> W22
-    W22 --> W23
-
-    W23 --> |yes|W24
-    W23 --> |no|Z
-
-    W24 --> Z
-
-    W3 --> W31
-    W31 --> |yes|W32
-    W31 --> |no|Z
-
-    W32 --> Z
-```
-
-### `scanner`
-
-The `runner` defers to a `scanner` implementation which scans arguments for
-potential `CommandClause` instances e.g. a `Command.name` followed by potential
-arguments for that command..
-
-### `parser`
-
-The `runner` defers to a `parser` implementation which performs the actual
-argument parsing based on the `CommandClause` instances returned from the
-`scanner`.
-
-The following parsing rules apply:
-
-**Arguments Must Follow Command**
-
-All arguments for a command are expected to FOLLOW the command i.e. this is
-**NOT** valid:
-
-    executable <sub_command_argument> <sub_command> // not valid
-
-**Arbitrary Option Order**
-
-The order of options for a particular command is not important i.e. these are
-equivalent:
-
-    executable <sub_command> --<option_1_name> <option_1_value> --<option_2_name> <option_2_value>
-    executable <sub_command> --<option_2_name> <option_2_value> --<option_1_name> <option_1_value>
-
-**Arbitrary Command Order**
-
-The order of commands is not important i.e. these are equivalent:
-
-    executable <sub_command> [sub_command_arguments] --<modifier_command_1> [modifier_command_1_arguments] \
-               --<modifier_command_2> [modifier_command_2_arguments]
-    executable --<modifier_command_1> [modifier_command_1_arguments] <sub_command> [sub_command_arguments] \
-               --<modifier_command_2> [modifier_command_2_arguments]
-
-**No Command Interleaving**
-
-Arguments for commands cannot be interleaved with other commands i.e. this is
-**NOT** valid:
-
-    executable --<modifier_command> <sub_command> [sub_command_arguments] [modifier_command_arguments] // not valid
-
-**Single Command**
-
-Apart from global modifier commands, there is expected to be only one command
-specified i.e. these will **NOT** work as intended:
-
-    // not valid - sub-command 2 and arguments will be treated as trailing arguments of sub-command 1.
-    executable <sub_command_1> [sub_command_1_arguments] <sub_command_2> [sub_command_2_arguments]
-
-    // not valid - sub-command and arguments will be treated as trailing arguments of global command.
-    executable --<global_command> <sub_command> [sub_command_arguments]
-
-**Group Command**
-
-A group command name must always be following immediately by a container
-sub-command name i.e. these are **NOT** valid:
-
-    executable <member_sub_command> <group_command> // not valid
-    executable <group_command> <global_command> <member_sub_command> // not valid
-
-**Unused Leading and Trailing Arguments**
-
-Any leading arguments which appear BEFORE an identified command name are
-retained. Any trailing arguments which appear after an identified name which are
-not consumed when parsing the command arguments are also retained.
-
-Once a command has been identified and parsed any retained arguments are
-considered unused and a warning is output.
-
-If a command is NOT identified, any retained arguments are considered potential
-arguments for a default command if it has been configured. This behaviour means
-the following are equivalent:
-
-    executable <default_command_argument> --<modifier_command_name> <modifier_command_argument>
-    executable --<modifier_command_name> <modifier_command_argument> <default_command_argument>
-
-### Command Execution
-
-A `Command` is executed via the implemented function:
-
-    execute(argumentValues: ArgumentValues, context: Context): Promise<void>;
-
-The `Context` instance allow access to the `CLIConfig` and the ability to access
-services by registered service IDs.
-
-The `ArgumentValues` instance provides access to the populated and validated
-arguments for the command. These values are provided either:
-
-- as a single key-value pair in the form `commandName: globalArgumentValue` for
-  a `GlobalCommand` or a `GlobalModifierCommand`.
-- as a complex nested key-value structure mirroring the defined `Option` and
-  `Positional` instances of a `SubCommand`
-
-As an example, if a `GlobalModifierCommand` is defined as follows:
-
-```
-const globalModifierCommand: GlobalModifierCommand = {
-  name: "log-level",
-  argument: {
-    name: "level",
-    type: ArgumentValueTypeName.STRING,
-  },
-  executePriority: 1,
-  execute: (argumentValues: ArgumentValues, context: Context) => Promise.resolve()
-};
-```
-
-and a `SubCommand` is defined as follows:
-
-```
-const subCommand: SubCommand = {
-  name: "connect",
-  options: [
-    {
-      name: "address",
-      type: ComplexValueTypeName.COMPLEX,
-      properties: [
-        {
-          name: "host",
-          type: ArgumentValueTypeName.STRING
-        },
-        {
-          name: "port",
-          type: ArgumentValueTypeName.NUMBER
-        }
-      ]
-    }
-  ],
-  positionals: [
-    {
-      name: "retryOnError",
-      type: ArgumentValueTypeName.BOOLEAN
-    }
-  ],
-  execute: (argumentValues: ArgumentValues, context: Context) => Promise.resolve()
-};
-```
-
-when the following command line arguments are specified:
-
-`myNetworkApp --connect --address.host=127.0.0.1 --address.port=8080 true --log-level=DEBUG`
-
-then the `ArgumentValues` passed to the `globalModifierCommand.execute(...)`
-function would be:
-
-```
-{
-  "log-level": "DEBUG"
-}
-```
-
-and the `ArgumentValues` passed to the `subCommand.execute(...)` function would
-be:
-
-```
-{
-  address: {
-    host: "127.0.0.1",
-    port: 8080
-  },
-  retryOnError: true
-}
-```