kicker Manual

Table of Contents

1. Introduction
2. Basic Setup
3. Parameter Types
   • Positional Arguments
   • Optional Arguments (Flags with Values)
   • Flag Arguments (Boolean Toggles)
   • Rest / Variadic Arguments (Multiple Values)
   • Repeated Options (Multiple Flags)
4. Automatic Help System & Docstrings
5. Creating Multi-Command Applications (Subcommands)

---

Introduction

kicker is a Macro-based Command-Line Interface (CLI) Parser for the Nim programming language designed for ease of use, speed, and reduced boilerplate.

The primary feature of kicker is its ability to read parameter signatures from a proc and automatically transform them into a CLI tool structure, including an automatic help system (--help) generated from the function's docstring.

---

Basic Setup

To begin, import kicker, apply the {.kicker.} macro to your desired proc, and call dispatch() at the end of the runtime.

Example main.nim

import kicker

proc main(data: float, Flag: bool) {.kicker.} =
  """
  data: Float data to be multiplied by 2.
  flag: Boolean flag to be passed to the proc.
  """
  echo "Testing Kicker"
  echo "Data x 2 = ", data * 2
  if flag:
    echo "Flag was passed!"

# Call the dispatcher to process command line arguments
dispatch("A basic kicker usage demo.")

When compiled and executed:

$ ./main 15.5 --flag
# Output:
# Testing Kicker
# Data x 2 = 31.0
# Flag was passed!

---

Parameter Types

kicker supports five styles of command-line parameters, defined by the variable types and defaults in the proc signature.

1. Automatic Short Flags (Abbreviations)

kicker automatically generates short flags by extracting all uppercase letters from the parameter name. The full flag name is the parameter name converted to lowercase.

Examples:

• Flag: bool (Uppercase F) $\rightarrow$ --flag and -f
• VerboseMode: bool (Uppercase V, M) $\rightarrow$ --verbosemode and -vm
• ServerPort: int = 8080 (Uppercase S, P) $\rightarrow$ --serverport and -sp

⚠️ Important: Parameter names containing uppercase letters are converted to all-lowercase when passed into the proc body. You must reference them in lowercase (e.g., use if verbosemode: instead of if VerboseMode:).

---

2. Positional Arguments

Mandatory parameters that depend on their position in the command. Define these by declaring a variable without a default value.

proc add(a: int, b: int) {.kicker.} =
  echo a + b

Usage:

$ ./main add 5 10
# 15

3. Optional Arguments

Optional parameters requiring a flag (e.g., --name). Define these by providing a Default Value.

💡 Note: Uppercase letters still generate automatic short flags (e.g., FirstName becomes -fn).

proc greet(Name: string = "World") {.kicker.} =
  echo "Hello ", name

Usage:

$ ./main greet --name Nim
# Hello Nim

4. Flag Arguments (Boolean)

Toggles for true/false values. If the flag is present, it is true. Define these using the bool type without a default value.

proc verboseMode(Verbose: bool) {.kicker.} =
  if verbose:
    echo "Verbose is ON"
  else:
    echo "Verbose is OFF"

5. Rest / Variadic Arguments

Used for an indefinite number of values at the end of a command. Define this using a seq[t] type without a default value.

proc showFiles(files: seq[string]) {.kicker.} =
  for f in files:
    echo f

6. Repeated Options

Used when the same flag can be called multiple times. Define this using a seq[t] type with an empty array default @[].

proc connect(Server: seq[string] = @[], Port: seq[int] = @[]) {.kicker.} =
  echo "Servers: ", server
  echo "Ports: ", port

---

Automatic Help System & Docstrings

kicker uses Docstrings (""" ... """) to generate help messages using the format variable_name: description.

proc download(Url: string, Output: string = "out.bin") {.kicker.} =
  """
  Downloads a file from the internet.
  url: The destination link of the file.
  output: The filename to save locally.
  """
  discard

Resulting Help Output:

$ ./main download -h
Usage: main download <url> [--output <val>]

Downloads a file from the internet.

Arguments:
  url <string>           The destination link of the file.

Options:
  -o, --output <string>  The filename to save locally. [default: out.bin]

---

Creating Multi-Command Applications (Subcommands)

For complex tools (like git or docker), create multiple procs with the {.kicker.} macro and call dispatch(helpMsg) once.

proc build() {.kicker.} =
  """Compiles the project."""
  echo "building..."

proc run() {.kicker.} =
  """Runs the program."""
  echo "running..."

dispatch("Nim Project Manager (NPM)")