beef331/commander

Quick and easy CLI doc generator + parser

Commander

Commander is a easy to use CLI documenter and parser.

How to use

import commander
import std/terminal
type Config = ref object
  useColor: bool
  color: ForegroundColor
  countTotal: int


let
  config = Config()
  cmd = initCommander()

genCommand(cmd):
  name("Super Cool CLI") # Gives a name to `cmd`
  header("This is a great little program, that stands for great things") # Gives the cmd a header
  section("Otherly", "This part does some cooool stuff", "That was all the cool stuff it did") # Makes a new section, with header, footer
  flag(short = "c", long = ["count", "countAlias"], desc = "Super fancy int math, totally rad.", typ = int): # Creates a new flag, short emits: `-c:C` long  emits: `--count:COUNT`
    config.countTotal += it # This is emited and is parsed from `typ`
  flag(long = "color", desc = "Chooses the colour to output in the terminal.",
      typ = ForegroundColor):
    case it  # This is emited and is parsed from `typ`
    of fgRed: discard
    else:
      config.color = it
      config.useColor = true
  flag(long = "help", desc = "Shows the help message."): # With no `typ` it's `-h` or `--help`
    let message =
      if config.useColor:
        ansiForegroundColorCode(config.color) & cmd.toCli & ansiResetCode
      else:
        cmd.toCli # Converts the doc to a cli help menu
    echo message
  flag(long = "bleep1", desc = "do bleep1", action = echo "bleep1") # Action can be same lined!
  flag(long = "bleep2", desc = "do bleep2", action = echo "bleep2") # Action can be same lined!
  footer("That's all") # Set's the cmd footer
writeFile("index.html", cmd) # Outputs the cli as html

The example's html

commander's Issues

feedback

a few suggestions:

• shorter syntax, allowing 1 liner flags with optional params, as in karax
• integrate action to take for each command line flag inside the DSL as explained below, to avoid repetitions
• predefine the object we're building so we can refer to it inside the DSL (see genHelpDefault(cmd)) or split the command assembly in multiple parts, even from other modules
• use it as the user flag automatically converted to the type specified in the AST (eg: typ = int), via appropriate generic parse(input: string, T: typedesc): T

type Color = enum {.pure.} on, off, auto
let config = ConfigRef() # user defined side param

import pkg/commander
let cmd = initCommander() # cmd is pre-defined, allowing access to it inside the DSL
genCommand(cmd):
  flag(short = "c", long = ["count", "countAlias"], desc= "some description", typ = int):
    config.countTotal += it # `it` is converted from input flag value to the provided `typ` (`int` in this case)
  flag(long = "colors", desc= "some description", typ = Color):
    case it
    of Color.auto: discard
    else: config.useColor = true
  flag(long = "help", desc= "shows help"):
    genHelpDefault(cmd) # we can access all to all the (serialized) commands, useful for help actions
  flag(long = "bleep1", desc= "do bleep1", action = echo "bleep1")
  flag(long = "bleep2", desc= "do bleep2", action = echo "bleep2")

when defined(cpp):
  # extra commands for cpp, possible since we've pre-defined `cmd`
  genCommand(cmd):
    flag(long = "bleep3", action = echo "bleep3")
when defined(js):
  # we can reuse other modules to build up the command
  from foo import genCommand2
  genCommand2(cmd)

we can render the DSL in different backends, eg:

let html = cmd.toHtml
let str = cmd.toCmdline
let manpage = cmd.toManpage

let me know if anything is unclear :)