G4.Abstraction.Cli.md

G4.Abstraction.Cli

G4.Abstraction.Cli is a command-line interface (CLI) factory that provides tools for generating CLI structures and patterns. This library allows developers to parse and validate CLI input, extract argument keys and values, handle arrays of values, and process nested CLI expressions. It simplifies command-line processing for applications that use complex CLI arguments or templates.

Installation

To install G4.Abstraction.Cli, add the NuGet package:

dotnet add package G4.Abstraction.Cli

Features

• CLI Template Parsing: Extracts CLI templates from larger strings using regular expression patterns.
• Argument Extraction: Extracts individual CLI arguments, keys, and values.
• Array Support: Supports multiple values for the same key, returning a serialized JSON array of all values under that key.
• Nested Expression Handling: Identifies and encodes nested CLI expressions within the template.
• Compliance Check: Confirms the validity of a CLI against a specified pattern.
• Dictionary Conversion: Converts CLI strings into a dictionary of key-value pairs for easy access.

Usage

1. CLI Validation Example

To validate a CLI string against the factory's CLI template pattern, use the ConfirmCli method. The expected format for CLI input is {{$ --key:value --anotherKey:value}}.

using G4.Abstraction.Cli;

var cliFactory = new CliFactory();
bool isValid = cliFactory.ConfirmCli("{{$ --key:value --anotherKey:value}}");

if (isValid)
{
    Console.WriteLine("The CLI is valid according to the template pattern.");
}
else
{
    Console.WriteLine("The CLI is not valid.");
}

2. Convert CLI to Dictionary

You can convert a CLI string into a dictionary of key-value pairs using the ConvertToDictionary method. This is useful for structured access to CLI arguments.

using G4.Abstraction.Cli;

var cliFactory = new CliFactory();
var cli = "{{$ --name:JohnDoe --age:30 --location:USA}}";

// Convert the CLI string to a dictionary of arguments
var arguments = cliFactory.ConvertToDictionary(cli);

foreach (var arg in arguments)
{
    Console.WriteLine($"{arg.Key}: {arg.Value}");
}

This example would produce output like:

Name: JohnDoe
Age: 30
Location: USA

3. Array Support Example

The CliFactory supports arrays by allowing multiple entries with the same key. When multiple values are specified for a key, ConvertToDictionary will return a serialized JSON array containing all values under that key.

using G4.Abstraction.Cli;

var cliFactory = new CliFactory();
var cli = "{{$ --names:foo --names:bar --names:some other name}}";

// Convert the CLI string to a dictionary of arguments
var arguments = cliFactory.ConvertToDictionary(cli);

foreach (var arg in arguments)
{
    Console.WriteLine($"{arg.Key}: {arg.Value}");
}

This example would produce output like:

Names: ["foo", "bar", "some other name"]

The ConvertToDictionary method serializes all values under the same key as a JSON array string, making it easy to handle lists of values in the CLI input as a single serialized JSON array.

4. Parsing Nested Expressions

The ConvertToDictionary method automatically handles nested CLI expressions within the {{$ }} syntax. For example, nested structures within the CLI string will be mapped correctly in the output dictionary.

Patterns Used

The CliFactory uses several regular expression patterns for extracting and processing CLI arguments:

• CLI Template Pattern: Used to isolate the CLI template from larger strings.
• Argument Pattern: Extracts individual CLI arguments.
• Key Pattern: Extracts keys from CLI arguments.
• Value Pattern: Extracts values from CLI arguments.
• Nested Expression Pattern: Detects and encodes nested CLI expressions for easy processing.

License

This library is released under the Apache License 2.0.