io

Seamless Command Line Integration with ZIG.

^{part of SuperZIG/io/terminal module.}

^{🔥 Built for power. Designed for speed. Ready for production. 🔥}

• Features 🌟

  • 📋 Command Management

    Define and handle commands with ease.

  • 🛠️ Option Parsing

    Support for short and long options, with or without values.

  • ❗ Required Options

    Enforce the presence of required options for commands.

  • ⚙️ Optional Options

    Provide flexibility to commands by allowing additional configuration without being mandatory.

  • 🌍 Platform Compatibility

    Supports Windows, Linux and macOS.

• 📖 Table of Contents

  🔹 🚀 Quick Start – A quick guide to get you started with the library.

  🔹 🎇 API Reference – Detailed documentation of available functions.

• Quick Start 🚀

  If you have not already added the library to your project, please review the installation guide for more information.

    const cli = @import("io").terminal.cli;
  

  1. Define Commands and Options

     Now let’s create our command line application, but before that we need to define the commands and options used to handle the user input arguments in the terminal, for example:

      const commands = [_]types.command {
     
          types.command {
              .name   = "test",                           // Name of the command
              .func   = &methods.commands.testFN,         // Function associated with the command
              .req    = &.{ "option1", "option2" },       // Required options for 'test' command
              .opt    = &.{ "option3" },                  // Optional options for 'test' command
          },
     
          types.command {
              .name   = "help",                           // Name of the command
              .func   = &methods.commands.helpFN,         // Function associated with the command
          }
      };
     

     now we have two commands (test and help), the help command can be used without any options but the test command required (option1 and option2) and optionally option3.

     Now lets define the command options.

      const options = [_]types.option {
     
          types.option {
              .name   = "option1",
              .short  = '1',
              .long   = "option1",
          },
     
          types.option {
              .name   = "option2",
              .short  = '2',
              .long   = "option2",
          },
     
          types.option {
              .name   = "option3",
              .short  = '3',
              .long   = "option3",
              .func   = &methods.options.option3FN
          },
      };
     

     After defining the commands and its options, we need to define the handlers.

      const methods = struct {
     
          pub const commands = struct {
     
              pub fn testFN(_options: []const types.option) bool {
                  return true;
              }
     
              pub fn helpFN(_: []const types.option) bool {
                  return true;
              }
          };
     
          pub const options = struct {
              pub fn option3FN(_val : []const u8) bool {
                  return true;
              }
          };
      };
     

  2. Start the CLI Application

     Pass your commands, options, and enable/disable debugging.

      pub fn main() !void {
          try cli.start(&commands, &options, true);
      }
     

  3. Run Your CLI

     Compile and execute your application.

      ./your_app test -1 valOne -2 valTwo -3 valThree
     

  Kickstart your project with our lite-cli template for a swift setup.

• API 🎇

  Index
  Methods
  Types
  Errors

  • ✨ Methods

    Function	Description
    start	Starts the CLI application.

  • 🍃 Types

    slice = []const u8

    • command

      Field	Type	Description
      name	slice	Name of the command.
      func	*const fn ([]const option) bool	Function to execute the command.
      req	[]const slice	Required options.
      opt	[]const slice	Optional options.

    • option

      Field	Type	Description
      name	slice	Name of the option.
      func	*const fn (slice) bool	Function to execute the option.
      short	u8	Short form, e.g., -n/-N
      long	slice	Long form, e.g., –name.
      value	slice	Value of the option.

  • ❌ Errors

    Error
    NoArgsProvided
    UnknownCommand
    UnknownOption
    MissingRequiredOption
    UnexpectedArgument
    CommandExecutionFailed

• 🔗 Related

  • Info

    Detailed terminal information ensuring cross-platform compatibility.

  • settings

    Comprehensive terminal settings for cross-platform compatibility.

  • ansi

    Utility functions for ANSI escape code manipulation and terminal styling.

  • Events

    Robust event handling for terminal key presses and mouse events.

  • Prompt

    Interactive prompts for user input.

This site is open source. Improve this page.