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::*;

    let ca = CommandsAggregator::former()
    .grammar(
    [
      Command::former()
      .phrase( "echo" )
      .hint( "prints all subjects and properties" )
      .subject( "Subject", Type::String, true )
      .property( "property", "simple property", Type::String, true )
      .form(),
    ])
    .executor(
    [
      ( "echo".to_owned(), Routine::new( |( args, props )|
      {
        println!( "= Args\n{args:?}\n\n= Properties\n{props:?}\n" );
        Ok( () )
      })),
    ])
    .build();

    let args = std::env::args().skip( 1 ).collect::< Vec< String > >();
    ca.perform( args.join( " " ) ).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

Macros

• parse_args
  Macro for parsing WCA arguments.

Structs

• Args
  Command Args
• Command
  Command descriptor.
• CommandBuilder
  A builder struct for constructing commands.
• 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.
• Context
  Container for contexts values
• ExecutableCommand_
  Represents a command that can be executed, with a list of command subjects and a set of command options, and a callback function that defines the command logic.
• Executor
  Executor that is responsible for executing the program’s commands. It uses the given Context to store and retrieve values during runtime.
• ExecutorConverter
  This is the struct that provides a way to convert a VerifiedCommand to an ExecutableCommand_.
• Input
  A structure representing an input with a single string value.
• Namespace
  Represents a namespace of commands with the specified Command type. This is done to be flexible and not to duplicate code.
• 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.
• Property
  A struct representing a property.
• 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.
• ExecutorType
  Represents the type of executor to use for running commands.
• HelpVariants
  Available help commands variants
• Routine
  Routine handle.
• 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

• CommandExt
  An extension trait for commands.
• CommandParser
  Can parse Commands
• IntoBuilder
  A trait for converting a type into a Builder.
• IntoInput
  A trait for converting various types into Input.
• NamespaceParser
  Can parse Namespaces
• ProgramParser
  Can parser Programs
• TryCast
  Can be implemented for something that represents a type of value

Functions

• ask
  Ask use input from standard input.
• cui
  Creates a command-line interface (CLI) builder with the given initial state.