lcli

An LFE Command Line Options & Tool Builder

Table of Contents

• Introduction
• Example Usage
• Documentation
• License

Introduction ↟

lcli (pronounced "Elk-ly") is a library for creating command line tools through support of parsing commands, options (flags), and arguments (non-flag parameters). Regular options parsing is done using the Erlang getopt community library. lcli manages the handling of everything else. Two excellet libraries have served as inspiration, from two different programming languages: Rust's clap and Go's kong (with the former having a bigger influence).

Example Usage ↟

A simple script below demonstrates lcli's wrappage of the Erlang getopt library:

#!/usr/bin/env lfe

(include-lib "lcli/include/records.lfe")

(defun options ()
  '(#m(type option long "help" help "Display help text")
    #m(type option long "host" short #\h val-type string default "localhost"
       help "Database server host")
    #m(type option long "port" short #\p val-type integer
       help "Database server port")
    #m(type option long "dbname" val-type string default "users"
       help "Database name")
    #m(type option name xml short #\x help "Output data in XML")
    #m(type option long "verbose" short #\v val-type integer help "Verbosity level")
    #m(type option long "output" short #\o val-type string help "Output file")))

(defun main ()
  (case (lcli:parse (options))
    ((match-parsed app a commands c options os args as)
       (lfe_io:format "App: ~p~nCommands: ~p~nOptions: ~p~nArgs: ~p~n"
                      (list a c os as)))))
  'ok)

(main)

For a more thorough checking of parse results, see ./examples/fake-db.lfe.

Test run:

$ ./examples/db.lfe -x --port 5099 --dbname webapp -o output.dump arg1 arg2

Output:

App: "./examples/fake-db.lfe"
Commands: ()
Options: #M(dbname "webapp" host "localhost" output "output.dump"
            port 5099 xml true)
Args: ("arg1" "arg2")

With these components parsed, a script writter or CLI tool developer has all the information needed to override configuration with options provided by a user.

Usage text is generated through a combination of lcli templates and formatting functions as well as utility functions provided by the getopt library:

 $ ./examples/db.lfe --help

Output:

NAME
  ./examples/fake-db.lfe

SYNOPSIS
  ./examples/fake-db.lfe [--help] [-h [<host>]] [-p <port>]
                         [--dbname [<dbname>]] [-x] [-v <verbose>]
                         [-o <output>]

OPTIONS
  --help         Display help text
  -h, --host     Database server host [default: localhost]
  -p, --port     Database server port
  --dbname       Database name [default: users]
  -x             Output data in XML
  -v, --verbose  Verbosity level
  -o, --output   Output file

Documentation ↟

Project documentation is here.

License ↟

Copyright © 2016-2023 Duncan McGreggor

Distributed under the Apache License, Version 2.0.