Crate wca

Module :: wca

The tool to make CLI ( commands user interface ). It is able to aggregate external binary applications, as well as functions, which are written in your language.

Sample

#[ cfg( not( feature = "no_std" ) ) ]
{
    use wca::{ Args, Context, Type };

    fn main()
    {

      let ca = wca::CommandsAggregator::former()
      .command( "echo" )
        .hint( "prints all subjects and properties" )
        .subject().hint( "Subject" ).kind( Type::String ).optional( true ).end()
        .property( "property" ).hint( "simple property" ).kind( Type::String ).optional( true ).end()
        .routine( | args : Args, props | { println!( "= Args\n{args:?}\n\n= Properties\n{props:?}\n" ) } )
        .end()
      .command( "inc" )
        .hint( "This command increments a state number each time it is called consecutively. (E.g. `.inc .inc`)" )
        .routine( | ctx : Context | { let i : &mut i32 = ctx.get_or_default(); println!( "i = {i}" ); *i += 1; } )
        .end()
      .command( "error" )
        .hint( "prints all subjects and properties" )
        .subject().hint( "Error message" ).kind( Type::String ).optional( true ).end()
        .routine( | args : Args | { println!( "Returns an error" ); Err( format!( "{}", args.get_owned::< String >( 0 ).unwrap_or_default() ) ) } )
        .end()
      .command( "exit" )
        .hint( "just exit" )
        .routine( || { println!( "exit" ); std::process::exit( 0 ) } )
        .end()
      .perform();

      let args = std::env::args().skip( 1 ).collect::< Vec< String > >();
      ca.perform( args ).unwrap();

    }
}

To add to your project

cargo add wca

Try out from the repository

git clone https://github.com/Wandalen/wTools
cd wTools
cd examples/wca_trivial
cargo run

Diagrams

Class diagram

• Parser

This component takes in raw strings of text and converts them into ParsedCommand objects. These objects contain all of the information needed to represent a command, but they haven’t been validated or processed in any way yet.

• Grammar

Contains available commands configured by the user.

Once the ParsedCommand objects have been generated, the Grammar component steps in. This component takes in the ParsedCommand-s and converts them into VerifiedCommand objects, which contain subject and property values that have been validated against a set of pre-defined grammar. This ensures that the user’s input is structured correctly and can be understood by the system.

• Executor

Contains available routines configured by the user.

Once the VerifiedCommand objects have been generated, the Executor component takes over. This component converts the GrammarCommands into ExecutableCommand_ objects, which contain the actual routines that will be executed at runtime. This is where the system takes action based on the user’s input.

• CommandsAggregator

Finally, the CommandsAggregator component brings everything together. This component is responsible for configuring the Parser, Grammar, and Executor components based on the user’s needs. It also manages the entire pipeline of processing, from parsing the raw text input to executing the final command(parse -> validate -> execute).

Sequence diagram

Modules

• ca
  Commands aggregator library.
• exposed
  Exposed namespace of the module.
• orphan
  Orphan namespace of the module.
• prelude
  Prelude to use essentials: use my_module::prelude::*.
• protected
  Protected namespace of the module.
• wtools
  Tools

Structs

• Args
  Command Args
• Command
  Command descriptor.
• CommandFormer
  Object to form Command. If field’s values is not set then default value of the field is set.
• CommandsAggregator
  The CommandsAggregator struct is responsible for aggregating all commands that the user defines, and for parsing and executing them. It is the main entry point of the library.
• CommandsAggregatorFormer
  Object to form CommandsAggregator. If field’s values is not set then default value of the field is set.
• Context
  Container for contexts values
• Dictionary
  A collection of commands.
• Executor
  Executor that is responsible for executing the program’s commands. It uses the given Context to store and retrieve values during runtime.
• Handler
  Routine handle.
• Input
  A structure representing an input with a single string value.
• ParsedCommand
  Represents a parsed command that has been extracted from an input string by a Parser.
• Parser
  Parser provides parsing command strings into ParsedCommand objects. It allows you to specify the symbols that will be used to interpret the command string, such as the command delimiter, property delimiter, and namespace delimiter.
• Program
  Represents a program that contains one or more namespaces, where each namespace contains a list of commands.
• Props
  Command Properties
• Runtime
  Represents the state of the program’s runtime, including the current context, execution position, and namespace of executable commands.
• RuntimeState
  State of a program runtime
• VerifiedCommand
  Represents a grammatically correct command with a phrase descriptor, a list of command subjects, and a set of command options.
• Verifier
  Converts a ParsedCommand to a VerifiedCommand by performing validation and type casting on values.

Enums

• Error
  Errors that can occur in application.
• HelpVariants
  Available help commands variants
• Routine
  Represents different types of routines.
• Type
  Available types that can be converted to a Value
• ValidationError
  Validation errors that can occur in application.
• Value
  Container for a Value of a specific type

Traits

• CommandParser
  Can parse Commands
• IntoInput
  A trait for converting various types into Input.
• ProgramParser
  Can parser Programs
• TryCast
  Can be implemented for something that represents a type of value

Functions

• ask
  Ask use input from standard input.