Table of Contents

Class CommandRouteParser

Namespace
OneImlx.Terminal.Commands.Parsers
Assembly
OneImlx.Terminal.dll

Represents a default command-line parser for processing terminal commands based on defined descriptors.

public class CommandRouteParser : ICommandRouteParser
Inheritance
CommandRouteParser
Implements
Inherited Members

Remarks

The default command-line parser is designed for extensive command line parsing. Key features include:

Configurable Elements: Adapts to various command structures with configurable separators, delimiters, and option prefixes.

Segmentation and Queue: Segregates the command input string to separate commands/arguments from options. Segments are efficiently processed using a queue.

Command Parsing: Commands provide context for subsequent segments and must always precede arguments and options. The parser recognizes root commands, command groups, and subcommands.

Hierarchical Parsing (Optional): Allows a hierarchical command structure with root, group, and subcommands. Note: Hierarchical parsing may affect the overall complexity of the parsing process.

Argument Parsing: Command arguments are processed before options. Any segment after the identified command, and that isn't recognized as an option or its alias, is treated as an argument. It's imperative that the provided arguments for a command don't exceed what its descriptor anticipates.

Option Parsing: Options follow arguments. The parser initially seeks the starting point of options in the input string. Once identified, each option, recognized by its prefix or alias prefix, is segmented using the option value separator. For an option to be valid, it must be defined in the command's descriptor.

Efficiency and Complexity: The parser's efficiency is derived from a combination of string operations and the sequential processing of segments. The initial identification of the starting point of options using `IndexOf` and subsequent `Substring` operations have a time complexity of O(n), where n is the length of the input string. The `Split` operations, both for commands/arguments and options, add another O(n). Processing segments through queue operations like Enqueue, Peek, and Dequeue have constant time complexities (O(1)) for each operation, but the cumulative time complexity across all segments remains O(n). Thus, considering all these operations, the overall complexity for the parsing process can be approximated as O(n). While the parser is designed to be comprehensive and handle a variety of command line structures efficiently, the actual performance can vary based on the intricacies of specific command structures and their length. It is always recommended to measure the parser's performance against real-world scenarios to assess its suitability for specific applications.

Potential Errors:

  • invalid_command: Occurs when multiple roots are detected in the command hierarchy.
  • missing_command: Raised when a command group is detected without a preceding root command.
  • invalid_request: Triggered by nested subcommands or an unrecognized command descriptor type.
  • unsupported_argument: Emitted when the command does not recognize the provided arguments or when the provided arguments surpass the number described in the command's descriptor.
  • unsupported_option: Resulted when an option or its alias isn't validated by the command's descriptor.
  • invalid_option: Happens when an option's ID is prefixed in the manner of an alias or the reverse.

Developer Note: While the default parser is optimized for a diverse set of command-line scenarios, if you possess a highly specialized or simplified parsing requirement, it might be beneficial to implement a custom parser. Nonetheless, it's advisable to thoroughly understand the capabilities and efficiency of this parser before transitioning to a custom implementation.

Constructors

CommandRouteParser(ITerminalTextHandler, ITerminalCommandStore, TerminalOptions, ILogger<CommandRouteParser>)

Initializes a new instance of the CommandRouteParser class.

public CommandRouteParser(ITerminalTextHandler textHandler, ITerminalCommandStore commandStore, TerminalOptions terminalOptions, ILogger<CommandRouteParser> logger)

Parameters

textHandler ITerminalTextHandler

The text handler.

commandStore ITerminalCommandStore

The command store handler.

terminalOptions TerminalOptions

The terminal configuration options.

logger ILogger<CommandRouteParser>

The logger.

Exceptions

TerminalException

This exception is designed to capture a myriad of parsing issues such as unrecognized commands, unexpected number of arguments, or misidentified options.

Methods

ParseRouteAsync(CommandRoute)

Asynchronously parses a given input into structured command data.

public Task<ParsedCommand> ParseRouteAsync(CommandRoute commandRoute)

Parameters

commandRoute CommandRoute

Returns

Task<ParsedCommand>

Remarks

This method provides a comprehensive solution for parsing terminal commands, offering developers the ability to extract relevant descriptors, options, and arguments from the provided input in an efficient manner.

Complexity Analysis:

The parsing process employs several phases, each with its own complexity:
  • Initial String Split and Queue Construction: The input string undergoes a preliminary split into segments. This operation's complexity is O(s), where s represents the length of the input string. Post splitting, segments are enqueued for orderly processing. The use of the Queue data structure ensures that segments are processed in a first-in-first-out manner, optimizing the parsing flow and ensuring order preservation.
  • Command, Argument, and Option Extraction: After the queue is populated, each segment is dequeued and evaluated sequentially to determine if it represents a command, option, or argument. The complexity of processing each segment is linear, O(n), where n is the number of segments.
  • Hierarchy Parsing (Optional): If hierarchy extraction is enabled, a command hierarchy is established. Its complexity, in the worst case, is linear with respect to the number of parsed command descriptors, O(m).
When taking into account all phases, the effective complexity of the algorithm is O(s + n), where the emphasis is on the fact that each segment is processed only once post splitting. This showcases the algorithm's efficiency, making it a robust choice for parsing terminal commands. However, developers should consider their specific parsing requirements. If you have simpler parsing needs, a custom implementation might allow for further optimizations. But for diverse and comprehensive parsing scenarios, this default implementation provides a well-rounded and efficient solution.

Exceptions

TerminalException

This exception is designed to capture a myriad of parsing issues such as unrecognized commands, unexpected number of arguments, or misidentified options.

Edit this page