Yamamari.ShellSharp 1.0.257

Shell Sharp by Yamamari

This library provides a framework for creating very simple classes that can be invoked by the command line. This can make it very easy to create a set of actions that are easy to interact with and automate with relatively little effort.

Structure of Invocation

The basic structure to invoke a script looks like this. Not every class will have arguments and the property names will often have aliases to make console interactions faster and easier.

className argument -propertyName propertyValue

Help

A script exists to provide transparency regarding the available scripts and how to invoke them. It is the Help script, which also has the alias of ?.

Optionally you can pass it the verbose parameter -v or specify the name of a script you'd like more information about -n NameOfScript.

Creating a Script

Any class becomes an invokable script by implementing the interface IShellScript. The shell engine will find these when it loads and will make them available to invoke via the command line.

One important warning - if two scripts have the same name (including aliases) the shell engine will be unable to process any commands.

Sample Script

using Yamamari.ShellSharp;

namespace Yamamari.Yo;

public class HelloWorld : IShellScript
{
    public void Run(IShell shell)
    {
        shell.Say("Hello! World!");
    }
}

Loading the Shell

You can get access to the shell by requesting one get created.

var shell = Shell.GetShell();

You may also specify specific assemblies you'd like it to parse in order to find additional scripts for execution.

var thisAssembly = typeof(Program).Assembly;
var shell = Shell.GetShell(thisAssembly);

Lastly, you can create a shell given a local directory and it will find all scripts across all assemblies at the specified location.

var thisDirectory = Environment.CurrentDirectory;
var shell = Shell.GetShell(thisDirectory);

At this point, you can invoke the shell to either interact with the UI or to run scripts:

shell.Run(args);

Below you'll find a sample program you could make your main program file and all scripts located within your assembly will be available for executing on a loop until you exit the loop.

Sample Program

// See https://aka.ms/new-console-template for more information

using Yamamari.ShellSharp;
using Yamamari.ShellSharp.UserExperience.Enumerations;

var shell = Shell.GetShell(typeof(Program).Assembly);
while (true)
{
    shell.Clear();
    TryRunNextCommand();
    if (!ShouldWeContinue(shell))
    {
        return;
    }
}

void TryRunNextCommand()
{
    try
    {
        RunNextCommand();
    }
    catch (Exception e)
    {
        shell.Say(e.Message, TextColor.Red);
    }
}

void RunNextCommand()
{
    var action = shell.Ask("What shall we do?");
    if (!string.IsNullOrWhiteSpace(action))
    {
        shell.Run(action);
    }
}

bool ShouldWeContinue(IUx ux)
{
    const string question = "Press 'x' to exit (or any other key to continue):";
    while (true)
    {
        ux.Say();
        ux.Say();
        var answer = ux.Ask(question, true);
        if (answer == "x")
        {
            return false;
        }
        
        return true;
    }
}

Decorators

You can add attributes to your scripts and their properties in order to simplify your interactions further.

• [HelpText] this attribute can be on scripts or their properties. The help script will display this text when users are asking for help.
• [Required] on a property will stop the script from being run if that property is missing
• [Flag] will modify a boolean property so that if the property is indicated in the command line without a value being provided, the value will be interpretted as true
• [Argument] specifies A SINGLE PROPERTY (only one) as the property that holds all 'argument' values - those provided without an associated parameter
• [GreaterThan("value")] For this attribute you can specify either the name of another property of the same type, or provide the string version of a concrete value that the input must be greater than for the script to be invoked
• [LesserThan("value")] Exact same as the greater than attribute, but with the comparison reversed.

Custom Decorators

You can create your own custom decorators that the shell engine will also evaluate prior to running the scripts. These fall into two categories:

1. Special processing happens first. These can change the value of a property before other actions are taken. You can create these by making attributes that inherit from SpecialProcessingAttribute
2. Business rules happen second. These will stop execution if they return false. You can make these by creating your own attribute classes that inherit from the abstract base of BusinessRuleAttribute.

Custom Mediums

By default, the shell interacts with the Console. You can override this and provide your own medium for interaction by creating a class that implements the interface IInteractionMedium and passing this to your shell.

shell.Medium = instanceOfMyCustomMedium;

Backlog

• Arguments