Crate wca

source ·
Expand description

§Module :: wca

experimental rust-status docs.rs Open in Gitpod discord

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::{ VerifiedCommand, 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( | o : VerifiedCommand | { println!( "= Args\n{:?}\n\n= Properties\n{:?}\n", o.args, o.props ) } )
        .end()
      .command( "error" )
        .hint( "prints all subjects and properties" )
        .subject().hint( "Error message" ).kind( Type::String ).optional( true ).end()
        .routine( | o : VerifiedCommand | { println!( "Returns an error" ); Err( format!( "{}", o.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§

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

Structs§

  • Command Args
  • Command descriptor.
  • Structure to form Command. Represents a forming entity designed to construct objects through a builder pattern.
  • 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.
  • Structure to form CommandsAggregator. Represents a forming entity designed to construct objects through a builder pattern.
  • Container for contexts values
  • A collection of commands.
  • Executor that is responsible for executing the program’s commands. It uses the given Context to store and retrieve values during runtime.
  • Routine handle.
  • A structure representing an input with a single string value.
  • Represents a parsed command that has been extracted from an input string by a Parser.
  • Parser is a struct used for parsing data.
  • Represents a program that contains one or more namespaces, where each namespace contains a list of commands.
  • Command Properties
  • Represents a grammatically correct command with a phrase descriptor, a list of command subjects, and a set of command options.
  • Converts a ParsedCommand to a VerifiedCommand by performing validation and type casting on values.

Enums§

  • Errors that can occur in application.
  • Available help commands variants
  • Order of commands and properties.
  • Represents different types of routines.
  • Available types that can be converted to a Value
  • Validation errors that can occur in application.
  • Container for a Value of a specific type

Traits§

  • A trait for converting various types into Input.
  • Can be implemented for something that represents a type of value

Functions§

  • Ask use input from standard input.