README

   1                                                              -*- outline -*-
   2
   3 * Copyright (C) 2010, 2011 Didier Verna
   4
   5 This file is part of Clon.
   6
   7 Copying and distribution of this file, with or without modification,
   8 are permitted in any medium without royalty provided the copyright
   9 notice and this notice are preserved.
  10
  11
  12 * Introduction
  13 In the Lisp family of languages, one of the key components is the so-called
  14 REPL, the Read-Eval-Print Loop, which blends the runtime, compilation and
  15 development phases together, allowing for a very high level of interaction
  16 with the program. The importance of this paradigm explains why it is still
  17 rare to find "standalone" applications written in Lisp: most Lisp application
  18 clients are lispers themselves, and they prefer to live in the REPL.
  19
  20 On the other hand, many contemporary Common Lisp compilers provide ways of
  21 creating standalone Common Lisp programs, using either shebang technology or
  22 by directly dumping executables. This process is getting easier to achieve
  23 every day. For instance, with SBCL, all it takes is one function call
  24 (save-lisp-and-die) and one command-line option to the compiler (--script).
  25
  26 The (big) size of a Lisp image has been considered a showstopper in creating
  27 standalone applications for a long time, but nowadays, it doesn't really
  28 matter anymore (if you are not convinced, just figure out the average size of
  29 an application bundle under Mac OS X). This, along with the fact that Common
  30 Lisp compilers can generate very efficient code today, makes the perspective
  31 of standalone Common Lisp applications very tempting again.
  32
  33 When it comes to preserving interaction with the user, one of the key
  34 components in a standalone application is the handling of the command-line.
  35 Clon is a library designed to do just that.
  36
  37
  38 * Overview
  39 Clon provides traditional features one might expect from a command-line
  40 options management library, but what makes it somewhat unique in its
  41 conception is that it has been designed with both the application developer
  42 and the application user in mind: many aspects of the command-line management
  43 usually imposed by the program are in fact under the control of the
  44 application user. The idea is that all Clon-enabled applications behave in a
  45 uniform way, and that it is the user who gets to decide, not the developper.
  46 The most important features of Clon are listed below.
  47
  48 ** Command-Line Syntax
  49 Clon imposes a particular yet flexible syntax for the command-line. Options
  50 have short and/or long names, beginning with either one or two dashes. Options
  51 may take an argument. In that case, the argument may be optional or mandatory.
  52 Option names may be abbreviated and one-character options may be grouped
  53 together in a single call. There is an additional call syntax for Boolean or
  54 Boolean-based options. Finally, the command-line may have a "postfix", that
  55 is, a non-option part.
  56
  57 ** Option Types
  58 Clon comes with a set of predefined option types, including "flags" (option
  59 without arguments), "switches" (Boolean options), simple Lisp objects, simple
  60 strings, enumerations, pathnames etc. Clon is also extensible: it is possible
  61 to define new option types, either from scratch or by subclassing an existing
  62 one.
  63
  64 ** Value Retrieval
  65 The traditional approach to command-line analysis is to process it
  66 sequentially, and Clon lets you do that. However, Clon also provides an
  67 explicit retrieval mechanism by which you can directly request the value of a
  68 specific option, regardless of its position, or even its presence on the
  69 command-line. An option's value can be retrieved from different sources: a
  70 command-line argument, a "fallback" value (for optional arguments), a default
  71 value or an environment variable associated with the option. The retrieval
  72 process is completely automated, hence removing this burden from the
  73 developer's shoulders.
  74
  75 ** Error Management
  76 Another cumbersome task already taken care of is error management. Clon
  77 provides two built-in error management schemes, in case something is wrong on
  78 the command-line. The simplest one is to quit the application with an
  79 informative error message. The other one is to enter an interactive dialog
  80 with the user, in which it is possible to fix the problem (correct a typo,
  81 discard an option call, provide a missing argument or value etc.). A unique
  82 feature of Clon is that the application user may choose his or her preferred
  83 error management scheme.
  84
  85 ** Help String Contents
  86 The "help string" is typically what you expect from the output of a --help
  87 option. Maintaining an up-to-date help string is a very boring task, so Clon
  88 completely automates this for you (another burden removed from the developer's
  89 shoulders). However, the application programmer still has control over the
  90 help string's contents, notably the order in which options are displayed, and
  91 also by having the possibility of grouping options together and inserting
  92 arbitrary text in the output.
  93
  94 ** Help String Format
  95 Clon also completely automates the help string typesetting process. For
  96 instance, it can automatically format the output for 80 columns, but it is
  97 also aware of the tty geometry and will use it when appropriate. Clon also
  98 supports help string "fontification" (or "highlighting") through ISO/IEC 6429
  99 SGR escape sequences on tty's that support it. Another unique feature of Clon
 100 is that the exact format and highlight specification for the help string is
 101 under the control of the application user, via the notion of "theme". Clon
 102 comes with a set of predefined themes (for instance, standard, with heavy
 103 fontification, refcard for quick reference etc.) and application users can
 104 define their own. As a matter of fact, a theme not only controls the format
 105 and highlight of the help string, but also its contents.
 106