#+title: cli

 #+author: Richard Westhaver

 #+description: Command-line Interface Library

 #+setupfile: ../../../clean.theme

 #+filetags: lisp cli

 #+property: header-args :dir ~/comp/core/ :exports both

 #+setupfile: ../../../clean.theme

 * Overview

 :PROPERTIES:

 :ID:       fb7c1b49-e293-41b7-863c-f38eaa361080

 :END:

 The =cli= library is a fully-featured toolkit for working with and

 building [[https://en.wikipedia.org/wiki/Command-line_interface][CLI]] programs.

 ** dependencies

 :PROPERTIES:

 :ID:       5d0f369d-5de0-41b1-8288-2633a84c3a42

 :END:

 #+begin_src lisp :results list

   (ql:quickload :doc)

   (let ((sys (asdf:find-system :cli)))

     (asdf:system-depends-on sys))

 #+end_src

 #+RESULTS:

 - std

 - log

 - dat

 - obj

 ** dependents

 :PROPERTIES:

 :ID:       6c86510a-2c59-48a6-91c3-8533ceb0dcda

 :END:

 #+begin_src lisp :results list

   (ql:quickload :doc)

   (let ((sys (doc:system-documentation :cli)))

     (mapcar (lambda (s) (asdf:component-name (doc:doc-system s))) (doc:doc-dependents sys)))

 #+end_src

 #+RESULTS:

 - user

 - prelude

 - packy

 - box

 - pod

 - net

 - vc

 - skel

 - cli/tests

 - core/lib

 ** files

 :PROPERTIES:

 :ID:       dc23dd4f-6025-40cb-90c7-982def7ef530

 :END:

 #+begin_src lisp :output replace :results list

   (mapcar (lambda (p)

               (enough-namestring p (asdf:system-source-directory :cli)))

             (doc:doc-files (doc:system-documentation :cli)))

 #+end_src

 #+RESULTS:

 - pkg.lisp

 - ansi.lisp

 - env.lisp

 - progress.lisp

 - spark.lisp

 - repl.lisp

 - shell.lisp

 - prompt.lisp

 - ed.lisp

 - tools/pkg.lisp

 - tools/term.lisp

 - tools/tmux.lisp

 - tools/pacman.lisp

 - tools/cc.lisp

 - tools/systemd.lisp

 - tools/wg.lisp

 - tools/cargo.lisp

 - tools/sbcl.lisp

 - clap/pkg.lisp

 - clap/ast.lisp

 - clap/vars.lisp

 - clap/util.lisp

 - clap/macs.lisp

 - clap/proto.lisp

 - clap/opt.lisp

 - clap/cmd.lisp

 - clap/cli.lisp

 - cli.lisp

 ** packages

 :PROPERTIES:

 :ID:       c62cb04c-1c86-4bbe-bd1e-b962c887b008

 :END:

 #+begin_src lisp :output replace :results list

   (mapcar (lambda (p) (package-name (doc:doc-package p)))

           (doc:doc-packages (doc:system-documentation :cli)))

 #+end_src

 #+RESULTS:

 - CLI/REPL

 - CLI/CLAP/UTIL

 - CLI/CLAP/PROTO

 - CLI/TOOLS/PACMAN

 - CLI/CLAP/OBJ

 - CLI/ENV

 - CLI/CLAP/MACS

 - CLI/TOOLS/SBCL

 - CLI/TOOLS/WG

 - CLI/TOOLS/SYSTEMD

 - CLI/PROMPT

 - CLI-USER

 - CLI/PROGRESS

 - CLI/CLAP

 - CLI/TOOLS/TMUX

 - CLI/TESTS

 - CLI/ANSI

 - CLI/SPARK

 - CLI/TOOLS/TERM

 - CLI/CLAP/AST

 - CLI/CLAP/VARS

 - CLI/ED

 - CLI/TOOLS/CARGO

 - CLI/CLAP/SIMPLE

 - CLI/TOOLS/CC

 - CLI

 - CLI/SHELL

 ** tests

 :PROPERTIES:

 :ID:       7fa7ae69-b3a0-4bdf-907c-dacb25cb3662

 :END:

 #+begin_src lisp :output replace

   (ql:quickload :cli/tests)

   (rt:in-suite :cli)

   (print rt:*test-suite* nil)

 #+end_src

 #+RESULTS:

 : #<RT:TEST-SUITE CLI [11:11:0:0] {1003038B23}>

 #+begin_src lisp :output replace

   (rt:tests rt:*test-suite*)

 #+end_src

 #+RESULTS:

 #+begin_example

 (#<RT:TEST SBCL-TOOLS :fn SBCL-TOOLS-TEST787 {100303C973}>

  #<RT:TEST CLAP-MAIN :fn CLAP-MAIN-TEST786 {100303C8E3}>

  #<RT:TEST CLI-AST :fn CLI-AST-TEST785 {100303C823}>

  #<RT:TEST ENV :fn ENV-TEST784 {100303C793}>

  #<RT:TEST REPL :fn REPL-TEST783 {100303C703}>

  #<RT:TEST SPARK :fn SPARK-TEST782 {100303C673}>

  #<RT:TEST PROGRESS :fn PROGRESS-TEST781 {100303C5E3}>

  #<RT:TEST CLAP-OPTS :fn CLAP-OPTS-TEST780 {100303C553}>

  #<RT:TEST CLAP-BASIC :fn CLAP-BASIC-TEST779 {100303C493}>

  #<RT:TEST CLI-PROMPT :fn CLI-PROMPT-TEST778 {1003038F83}>

  #<RT:TEST ANSI :fn ANSI-TEST777 {1003038D33}>)

 #+end_example

 * Packages

 ** cli/clap

 - nicknames :: clap

 =clap= is a name borrowed from the [[https://github.com/clap-rs/clap][clap.rs]] Command Line Argument

 Parser. What can I say, it's a good acronym.

 Besides the system tests, you can find this package used in our lisp

 applications (=lisp/bin=).

 =clap= provides an object protocol and classes which parse input into

 a simple AST and execute the appropriate option and command handlers.

 Several macros form the public API used to build a CLI including

 =defcommand=, =defopt=, =define-cli=, and =defmain=.