descriptionCommand-Line Options Nuker
homepage URLhttp://www.lrde.epita.fr/~didier/software/lisp/clon.php
repository URLhttp://www.lrde.epita.fr/~didier/software/lisp/clon/clon.git
ownertrebbu@googlemail.com
last changeTue, 16 Apr 2013 16:08:44 +0000 (16 18:08 +0200)
last refreshSun, 19 Nov 2017 15:26:33 +0000 (19 16:26 +0100)
content tags
add:
README
                                                             -*- outline -*-

* Copyright (C) 2010, 2011 Didier Verna

This file is part of Clon.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.


* Introduction
In the Lisp family of languages, one of the key components is the so-called
REPL, the Read-Eval-Print Loop, which blends the runtime, compilation and
development phases together, allowing for a very high level of interaction
with the program. The importance of this paradigm explains why it is still
rare to find "standalone" applications written in Lisp: most Lisp application
clients are lispers themselves, and they prefer to live in the REPL.

On the other hand, many contemporary Common Lisp compilers provide ways of
creating standalone Common Lisp programs, using either shebang technology or
by directly dumping executables. This process is getting easier to achieve
every day. For instance, with SBCL, all it takes is one function call
(save-lisp-and-die) and one command-line option to the compiler (--script).

The (big) size of a Lisp image has been considered a showstopper in creating
standalone applications for a long time, but nowadays, it doesn't really
matter anymore (if you are not convinced, just figure out the average size of
an application bundle under Mac OS X). This, along with the fact that Common
Lisp compilers can generate very efficient code today, makes the perspective
of standalone Common Lisp applications very tempting again.

When it comes to preserving interaction with the user, one of the key
components in a standalone application is the handling of the command-line. 
Clon is a library designed to do just that.


* Overview
Clon provides traditional features one might expect from a command-line
options management library, but what makes it somewhat unique in its
conception is that it has been designed with both the application developer
and the application user in mind: many aspects of the command-line management
usually imposed by the program are in fact under the control of the
application user. The idea is that all Clon-enabled applications behave in a
uniform way, and that it is the user who gets to decide, not the developper. 
The most important features of Clon are listed below.

** Command-Line Syntax
Clon imposes a particular yet flexible syntax for the command-line. Options
have short and/or long names, beginning with either one or two dashes. Options
may take an argument. In that case, the argument may be optional or mandatory. 
Option names may be abbreviated and one-character options may be grouped
together in a single call. There is an additional call syntax for Boolean or
Boolean-based options. Finally, the command-line may have a "postfix", that
is, a non-option part.

** Option Types
Clon comes with a set of predefined option types, including "flags" (option
without arguments), "switches" (Boolean options), simple Lisp objects, simple
strings, enumerations, pathnames etc. Clon is also extensible: it is possible
to define new option types, either from scratch or by subclassing an existing
one.

** Value Retrieval
The traditional approach to command-line analysis is to process it
sequentially, and Clon lets you do that. However, Clon also provides an
explicit retrieval mechanism by which you can directly request the value of a
specific option, regardless of its position, or even its presence on the
command-line. An option's value can be retrieved from different sources: a
command-line argument, a "fallback" value (for optional arguments), a default
value or an environment variable associated with the option. The retrieval
process is completely automated, hence removing this burden from the
developer's shoulders.

** Error Management
Another cumbersome task already taken care of is error management. Clon
provides two built-in error management schemes, in case something is wrong on
the command-line. The simplest one is to quit the application with an
informative error message. The other one is to enter an interactive dialog
with the user, in which it is possible to fix the problem (correct a typo,
discard an option call, provide a missing argument or value etc.). A unique
feature of Clon is that the application user may choose his or her preferred
error management scheme.

** Help String Contents
The "help string" is typically what you expect from the output of a --help
option. Maintaining an up-to-date help string is a very boring task, so Clon
completely automates this for you (another burden removed from the developer's
shoulders). However, the application programmer still has control over the
help string's contents, notably the order in which options are displayed, and
also by having the possibility of grouping options together and inserting
arbitrary text in the output.

** Help String Format
Clon also completely automates the help string typesetting process. For
instance, it can automatically format the output for 80 columns, but it is
also aware of the tty geometry and will use it when appropriate. Clon also
supports help string "fontification" (or "highlighting") through ISO/IEC 6429
SGR escape sequences on tty's that support it. Another unique feature of Clon
is that the exact format and highlight specification for the help string is
under the control of the application user, via the notion of "theme". Clon
comes with a set of predefined themes (for instance, standard, with heavy
fontification, refcard for quick reference etc.) and application users can
define their own. As a matter of fact, a theme not only controls the format
and highlight of the help string, but also its contents. 
shortlog
2013-04-16 Didier VernaProtect against error in user home directory computationmaster
2012-10-05 Didier VernaUpdate for the latest Declt.
2012-09-26 Didier VernaBump version number.version-1.0b23
2012-09-26 Didier VernaAdd Jan Moringen to the acknowledgements section.
2012-09-26 Didier VernaRecode some Latin 1 files into UTF8.
2012-09-26 Didier VernaAdd a comment in Jan Moringen's contrib.
2012-09-26 Didier VernaDocument DUMP's &rest argument.
2012-09-26 Didier VernaFix usage of sb-posix package.
2012-09-26 Didier VernaExtend the dumping protocol.
2012-08-08 Didier VernaAdd the contrib directory.
2012-08-07 Didier VernaUpdate minimum versions of some compilers.
2012-08-07 Didier VernaUpgrade ABCL support for the MOP.
2012-08-07 Didier VernaImprove installation process.
2012-05-22 Didier VernaFix spelling of LispWorks.version-1.0b22
2012-05-22 Didier VernaUpgrade version number to 1.0b22.
2012-05-22 Didier VernaRevert "Change the default output stream of HELP to...
...
tags
5 years ago version-1.0b23 Version 1.0 beta 23 "Michael Brecker"
5 years ago version-1.0b22 Version 1.0 beta 22 "Michael Brecker"
5 years ago version-1.0b21 Version 1.0 beta 21 "Michael Brecker"
5 years ago version-1.0b20 Version 1.0 beta 20 "Michael Brecker"
6 years ago version-1.0b19 Version 1.0 beta 19 "Michael Brecker"
6 years ago version-1.0b18 Version 1.0 beta 18 "Michael Brecker"
6 years ago version-1.0b17 Version 1.0 beta 17 "Michael Brecker"
6 years ago version-1.0b16 Version 1.0 beta 16 "Michael Brecker"
7 years ago version-1.0b15 Version 1.0 beta 15 "Michael Brecker"
7 years ago version-1.0b14 Version 1.0 beta 14 "Michael Brecker"
7 years ago version-1.0b13 Version 1.0 beta 13 "Michael Brecker"
7 years ago version-1.0b12 Version 1.0 beta 12 "Michael Brecker"
7 years ago version-1.0b11 Version 1.0 beta 11 "Michael Brecker"
7 years ago version-1.0b10 Version 1.0 beta 10 "Michael Brecker"
7 years ago version-1.0b9 Version 1.0 beta 9 "Michael Brecker"
7 years ago version-1.0b8 Version 1.0 beta 8 "Michael Brecker"
...
heads
4 years ago master