changelog shortlog graph tags branches changeset files revisions annotate raw help

Mercurial > org > docs / core/lib/cli.org

changeset 48: 9f2e9e647333
parent: 517e7b6fb42d
child: 8e71b315fca2
author: Richard Westhaver <ellis@rwest.io>
date: Sat, 07 Sep 2024 22:34:47 -0400
permissions: -rw-r--r--
description: core documentation and stats 
     1 #+title: cli
     2 #+author: Richard Westhaver
     3 #+description: Command-line Interface Library
     4 #+setupfile: ../../../clean.theme
     5 #+filetags: lisp cli
     6 #+property: header-args :dir ~/comp/core/ :exports both
     7 #+setupfile: ../../../clean.theme
     8 * Overview
     9 :PROPERTIES:
    10 :ID:       fb7c1b49-e293-41b7-863c-f38eaa361080
    11 :END:
    12 The =cli= library is a fully-featured toolkit for working with and
    13 building [[https://en.wikipedia.org/wiki/Command-line_interface][CLI]] programs.
    14 ** dependencies
    15 :PROPERTIES:
    16 :ID:       5d0f369d-5de0-41b1-8288-2633a84c3a42
    17 :END:
    18 #+begin_src lisp :results list
    19   (ql:quickload :doc)
    20   (let ((sys (asdf:find-system :cli)))
    21     (asdf:system-depends-on sys))
    22 #+end_src
    23 
    24 #+RESULTS:
    25 - std
    26 - log
    27 - dat
    28 - obj
    29 
    30 ** dependents
    31 :PROPERTIES:
    32 :ID:       6c86510a-2c59-48a6-91c3-8533ceb0dcda
    33 :END:
    34 #+begin_src lisp :results list
    35   (ql:quickload :doc)
    36   (let ((sys (doc:system-documentation :cli)))
    37     (mapcar (lambda (s) (asdf:component-name (doc:doc-system s))) (doc:doc-dependents sys)))
    38 #+end_src
    39 
    40 #+RESULTS:
    41 - user
    42 - prelude
    43 - packy
    44 - box
    45 - pod
    46 - net
    47 - vc
    48 - skel
    49 - cli/tests
    50 - core/lib
    51 
    52 ** files
    53 :PROPERTIES:
    54 :ID:       dc23dd4f-6025-40cb-90c7-982def7ef530
    55 :END:
    56 #+begin_src lisp :output replace :results list
    57   (mapcar (lambda (p)
    58               (enough-namestring p (asdf:system-source-directory :cli)))
    59             (doc:doc-files (doc:system-documentation :cli)))
    60 #+end_src
    61 
    62 #+RESULTS:
    63 - pkg.lisp
    64 - ansi.lisp
    65 - env.lisp
    66 - progress.lisp
    67 - spark.lisp
    68 - repl.lisp
    69 - shell.lisp
    70 - prompt.lisp
    71 - ed.lisp
    72 - tools/pkg.lisp
    73 - tools/term.lisp
    74 - tools/tmux.lisp
    75 - tools/pacman.lisp
    76 - tools/cc.lisp
    77 - tools/systemd.lisp
    78 - tools/wg.lisp
    79 - tools/cargo.lisp
    80 - tools/sbcl.lisp
    81 - clap/pkg.lisp
    82 - clap/ast.lisp
    83 - clap/vars.lisp
    84 - clap/util.lisp
    85 - clap/macs.lisp
    86 - clap/proto.lisp
    87 - clap/opt.lisp
    88 - clap/cmd.lisp
    89 - clap/cli.lisp
    90 - cli.lisp
    91 
    92 ** packages
    93 :PROPERTIES:
    94 :ID:       c62cb04c-1c86-4bbe-bd1e-b962c887b008
    95 :END:
    96 #+begin_src lisp :output replace :results list
    97   (mapcar (lambda (p) (package-name (doc:doc-package p)))
    98           (doc:doc-packages (doc:system-documentation :cli)))
    99 #+end_src
   100 
   101 #+RESULTS:
   102 - CLI/REPL
   103 - CLI/CLAP/UTIL
   104 - CLI/CLAP/PROTO
   105 - CLI/TOOLS/PACMAN
   106 - CLI/CLAP/OBJ
   107 - CLI/ENV
   108 - CLI/CLAP/MACS
   109 - CLI/TOOLS/SBCL
   110 - CLI/TOOLS/WG
   111 - CLI/TOOLS/SYSTEMD
   112 - CLI/PROMPT
   113 - CLI-USER
   114 - CLI/PROGRESS
   115 - CLI/CLAP
   116 - CLI/TOOLS/TMUX
   117 - CLI/TESTS
   118 - CLI/ANSI
   119 - CLI/SPARK
   120 - CLI/TOOLS/TERM
   121 - CLI/CLAP/AST
   122 - CLI/CLAP/VARS
   123 - CLI/ED
   124 - CLI/TOOLS/CARGO
   125 - CLI/CLAP/SIMPLE
   126 - CLI/TOOLS/CC
   127 - CLI
   128 - CLI/SHELL
   129 
   130 ** tests
   131 :PROPERTIES:
   132 :ID:       7fa7ae69-b3a0-4bdf-907c-dacb25cb3662
   133 :END:
   134 #+begin_src lisp :output replace
   135   (ql:quickload :cli/tests)
   136   (rt:in-suite :cli)
   137   (print rt:*test-suite* nil)
   138 #+end_src
   139 
   140 #+RESULTS:
   141 : #<RT:TEST-SUITE CLI [11:11:0:0] {1003038B23}>
   142 
   143 #+begin_src lisp :output replace
   144   (rt:tests rt:*test-suite*)
   145 #+end_src
   146 
   147 #+RESULTS:
   148 #+begin_example
   149 (#<RT:TEST SBCL-TOOLS :fn SBCL-TOOLS-TEST787 {100303C973}>
   150  #<RT:TEST CLAP-MAIN :fn CLAP-MAIN-TEST786 {100303C8E3}>
   151  #<RT:TEST CLI-AST :fn CLI-AST-TEST785 {100303C823}>
   152  #<RT:TEST ENV :fn ENV-TEST784 {100303C793}>
   153  #<RT:TEST REPL :fn REPL-TEST783 {100303C703}>
   154  #<RT:TEST SPARK :fn SPARK-TEST782 {100303C673}>
   155  #<RT:TEST PROGRESS :fn PROGRESS-TEST781 {100303C5E3}>
   156  #<RT:TEST CLAP-OPTS :fn CLAP-OPTS-TEST780 {100303C553}>
   157  #<RT:TEST CLAP-BASIC :fn CLAP-BASIC-TEST779 {100303C493}>
   158  #<RT:TEST CLI-PROMPT :fn CLI-PROMPT-TEST778 {1003038F83}>
   159  #<RT:TEST ANSI :fn ANSI-TEST777 {1003038D33}>)
   160 #+end_example
   161 * Packages
   162 ** cli/clap
   163 - nicknames :: clap
   164 
   165 =clap= is a name borrowed from the [[https://github.com/clap-rs/clap][clap.rs]] Command Line Argument
   166 Parser. What can I say, it's a good acronym.
   167 
   168 Besides the system tests, you can find this package used in our lisp
   169 applications (=lisp/bin=).
   170 
   171 =clap= provides an object protocol and classes which parse input into
   172 a simple AST and execute the appropriate option and command handlers.
   173 
   174 Several macros form the public API used to build a CLI including
   175 =defcommand=, =defopt=, =define-cli=, and =defmain=.