3 @c user.texi --- User manual
5 @c Copyright (C) 2010, 2011, 2012 Didier Verna.
7 @c Author: Didier Verna <didier@lrde.epita.fr>
8 @c Maintainer: Didier Verna <didier@lrde.epita.fr>
10 @c This file is part of Clon.
12 @c Permission to use, copy, modify, and distribute this software for any
13 @c purpose with or without fee is hereby granted, provided that the above
14 @c copyright notice and this permission notice appear in all copies.
16 @c THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 @c WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 @c MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 @c ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 @c WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 @c ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 @c OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
27 @c Contents management by FCM version 0.1.
30 @c ====================================================================
32 @c ====================================================================
34 @setfilename clon-user.info
35 @settitle The Clon User Manual
37 @documentencoding ISO-8859-1
42 @c ====================================================================
44 @c ====================================================================
45 @set VERSION 1.0 beta 20 "Michael Brecker"
46 @set COPYRIGHT_DATE 2010, 2011, 2012
47 @setchapternewpage odd
48 @setcontentsaftertitlepage
50 The Clon User Manual for version @value{VERSION}.
51 @end documentdescription
55 @c ====================================================================
57 @c ====================================================================
96 @option{--clon-\name\}
100 @c --------------------------------
101 @c Manuals cross-referencing macros
102 @c --------------------------------
103 @c The following 3 macros are here to circumvent the info filenames
104 @c changes, when referencing the end-user manual:
106 @macro pxenduserref{node}
108 @pxref{\node\, , , clon-enduser, The Clon End-User Manual}
111 @pxref{\node\, , , enduser, The Clon End-User Manual}
115 @macro xenduserref{node}
117 @xref{\node\, , , clon-enduser, The Clon End-User Manual}
120 @xref{\node\, , , enduser, The Clon End-User Manual}
124 @macro enduserref{node}
126 @ref{\node\, , , clon-enduser, The Clon End-User Manual}
129 @ref{\node\, , , enduser, The Clon End-User Manual}
143 @cindex @t{--clon-\opt\}
144 @cindex Built-In Options, @t{--clon-\opt\}
145 @cindex Options, built-in, @t{--clon-\opt\}
148 @c Common option properties
149 @macro copindex{prop}
150 @cindex Options, common properties, @t{\prop\}
151 @cindex Common Option Properties, @t{\prop\}
155 @c #### NOTE: not an alias because of argument syntax.
156 @macro oindex{name,class}
157 @cindex \name\ (@t{\class\})
158 @cindex Options, \name\ (@t{\class\})
163 @macro voindex{name,class}
164 @cindex \name\ (@t{\class\})
165 @cindex Valued Options, \name\ (@t{\class\})
166 @cindex Options, valued, \name\ (@t{\class\})
170 @c Common valued option properties
171 @macro cvopindex{prop}
172 @cindex Valued Options, common properties, @t{\prop\}
173 @cindex Common Valued Option Properties, @t{\prop\}
174 @cindex Options, valued, common properties, @t{\prop\}
177 @c Valued option properties
178 @macro vopindex{name,class,prop}
179 @cindex \name\ (@t{\class\}), properties, @t{\prop\}
180 @cindex Valued Options, \name\ (@t{\class\}), properties, @t{\prop\}
181 @cindex Options, valued, \name\ (@t{\class\}), properties, @t{\prop\}
184 @c Configuration options
186 @vindex com.dvlsoft.clon.configuration
187 @cindex Configuration Option, @t{:\name\}
196 @macro foindex{func,opt}
197 @findex \func\@r{, options, }\opt\
201 @macro fiindex{func,item}
202 @findex \func\@r{, items, }\item\
206 @macro fkindex{func,key}
207 @findex \func\@r{, keys, }\key\
211 @macro fiaindex{func,arg}
212 @findex \func\@r{, initargs, }\arg\
215 @c Generic functions sub-index
216 @macro gfsubindex{func}
217 @findex @r{Generic Functions, }\func\
226 @c Generic function methods
227 @macro gfmindex{func,method}
228 @findex \func\@r{, methods, }\method\
229 @findex @r{Generic Functions, }\func\@r{, methods, }\method\
232 @c #### FIXME: I need this because when using @defun, the function is
233 @c referenced directly but not under the Constructors sub-index. This
234 @c sucks because what I would like is the ability to define my own
235 @c @defXXX macros, which apparently I can't. Besides, doing this
236 @c produces 2 separate index entries, instead of only one with two pagerefs.
237 @c This problem stands for @gfsubindex (see above), @rfsubindex (see
238 @c below) and @ecsubindex (see below) as well.
239 @c Constructor functions sub-index
240 @macro cfsubindex{func}
241 @findex @r{Constructors, }\func\
244 @c Constructor functions
250 @c Constructor function initargs
251 @macro cfiaindex{func,arg}
252 @fiaindex{\func\, \arg\}
253 @findex @r{Constructors, }\func\@r{, initargs, }\arg\
256 @c Reader functions subindex
257 @macro rfsubindex{func}
258 @findex @r{Readers, }\func\
271 @c Environment variables
274 @vindex @r{Environment, }\var\
277 @c Built-in environment variables
278 @macro bievindex{var}
289 @tpindex @r{Classes, }\cls\
293 @macro clssindex{cls,slot}
294 @tpindex \cls\@r{, slots, }\slot\
295 @tpindex @r{Classes, }\cls\@r{, slots, }\slot\
299 @macro clsiaindex{cls,arg}
300 @tpindex \cls\@r{, initargs, }\arg\
301 @tpindex @r{Classes, }\cls\@r{, initargs, }\arg\
307 @tpindex @r{Option Classes, }\cls\
310 @c Error conditions subindex
311 @macro ecsubindex{cond}
312 @tpindex @r{Error Conditions, }\cond\
321 @c Error condition slots
322 @macro ecsindex{cond,slot}
323 @tpindex \cond\@r{, slots, }\slot\
324 @tpindex @r{Error Conditions, }\cond\@r{, slots, }\slot\
328 @macro pkgindex{name}
330 @tpindex @r{Packages, }\name\
334 @macro sysindex{name}
336 @tpindex @r{Systems, }\name\
341 @c ====================================================================
342 @c Info Category and Directory
343 @c ====================================================================
344 @dircategory Common Lisp
346 * Clon User: (clon-user). The Clon User Manual.
351 @c ====================================================================
353 @c ====================================================================
356 Copyright @copyright{} @value{COPYRIGHT_DATE} Didier Verna
358 Permission is granted to make and distribute verbatim copies of this
359 manual provided the copyright notice and this permission notice are
360 preserved on all copies.
363 Permission is granted to process this file through TeX and print the
364 results, provided the printed document carries a copying permission
365 notice identical to this one except for the removal of this paragraph
366 (this paragraph not being relevant to the printed manual).
369 Permission is granted to copy and distribute modified versions of this
370 manual under the conditions for verbatim copying, provided also that the
371 section entitled ``Copying'' is included exactly as in the original.
373 Permission is granted to copy and distribute translations of this manual
374 into another language, under the above conditions for modified versions,
375 except that this permission notice may be translated as well.
381 @c ====================================================================
383 @c ====================================================================
385 @title The Clon User Manual
386 @subtitle The @CmdLine{} Options Nuker, Version @value{VERSION}
389 @author Didier Verna <@email{didier@@lrde.epita.fr}>
391 @vskip 0pt plus 1filll
394 @hfill Cover art by Alexis Angelidis.
399 @c ====================================================================
401 @c ====================================================================
406 @c ====================================================================
408 @c ====================================================================
410 @node Top, Copying, (dir), (dir)
411 @top The Clon User Manual
413 This is the @clon{} User Manual for @clon{} version @value{VERSION}:
414 it explains how to use @clon{} in your application.
417 * Copying:: The BSD license
418 * Introduction:: What Clon is all about
419 * Installation:: Library, documentation and sample code
420 * Quick Start:: For the brave and the impatient
421 * Using Clon:: Clonificating your application
422 * Extending Clon:: Creating your own option types
423 * Advanced Usage:: Things rarely needed
424 * Conclusion:: That's all folks
425 * Technical Notes:: Configuration, platforms and portability
426 * API Quick Reference:: The Complete protocols
427 * Indexes:: Concept, Function and Variable
428 * Acknowledgments:: Hall of Pride
436 @c ====================================================================
438 @c ====================================================================
439 @node Copying, Introduction, Top, Top
443 Permission to use, copy, modify, and distribute this software for any
444 purpose with or without fee is hereby granted, provided that the above
445 copyright notice and this permission notice appear in all copies.
447 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
448 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
449 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
450 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
451 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
452 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
453 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
458 @c ====================================================================
460 @c ====================================================================
461 @node Introduction, Installation, Copying, Top
462 @chapter Introduction
464 @clon{} is a library for managing @cmdline{} options in standalone @cl{}
465 applications. It provides a unified option syntax with both short and
466 long names, automatic completion of partial names and automatic
467 retrieval/conversion of option arguments from the @cmdline{}, associated
468 environment variables, fallback or default values. @clon{} comes with a
469 set of extensible option types (switches, paths, strings @etc{}).
470 @clon{} also provides automatic generation and formatting of help
471 strings, with support for highlighting on @tty{}'s through ISO/IEC 6429
472 SGR. This formatting is customizable through @emph{themes}.
474 Depending on the target audience, @clon{} stands for either ``The
475 @CmdLine{} Options Nuker'' or ``The @cl{} Options Nuker''. @clon{} also
476 has a recursive acronym: ``@clon{} Likes Options Nuking'', and a reverse
477 one: ``Never Omit to Link with @clon{}''. Other possible expansions of
478 the acronym are still being investigated.
480 This manual is for the @clon{} @emph{user}, that is, the developer of a
481 @cl{} application who wants to use @clon{} for @cmdline{} option
482 management@footnote{An application using @clon{} for its @cmdline{}
483 option management is said to be @emph{clonified}. It is also possible to
484 say @emph{clonfiscated}. However, we advise against using
485 @emph{clonistified}. The term @emph{clonificated} is also considered bad
486 style, and the use of @emph{clonificationated} is strictly prohibited.}.
487 As opposed to the user of the @emph{library}, the user of an
488 @emph{application} powered by @clon{} is called an @emph{end-user}.
489 @clon{} provides both a user manual (this one) and an end-user manual
490 (@pxenduserref{Top}). Everybody should read the end-user manual first.
492 @ref{Quick Start} provides a very short example in order to give an
493 overview of what's coming next. @ref{Using Clon} explains in detail how
494 to clonify your application, and @ref{Extending Clon} describe how to
495 extend @clon{} with your own option types.
499 @c ====================================================================
501 @c ====================================================================
502 @node Installation, Quick Start, Introduction, Top
503 @chapter Installation
504 @clon{} currently works on Unix (including MacOS X) and Windows (Cygwin
505 or MinGW) with SBCL, CMUCL, CCL, ECL, CLISP and ABCL. @clon{} is
506 provided as an ASDF 2 system, but has no mandatory dependency. CFFI may
507 optionally be used with CLISP. @xref{Supported Platforms}, for more
510 In addition to the library itself, the Clon distribution offers
511 documentation in the form of 3 different manuals, some data files that
512 are needed for it to work properly, and a couple of demonstration
513 programs. Because of that, some bits of manual installation are needed.
515 After unpacking somewhere in the ASDF 2 source registry, please perform
516 the following steps, in order.
520 Edit @file{Makefile.cnf} to your specific needs.
523 Type @command{make} to compile the documentation and the demo programs
524 (end-user manual, user manual and possibly reference manual). By
525 default, the documentation is built in info, PDF and HTML formats. If
526 you want other formats (DVI and PostScript are available), type
527 @command{make all-formats}. You can also type individually @command{make
528 dvi} and/or @command{make ps} in order to get the corresponding format.
531 As documented in @file{Makefile.cnf}, the reference manual is only
532 generated if you have SBCL and the Declt library at hand (see
533 @uref{http://www.lrde.epita.fr/~didier/software/lisp/misc.php#declt}).
536 Type @command{make install} to install both the documentation and the
537 data files. If you have compiled the documentation in DVI and PostScript
538 format, those will be installed as well. The same goes for the reference
539 manual. The demo programs are not installed anywhere.
542 Type @command{make uninstall} to uninstall the library.
546 @c ====================================================================
548 @c ====================================================================
549 @node Quick Start, Using Clon, Installation, Top
551 In this chapter, we assume that you have properly installed @clon{}
552 (@pxref{Technical Notes}), and we build a very short program to get you
553 started. Let's call it @file{quickstart.lisp}.
556 * Full Source:: The complete source code
557 * Explanation:: Step-by-step code walking
564 @node Full Source, Explanation, Quick Start, Quick Start
566 For cut'n paste convenience, the complete source code is given below.
567 For a slightly longer example, have a look at the demonstration program
568 called @file{simple} in the distribution.
572 (in-package :cl-user)
575 (asdf:load-system :com.dvlsoft.clon)
576 (use-package :com.dvlsoft.clon)
578 (defsynopsis (:postfix "FILES...")
579 (text :contents "A very short program.")
580 (group (:header "Immediate exit options:")
581 (flag :short-name "h" :long-name "help"
582 :description "Print this help and exit.")
583 (flag :short-name "v" :long-name "version"
584 :description "Print version number and exit.")))
587 "Entry point for our standalone application."
589 (when (getopt :short-name "h")
592 (do-cmdline-options (option name value source)
593 (print (list option name value source)))
597 (dump "quickstart" main)
605 @node Explanation, , Full Source, Quick Start
607 Let's examine this program step-by-step now.
609 @pkgindex{com.dvlsoft.clon}@c
610 @sysindex{com.dvlsoft.clon}@c
611 First, we put ourselves in the @cl{} user package, and load @clon{} from
612 its ASDF system @samp{com.dvlsoft.clon}. Next, we use the @clon{}
613 package, also named @samp{com.dvlsoft.clon}.
617 (in-package :cl-user)
620 (asdf:load-system :com.dvlsoft.clon)
621 (use-package :com.dvlsoft.clon)
625 In fact, using the @clon{} package directly is done here for simplicity,
626 but is not recommended. In case you find the package name too long to
627 prefix every symbol with, @clon{} provides a utility function that
628 allows you to add (and use) a shorter nickname instead (the
629 demonstration programs in the distribution show how to use it):
631 @cindex Package, nicknames
632 @defun nickname-package &optional NICKNAME
633 Add NICKNAME (:CLON by default) to the :COM.DVLSOFT.CLON package.
639 @cindex Text, in synopsis
640 @cindex Options, in synopsis
641 @cindex Groups, in synopsis
643 The next thing you want to do is to create a set of options, groups or
644 texts that your application will recognize and/or display in its help
645 string. The structure of your @cmdline{} is known to @clon{} as the
646 @dfn{synopsis}. In order to create it, use the macro @code{defsynopsis}.
648 @foindex{defsynopsis,:postfix}
649 @fiindex{defsynopsis,text}
650 @fiindex{defsynopsis,options}
651 @fiindex{defsynopsis,group}
654 (defsynopsis (:postfix "FILES...")
655 (text :contents "A very short program.")
656 (group (:header "Immediate exit options:")
657 (flag :short-name "h" :long-name "help"
658 :description "Print this help and exit.")
659 (flag :short-name "v" :long-name "version"
660 :description "Print version number and exit.")))
664 Note that the synopsis has a double role: it not only serves to define
665 the options recognized by your application, but also the order in which
666 every element appears in the help string. In that particular example, we
667 define a line of text and a group with a header and two flags.
670 @cfindex{make-context}
671 Now, we are going to define a function @code{main} for our standalone
672 application. The first thing that we need to do is create a
673 @dfn{context}. A context is an object that @clon{} uses to store various
674 things, including some state related to the parsing of the @cmdline{}.
675 You create a context with the function @code{make-context}.
680 "Entry point for our standalone application."
685 @cindex Options Retrieval, explicit
686 @cindex Retrieval, of options, explicit
688 @cindex Help String, display
690 At that point, @clon{} is ready to retrieve the options you want from
691 the @cmdline{}. Let's first see if the user has called the option
692 @option{-h}, and give him the help string. Option retrieval is done with
693 the function @code{getopt}, and automatic help string output with the
694 function @code{help}. Note that what we do here is @emph{not} process
695 the @cmdline{} in sequence, but look directly for a specific option by
696 name (this retrieval method is said to be @dfn{explicit}).
698 @fkindex{getopt,:short-name}
701 (when (getopt :short-name "h")
708 The @code{exit} function is a wrapper around an
709 implementation-dependent way to exit (shall I say quit?) the @cl{}
710 environment, hence the program. It takes an optional argument that
711 stands for the exit status.
713 @cindex Options Retrieval, sequential
714 @cindex Retrieval, of options, sequential
715 @findex do-cmdline-options
716 And now, we are going to retrieve the other options and simply print
717 them. This time however, we process the @cmdline{} sequentially (so this
718 retrieval method is said to be @dfn{sequential}). This is done with the
719 @code{do-cmdline-options} macro. We also close the @code{main} function.
723 (do-cmdline-options (option name value source)
724 (print (list option name value source)))
730 Finally, time to save the Lisp image.
736 (dump "quickstart" main)
740 The first argument to @code{dump} is the name of the executable to
741 produce, and the second argument is the name of the function to call
742 automatically at startup.
744 In order to get a standalone executable from this program, all you need
745 to do now is to type @samp{CC=gcc sbcl --script quickstart.lisp}. Note
746 that the actual way of dumping executables is compiler-dependent. For
747 more information on the proper way to do it and on the compilers
748 currently supported, see @ref{Dumping Executables}.
750 Note also that it is possible to use @clon{} without actually dumping a
751 standalone executable (@pxref{Not Dumping Executables}).
755 @c ====================================================================
757 @c ====================================================================
758 @node Using Clon, Extending Clon, Quick Start, Top
761 Using @clon{} in your application is a two stages process. In phase 1,
762 you create a @dfn{synopsis}, which is a description of your
763 application's @cmdline{} and a @dfn{context}, which describes this
764 specific execution of the program. In phase 2, you retrieve the option
765 values and possibly display help strings. Phase 1 is called the
766 @dfn{initialization phase}, while phase 2 is called the @dfn{runtime
770 * Synopsis Definition:: Describing your command-line
771 * Context Creation:: Instantiating your command-line
772 * Integrity Checks:: Verifying the Clon semantics
773 * Option Retrieval:: Getting the options values
774 * Help:: Generating the help string
778 @c -------------------
779 @c Synopsis Definition
780 @c -------------------
781 @node Synopsis Definition, Context Creation, Using Clon, Using Clon
782 @section Synopsis Definition
784 @cindex Initialization Phase
785 @cindex Phase, initialization
788 Step one of the @clon{} initialization phase consists in defining a
789 @dfn{synopsis}. A synopsis is essentially a description of your
790 application's @cmdline{}: it describes what are the available options,
791 whether your application has a postfix @etc{} The synopsis, however,
792 plays a second role: it also describes the contents of your
793 application's help string. When you create a synopsis, you describe the
794 @cmdline{} and the help string at the same time.
797 * Synopsis Items:: Defsynopsis and its contents
798 * Built-In Option Types:: The exhaustive list
799 * Advanced Synopsis Creation:: The non-declarative way
802 @node Synopsis Items, Built-In Option Types, Synopsis Definition, Synopsis Definition
803 @subsection Synopsis Items
804 Look again at the synopsis definition provided in @ref{Quick Start}.
808 (defsynopsis (:postfix "FILES...")
809 (text :contents "A very short program.")
810 (group (:header "Immediate exit options:")
811 (flag :short-name "h" :long-name "help"
812 :description "Print this help and exit.")
813 (flag :short-name "v" :long-name "version"
814 :description "Print version number and exit.")))
818 You define a synopsis with the @code{defsynopsis} macro.
820 @defmac defsynopsis ([OPTIONS@dots{}]) ITEMS@dots{}
821 Define a new synopsis and return it. @var{OPTIONS} are key/value pairs.
822 @var{ITEMS} are text, group or option descriptions.
824 The following @var{OPTIONS} are currently available.
828 @foindex{defsynopsis,:postfix}@c
829 @cindex Command-Line, remainder
830 @cindex Remainder, of command-line
831 A string which will appear at the end of the synopsis line in the help
832 string. When you provide a postfix, you also implicitely tell @clon{}
833 that your application accepts non-option arguments at the end of the
834 @cmdline{} (this is called the @dfn{remainder} of the @cmdline{}). See
835 @enduserref{Option Separator} for more information on the behavior of
836 @clon{} with respect to postfixes. Also, see @ref{Command-Line
837 Remainder} on how to access the @cmdline{} remainder.
841 We now examine the syntax for each possible @var{ITEM}.
843 * Text:: Adding arbitrary text
844 * Options:: Adding options
845 * Groups:: Adding groups
848 @node Text, Options, Synopsis Items, Synopsis Items
851 @cindex Text, in synopsis
852 @fiindex{defsynopsis,text}
853 In order to add arbitrary text to your help string, use the following
857 @t{(text} [@var{OPTIONS@dots{}}]@t{)}
859 @var{OPTIONS} are key/value pairs. The following @var{OPTIONS} are
863 @cindex Text, contents
864 The actual text string. Try to make proper sentences when adding
865 arbitrary text. You can use explicit newline characters in your text if
866 you really want to go next line, but in general, you should not worry
867 about the formatting because the themes are here to do so. In
868 particular, don't finish your text with a newline. This would break
869 potential theme specifications.
874 When non-@code{nil}, the text won't appear in the help string. Hidden
875 texts can still be displayed individually though (@pxref{Help}).
878 @node Options, Groups, Text, Synopsis Items
879 @subsubsection Options
881 @cindex Options, in synopsis
882 @fiindex{defsynopsis,options}
883 In order to add an option to your help string, you must provide a list
884 beginning with the option type and followed by key/value pairs
885 describing the option's properties. For instance, to add a flag with a
886 short name and a description, you could do this:
889 (flag :short-name "h" :description "Print this help and exit.")
892 Option properties vary depending on the option type. The exact list of
893 available option types, and the corresponding properties are described
894 in @ref{Built-In Option Types}.
896 @node Groups, , Options, Synopsis Items
897 @subsubsection Groups
899 @cindex Groups, in synopsis
900 @fiindex{defsynopsis,group}
901 In order to add a group to your help string, use the following form:
904 @t{(group} ([@var{OPTIONS@dots{}}]) @var{ITEMS@dots{}}@t{)}
906 @cindex Text, in groups
907 @cindex Options, in groups
908 @cindex Groups, in groups
909 @var{OPTIONS} are key/value pairs. @var{ITEMS} simply are arbitrary
910 text, option or sub-group descriptions as we've just seen.
912 The following @var{OPTIONS} are currently available.
916 @cindex Header, in group
917 @foindex{defgroup,:header}@c
918 A string which will be displayed above the group's contents in the help
919 string. The same formatting recommendations as for arbitrary text apply
922 @cindex Hidden Groups
923 @cindex Groups, hidden
924 @foindex{defgroup,:hidden}@c
926 @cindex Built-In Groups
927 @cindex Groups, built-in
929 When non-@code{nil}, the group won't appear in the help string. Hidden
930 groups can still be displayed individually though (@pxref{Help}). For
931 instance, the @clon{} built-in group is hidden in the regular help
932 string, but the @bioption{help} option still displays it individually.
935 @node Built-In Option Types, Advanced Synopsis Creation, Synopsis Items, Synopsis Definition
936 @subsection Built-In Option Types
937 @cindex Built-In Option Types
938 @cindex Options, built-in types
939 @cindex Option Types, built-in
940 In this section, we will review all the built-in option types that
941 @clon{} provides, along with their corresponding properties. You can use
942 them directly in your synopsis description. For adding personal option
943 types to @clon{}, see @ref{New Option Types}.
946 * Common Properties:: For all options
947 * Flags:: Built-in options without arguments
948 * Common Valued Option Properties:: For all valued options
949 * Built-In Valued Options:: Built-in options with arguments
952 @node Common Properties, Flags, Built-In Option Types, Built-In Option Types
953 @subsubsection Common Properties
954 @cindex Options, common properties
955 @cindex Common Option Properties
957 All option types in @clon{}, including those you define yourself
958 (@pxref{New Option Types}), have a set of basic, common properties. Here
963 @copindex{:short-name}
964 The option's short name. A string or @code{nil}.
966 @copindex{:long-name}
967 The option's long name. A string or @code{nil}.
969 @copindex{:description}
970 The option's descriptive text. A string or @code{nil}. The same
971 formatting recommendations as for arbitrary text apply (@pxref{Text}).
974 The option's associated environment variable. A string or @code{nil}.
977 @cindex Hidden Options
978 @cindex Options, hidden
980 When non-@code{nil}, the option won't appear in the help string. Hidden
981 options can still be displayed individually though (@pxref{Help}).
984 Note that an option is required to have at least one name (either short
985 or long). Non-@code{nil} but empty names are also prohibited, and of
986 course, a short name cannot begin with a dash (otherwise, it would be
987 mistaken for a long name, but did I really need to mention this?).
989 @node Flags, Common Valued Option Properties, Common Properties, Built-In Option Types
992 In @clon{}, options that don't take any argument are of type
993 @code{flag}. These options don't provide additional properties on top of
994 the common set described in @ref{Common Properties}. All properties
995 default to @code{nil}.
997 @node Common Valued Option Properties, Built-In Valued Options, Flags, Built-In Option Types
998 @subsubsection Common Valued Option Properties
999 @cindex Valued Options
1000 @cindex Options, valued
1001 @clsindex{valued-option}
1002 All non-flag options in @clon{} are said to be @dfn{valued}. All valued
1003 options, including those you define yourself (@pxref{New Option Types}),
1004 share a set of additional properties. Here is a list of them.
1006 @cindex Valued Options, common properties
1007 @cindex Common Valued Option Properties
1008 @cindex Options, valued, common properties
1010 @item :argument-name
1011 @cvopindex{:argument-name}
1012 The name of the option's argument, as it appears in the help string. It
1013 defaults to @code{"ARG"}, so that for instance, a @samp{name} option
1014 would appear like this: @samp{--name=ARG}.
1015 @item :argument-type
1016 @cvopindex{:argument-type}
1017 The status of the argument. Possible values are @code{:required} (the
1018 default) and @code{:mandatory} which are synonyms, or @code{:optional}.
1019 @item :fallback-value
1020 @cvopindex{:fallback-value}
1021 @cindex Values, source, fallback
1022 @item :default-value
1023 @cvopindex{:default-value}
1024 @cindex Values, source, default
1025 The option's fallback and default values. Remember that a fallback value
1026 only makes sense when the argument is optional. Besides, also when the
1027 argument is optional, you need to provide at least a fallback or a
1028 default value (or both of course; see @enduserref{Value Sources}).
1031 @node Built-In Valued Options, , Common Valued Option Properties, Built-In Option Types
1032 @subsubsection Built-In Valued Options
1033 @cindex Option Types, valued
1034 @cindex Built-In Option Types, valued
1035 @cindex Options, built-in types, valued
1036 @cindex Option Types, built-in, valued
1037 @clon{} currently defines 6 built-in valued option types. These option
1038 types may change the default value for some common properties, and / or
1039 provide additional properties of their own. All of this is described
1044 @voindex{Strings,stropt}@c
1045 @cvopindex{:argument-name}@c
1046 This option type is for options taking strings as their argument. String
1047 options don't provide any additional properties, but their default
1048 argument name is changed from @code{"ARG"} to @code{"STR"}.
1050 @voindex{Lisp Objects,lispobj}@c
1051 @cvopindex{:argument-name}@c
1052 @vopindex{Lisp Objects,lispobj,:typespec}@c
1053 @bioindex{line-width}@c
1054 This option type is for options taking any kind of Lisp object as their
1055 argument. @code{lispobj} options change their default argument name from
1056 @code{"ARG"} to @code{"OBJ"}. Also, they provide an additional property
1057 called @code{:typespec} which must be a @cl{} type specifier that the
1058 argument must satisfy. It defaults to @code{t}. Look at the
1059 @bioption{line-width} built-in option for an example.
1061 @voindex{Enumerations,enum}@c
1062 @cvopindex{:argument-name}@c
1063 @vopindex{Enumerations,enum,:enum}@c
1064 @bioindex{version}@c
1065 This option type is for options taking values from an enumerated set of
1066 keywords. @code{enum} options change their default argument name from
1067 @code{"ARG"} to @code{"TYPE"}. Also, they provide an additional property
1068 called @code{:enum} to store the list of @cl{} keywords enumerating the
1069 possible values. The end-user does not use a colon when providing an
1070 argument to an @code{enum} option. Only the keyword's name. The end-user
1071 also has the ability to abbreviate the possible values. An empty
1072 argument is considered as an abbreviation for the first element in the
1073 set. Look at the @bioption{version} built-in option for an example.
1075 @bioindex{search-path}@c
1077 @voindex{Paths,path}@c
1078 @cvopindex{:argument-name}@c
1079 @vopindex{Paths,path,:type}@c
1080 This option type is for options taking a colon-separated list of
1081 pathnames as argument. @code{path} options change their default argument
1082 name from @code{"ARG"} to @code{"PATH"}. Also, they provide an
1083 additional property called @code{:type} which specifies the kind of path
1084 which is expected. Possible values are: @code{:file}, @code{:directory},
1085 @code{:file-list}, @code{:directory-list} or @code{nil} (meaning that
1086 anything is allowed). Null paths are allowed, and may be provided by an
1087 empty argument. Look at the @bioption{search-path} and
1088 @bioption{theme} built-in options for examples.
1090 @voindex{Switches,switch}@c
1091 @cvopindex{:argument-name}@c
1092 @cvopindex{:argument-type}@c
1093 @vopindex{Switches,switch,:argument-style}@c
1094 This option type is for Boolean options. @code{switch} options change
1095 their default argument type from required to optional and provide a
1096 fallback value of @code{t} automatically for optional arguments.
1097 @code{switch} options provide a new property called
1098 @code{:argument-style}. Possible values are @code{:yes/no} (the
1099 default), @code{:on/off}, @code{:true/false}, @code{:yup/nope},
1100 @code{:yeah/nah}. This property affects the way the argument name and
1101 true or false values are advertized in help strings. However, all
1102 possible arguments forms (@pxenduserref{Switches}) are always available
1105 @voindex{Extended Switches,xswitch}@c
1106 @cvopindex{:argument-name}@c
1107 @cvopindex{:argument-type}@c
1108 @vopindex{Extended Switches,xswitch,:argument-style}@c
1109 @vopindex{Extended Switches,xswitch,:enum}@c
1110 @bioindex{highlight}@c
1111 This option type stands for @dfn{extended} switch. Extended switches
1112 result from the mating of a male switch and a female enumeration, or the
1113 other way around (elementary decency prevents me from describing this
1114 mating process in detail): their possible values are either Boolean or
1115 from an @code{:enum} property as in the case of @code{enum} options. As
1116 simple switches, @code{xswitch} options change their default argument
1117 type from required to optional and provide a fallback value of @code{t}
1118 automatically for optional arguments. They also provide the
1119 @code{:argument-style} property. Contrary to switches, however, this
1120 property does not affect the argument name. It only affects the way true
1121 or false values are displayed in help strings. Look at the
1122 @bioption{highlight} built-in option for an example.
1125 @node Advanced Synopsis Creation, , Built-In Option Types, Synopsis Definition
1126 @subsection Advanced Synopsis Creation
1128 The fact that @code{defsynopsis} lets you define things in a
1129 @emph{declarative} way has not escaped you. Declarative is nice but
1130 sometimes it gets in the way, so it is time to see how things work under
1131 the hood. Every item in a synopsis is in fact implemented as an object
1132 (an instance of some class), so it turns out that @code{defsynopsis}
1133 simply is a convenience wrapper around the corresponding constructor
1134 functions for all such objects. Instead of using @code{defsynopsis}, you
1135 can then use those constructor functions explicitely.
1138 * Constructors:: The expansion of defsynopsis
1139 * Advantages:: Yes, but why?
1140 * Group Definition:: The declarative way
1143 @node Constructors, Advantages, Advanced Synopsis Creation, Advanced Synopsis Creation
1144 @subsubsection Constructors
1145 Let's have a look at the expansion of @code{defsynopsis} from the quick
1146 start example (@pxref{Quick Start}).
1148 The original code is like this:
1152 (defsynopsis (:postfix "FILES...")
1153 (text :contents "A very short program.")
1154 (group (:header "Immediate exit options:")
1155 (flag :short-name "h" :long-name "help"
1156 :description "Print this help and exit.")
1157 (flag :short-name "v" :long-name "version"
1158 :description "Print version number and exit.")))
1162 And once the macro is expanded, it will look like this:
1164 @cfindex make-synopsis
1168 @findex defsynopsis@r{, expansion}
1171 (make-synopsis :postfix "FILES..."
1172 :item (make-text :contents "A very short program.")
1173 :item (make-group :header "Immediate exit options:"
1174 :item (make-flag :short-name "h"
1176 :description "Print this help and exit.")
1177 :item (make-flag :short-name "v"
1178 :long-name "version"
1179 :description "Print version number and exit.")))
1183 As you can see, every synopsis element has a corresponding
1184 @code{make-@var{SOMETHING}} constructor, and the keywords used here and
1185 there in @code{defsyopsis} are in fact initargs to those constructors.
1186 We now examine those constructors in greater detail.
1188 @cindex Options, creation
1189 @defun make-text [@code{:hidden} BOOL] @code{:contents} STRING
1190 @cfsubindex{make-text}
1191 @cfiaindex{make-text,:contents}
1192 @cfiaindex{make-text,:hidden}
1193 Create an arbitrary text object, possibly hidden, whose contents is
1197 @c #### FIXME: I would like an environment without indexing here.
1198 @defun make-@var{OPTION} :INITARG INITVAL@dots{}
1199 @cfsubindex{make-@var{OPTION}}
1201 @cfindex make-stropt
1202 @cfindex make-lispobj
1205 @cfindex make-switch
1206 @cfindex make-xswitch
1207 Create a new @var{OPTION} object, @var{OPTION} being any built-in option
1208 type (@code{flag}, @code{stropt} @etc{}, see @ref{Built-In Valued
1209 Options}) or user-defined one (@pxref{New Option Types}). For a list of
1210 available initialization arguments (depending on the option type), see
1211 @ref{Built-In Option Types}.
1214 @defun make-group [@code{:header} STRING @code{:hidden} BOOL] @
1215 @code{:item} ITEM1 @code{:item} ITEM2@dots{}
1216 @cfsubindex{make-group}
1217 @cfiaindex{make-group,:header}
1218 @cfiaindex{make-group,:hidden}
1219 @cfiaindex{make-group,:item}
1221 Create a group object, possibly hidden, whose header is @var{STRING}.
1222 Every @var{ITEM} is an arbitrary text object, option object or group
1223 object. The order is important as it determines the display of the help
1227 @defun make-synopsis [@code{:postfix} STRING] @
1228 @code{:item} ITEM1 @code{:item} ITEM2@dots{}
1229 @cfsubindex{make-synopsis}
1230 @cfiaindex{make-synopsis,:postfix}
1231 @cfiaindex{make-synopsis,:item}
1233 Create a synopsis object whose postfix is @var{STRING}. Every @var{ITEM} is
1234 an arbitrary text object, option object or group object. The order is
1235 important as it determines the display of the help string.
1238 In fact, the @code{defsynopsis} macro allows you to freely mix
1239 declarative forms, constructor calls or whatever Lisp code you may want
1240 to use. The way this works is as follows: if a synopsis @var{ITEM}
1241 (@pxref{Synopsis Items}) is a list whose @code{car} is @code{text},
1242 @code{group}, or any option type (inluding those you define yourselves;
1243 see @ref{New Option Types}), then the @var{ITEM} is expanded as
1244 explained earlier. Otherwise, it is just left @emph{as-is}.
1246 To sum up, here's a example of things you can do in @code{defsynopsis}.
1250 (com.dvlsoft.clon:defsynopsis ()
1253 (setq *another-option* (com.dvlsoft.clon:make-switch #| ... |#)))
1258 @node Advantages, Group Definition, Constructors, Advanced Synopsis Creation
1259 @subsubsection Advantages
1261 So, why would you want to use constructors directly or mix declarative
1262 and imperative forms in @code{defsynopsis}? There are several reasons
1266 Some people prefer to declare (or should I say, create) their arbitrary
1267 texts, options and groups locally, in files, modules or ASDF components
1268 where they belong. In such a case, you need to keep references to the
1269 corresponding objects in order to compute the synopsis in the end.
1271 Since using constructors explicitely allows you to keep references to
1272 the created objects, these objects can be @emph{reused}. For instance,
1273 you can use the same text at different places, you can also use a single
1274 option several times, or even a single group several times so that its
1275 items appear in different places @etc{} Note that @clon{} knows its way
1276 around multiple occurrences of the same object: even if you use the same
1277 option object several times in a synopsis, @clon{} only maintains a
1278 single option definition.
1281 @node Group Definition, , Advantages, Advanced Synopsis Creation
1282 @subsubsection Group Definition
1283 There is one last point we need to address in order to complete this
1284 section. There might be times when you need to manipulate an explicit
1285 group object, but the object itself can still be created in a
1286 declarative (or mixed) way because you don't need to keep references on
1287 its items. For this, @clon{} provides a macro called @code{defgroup}.
1289 @defmac defgroup (OPTIONS@dots{}) ITEMS@dots{}
1290 @cindex Groups, in synopsis
1291 @fiindex{defsynopsis,group}
1292 @foindex{defgroup,:header}
1293 @foindex{defgroup,:hidden}
1294 Define a new group and return it. This macro behaves exactly like the
1295 @code{group} form in a call to @code{defsynopsis} (@pxref{Groups}). In
1296 fact, an intermediate step in the expansion of the @code{defsynopsis}
1297 macro is to transform @code{group} forms into @code{defgroup} macro
1298 calls. As for @code{defsynopsis}, @code{defgroup} allows you to mix
1299 declarative forms, constructor calls or any kind of Lisp code.
1307 @node Context Creation, Integrity Checks, Synopsis Definition, Using Clon
1308 @section Context Creation
1310 @cindex Initialization Phase
1311 @cindex Phase, initialization
1313 Step two of the @clon{} initialization phase consists in creating a
1314 @dfn{context}. A context is an object representing a particular instance
1315 of your program, for example (and most notably) with an actual
1316 @cmdline{} as the user typed it.
1319 * Making A Context:: The Constructor function
1320 * Contextual Information:: Interesting context slots
1323 @node Making A Context, Contextual Information, Context Creation, Context Creation
1324 @subsection Making A Context
1326 @cfindex{make-context}
1327 You create a context with the @code{make-context} function.
1330 @cfsubindex{make-context}
1331 Create a new context. That's it.
1334 @node Contextual Information, , Making A Context, Context Creation
1335 @subsection Contextual Information
1337 Once a context object is created, you have access to some interesting
1338 contextual information.
1341 * Program Name:: As it appear on the command-line
1342 * Command-Line Remainder:: The non-options part
1343 * Command-Line Polling:: Whether something is left
1346 @node Program Name, Command-Line Remainder, Contextual Information, Contextual Information
1347 @subsubsection Program Name
1348 The application's program name, as it appears on the @cmdline{}, may be
1349 accessed from @clon{}. You may find it easier to do this way, as @clon{}
1350 wraps around implementation-dependent access methods to @code{argv[0]}.
1353 In order to retrieve @code{argv[0]}, use the @code{progname} function
1354 like this: @code{(progname)}.
1356 @node Command-Line Remainder, Command-Line Polling, Program Name, Contextual Information
1357 @subsubsection Command-Line Remainder
1358 @cindex Remainder, of command-line
1359 @cindex Command-Line, remainder
1360 In the case your @cmdline{} has a remainder (that is, a non-options
1361 part; see @enduserref{Option Separator} and @ref{Synopsis Items}), you
1362 may need to access it in order to process it independently from @clon{}.
1363 Since @clon{} is responsible for parsing the @cmdline{}, it is also in
1364 charge of figuring out where the remainder of the @cmdline{} begins.
1367 The @cmdline{} remainder is known to @clon{} as soon as a context is
1368 created. You can retrieve it by using the @code{remainder} function like
1369 this: @code{(remainder)}. The remainder is provided as a list of strings.
1371 @node Command-Line Polling, , Command-Line Remainder, Contextual Information
1372 @subsubsection Command-Line Polling
1373 @cindex Polling, of command-line
1374 @cindex Command-Line, polling
1376 @clon{} provides two utility functions to inquire on the current status
1379 @findex cmdline-options-p
1381 The function @code{cmdline-options-p} returns true if there are still
1382 unprocessed options on the @cmdline{}. The function @code{cmdline-p}
1383 returns true if there's @emph{anything} left on the @cmdline{}, that is,
1384 either unprocessed options, or a remainder. A potential use of
1385 @code{cmdline-p} at a very early stage of your application could be to
1386 automatically display a help string if the @cmdline{} is effectively
1393 @node Integrity Checks, Option Retrieval, Context Creation, Using Clon
1394 @section Integrity Checks
1396 @cfindex{make-context}
1397 At this point, you know about the two necessary steps to initialize
1398 @clon{}: defining a synopsis and creating a context. If you paid
1399 attention to the quick start application (@pxref{Quick Start}), you may
1400 have noticed that @code{defsynopsis} was called as a top-level form
1401 whereas @code{make-context} was called from the function @code{main}. So
1404 First, I hope that you see why a context cannot be created as a toplevel
1405 form. If you do that, you will end-up creating a context relevant to the
1406 Lisp environment from which the application is created, not run.
1408 The synopsis, on the other hand, could be defined either as a toplevel
1409 form, as done in the quick start and the demo programs, or in the
1410 function @code{main}, just before making a context. There is a very good
1411 reason to prefer a toplevel form however: that reason is called
1412 ``integrity checks''.
1414 When you define a synopsis (or any synopsis item, for that matter),
1415 @clon{} performs a number of checks to make sure that you're making a
1416 sensible use of the library. In fact, the number of semantic mistakes
1417 that you can make is quite puzzling. You could for instance define
1418 several options with identical names, forget to provide a fallback or
1419 default value when it is required, provide invalid fallback or default
1420 values, and the list goes on and on. These are just a few examples but
1421 there are many more, and @clon{} checks all of those (I think).
1423 Since those mistakes relate to the definition of the application itself,
1424 they do not depend on a particular execution of it. Consequently, the
1425 sooner @clon{} catches them, the better. If you define your
1426 application's synopsis as a toplevel form, @clon{} will be able to
1427 perform its integrity checks when the application is created, not only
1428 when it is used. In other words, you won't be able to get a working
1429 application until your use of @clon{} is semantically correct.
1431 This is why it is strongly recommended to create synopsis from toplevel
1432 forms, and this also explains why @clon{} chooses @emph{not} to provide
1433 an @code{initialize} function that would wrap around @code{defsynopsis}
1434 and @code{make-context} together.
1441 @node Option Retrieval, Help, Integrity Checks, Using Clon
1442 @section Option Retrieval
1443 @cindex Runtime Phase
1444 @cindex Phase, runtime
1445 @cindex Retrieval, of options
1446 @cindex Options Retrieval
1448 During the runtime phase of @clon{}, your main activity will be to
1449 retrieve options and their values. @clon{} provides two techniques for
1450 retrieving options: you can request the value for a specific option
1451 directly, or you can process the @cmdline{} sequentially, which is the
1452 more traditional approach.
1454 @cindex Command-Line
1456 Both of these techniques can be freely combined together at any time,
1457 because @clon{} keeps track of the current status of the @cmdline{}. In
1458 fact, @clon{} never works on the original @cmdline{}, but uses a mutable
1459 @emph{copy} of it after parsing. If you want to access the real
1460 @cmdline{} of your application (except for the compiler-specific
1461 options, see @ref{Not Dumping Executables}), you may use the
1462 @code{cmdline} function, which is a wrapper around an
1463 implementation-dependent way to access it.
1466 Finally, remember that the @cmdline{} is scanned from left to right
1467 during option retrieval (@pxenduserref{Option Retrieval}).
1470 * Explicit Retrieval:: Accessing options by name
1471 * Sequential Retrieval:: Accessing options in order
1474 @node Explicit Retrieval, Sequential Retrieval, Option Retrieval, Option Retrieval
1475 @subsection Explicit Retrieval
1476 @cindex Options Retrieval, explicit
1477 @cindex Retrieval, of options, explicit
1478 Since @clon{} lets you retrieve options on demand (at any time), it
1479 makes sense to be able to request the value of a specific option
1480 explicitely. For instance, you might want to try the @samp{--help}
1481 option first, without looking at the rest of the @cmdline{} because the
1482 application will in fact quit immediately after having displayed the
1485 @defun getopt :KEY VALUE@dots{}
1486 Retrieve the value of a specific option. The following @var{:KEY}s are
1487 currently available.
1492 @fkindex{getopt,:short-name}
1493 @fkindex{getopt,:long-name}
1494 Use one of these 2 keys to specify the name of the option you wish to
1497 @fkindex{getopt,:option}
1498 Alternatively, you can use a reference to an option object
1499 (@pxref{Constructors}).
1502 This function return two values: the option's value and the value's
1503 source (@pxenduserref{Value Sources}).
1506 The value's source may have the following forms:
1508 @item (:cmdline @var{NAME})
1509 @cindex Values, source, @cmdline{}
1510 This is for options found on the @cmdline{}. @var{NAME} is the name used
1511 on the @cmdline{}. It can be the option's long or short name, or a
1512 completed long name if the option's name was abbreviated. A completed
1513 name displays the omitted parts in parentheses (@code{"he(lp)"} for
1515 @item (:fallback @var{NAME})
1516 @cvopindex{:fallback-value}
1517 @cindex Values, source, fallback
1518 The same but when the fallback value is used, that is, when an option is
1519 not provided with its (optional) argument.
1520 @item (:default @var{NAME})
1521 @cvopindex{:default-value}
1522 @cindex Values, source, default
1523 The same, but when the default value is used (because there is no
1525 @item (:environment @var{VAR})
1527 @cindex Values, source, environment
1528 This is for options not found on the @cmdline{} but for which there is
1529 an associated environment variable set in the application's environment.
1530 @var{VAR} is the name of the corresponding environment variable.
1532 @cvopindex{:default-value}
1533 @cindex Values, source, default
1534 This is for options not found anywhere, but for which a default value
1540 Note that because flags don't take any argument, @code{getopt} returns a
1541 virtual value of @code{t} when they are found or a corresponding
1542 environment variable exists in the environment. For the same reason, a
1543 flag's value source may ony be @code{(:cmdline @var{NAME})} or
1544 @code{(:environment @var{VAR})}.
1547 When an option is not found anywhere and there is no default value,
1548 @code{getopt} just returns nil (no second value). Also, note that when
1549 your option accepts @code{nil} as a value, you @emph{need} to handle the
1550 second retrun value to make the difference between an option not found,
1551 and an actual value of @code{nil}.
1554 @node Sequential Retrieval, , Explicit Retrieval, Option Retrieval
1555 @subsection Sequential Retrieval
1556 @cindex Options Retrieval, sequential
1557 @cindex Retrieval, of options, sequential
1558 The more traditional approach to option retrieval is to scan the
1559 @cmdline{} for options in their order of appearance. @clon{} supports
1560 this by providing you with one function and two macros, as explained
1563 @defun getopt-cmdline
1564 Get the @dfn{next} @cmdline{} option, that is, the first option on the
1565 @cmdline{} that has not been previously retrieved, either explicitely or
1568 When there are no more options on the @cmdline{}, this function returns
1569 @code{nil}. Otherwise, four values are returned: the corresponding
1570 option object from the synopsis definition (@pxref{Constructors}), the
1571 name used on the @cmdline{}, the option's value and the value source
1572 (@code{:cmdline}, @code{:fallback} or @code{:default}). As in the case
1573 of explicit retrieval (@pxref{Explicit Retrieval}), the option's name
1574 may be completed in case of abbreviation.
1576 @rfindex{short-name}
1578 @copindex{:short-name}
1579 @copindex{:long-name}
1580 Unless you keep references to all your option objects (and thus can
1581 compare them directly to the one returned by this function), you can
1582 still identify the retrieved option by using the @code{short-name} and
1583 @code{long-name} readers on it: simply use @code{(long-name
1584 @var{OPTION})} or @code{(short-name @var{OPTION})} and you will get the
1585 corresponding strings.
1588 @defmac multiple-value-getopt-cmdline (OPTION NAME VALUE SOURCE) BODY
1589 Evaluate @var{BODY} with @var{OPTION}, @var{NAME}, @var{VALUE} and
1590 @var{SOURCE} bound to the values returned by the @code{getopt-cmdline}
1591 function above. Note that @var{BODY} is not evaluated if there was no
1592 remaining option on the @cmdline{}, so you don't need to conditionalize
1593 on @var{OPTION} being @code{null} yourself.
1596 @defmac do-cmdline-options (OPTION NAME VALUE SOURCE) BODY
1597 As above, but loop over all @cmdline{} options.
1604 @node Help, , Option Retrieval, Using Clon
1607 One of the first motivations in the design of @clon{} was to automate
1608 the generation of the help string, which is a very boring maintenance
1609 task to do by hand. The application's synopsis contains all the
1610 necessary information to do so. In order to print your application's
1611 help string, use the @code{help} function.
1613 @defun help [@code{:item} ITEM]
1614 @bioindex{search-path}
1615 @bievindex{SEARCH_PATH}
1616 @bioindex{highlight}
1617 @bievindex{HIGHLIGHT}
1620 @bioindex{line-width}
1621 @bievindex{LINE_WIDTH}
1622 Print the application's help string. Printing honors the search path,
1623 theme, line width and highlight settings provided by the corresponding
1624 built-in options (@pxenduserref{Theme Mechanism}).
1627 @fkindex{help,:item}
1628 By default, @code{help} prints the whole application help string,
1629 excluding hidden items. However, if you have kept a reference to any
1630 synopsis item (option, text, group), you can pass it as the value of the
1631 @code{:item} key, and @clon{} will only print the help string for that
1632 particular item. In this case however, the hidden state of the item is
1633 discarded (but @emph{not} the ones of sub-items).
1636 @cindex Built-In Groups
1637 @cindex Groups, built-in
1638 @cindex Hidden Groups
1639 @cindex Groups, hidden
1640 For instance, the @clon{} built-in group is normally hidden, so it
1641 doesn't show up in the global help string, but the @bioption{help}
1642 option uses the @code{help} function on it explicitely, so it discards
1645 Here is a potentially useful application of hidden groups in conjunction
1646 with the @code{:item} key. Look at ImageMagick's @file{convert}
1647 program's help string for instance: it is 276 lines long. Gosh. The help
1648 string is decomposed into several categories: image settings, image
1649 operators, misc options @etc{}. If I were to implement this program, I
1650 would rather have the @option{--help} option display an overview of the
1651 program, advertise @option{--version} and a couple of others, and I
1652 would then implement @option{--help} as an enumeration for listing every
1653 option category individually (they would normally be stored in hidden
1654 groups). The user could then use @option{--help=settings},
1655 @option{--help=operators} and so on to display only the category she's
1658 Finally, here is potentially useful application of hidden options that
1659 are never ever displayed in any help string whatsoever, and I mean,
1660 like, ever. This is the perfect tool for backdoor'ing a program. For
1661 instance, if you ever need to implement a
1662 @option{--discard-all-security-measures-and-blow-the-nuke} option, then
1663 you'd better have it hidden@dots{}
1667 @c ====================================================================
1669 @c ====================================================================
1670 @node Extending Clon, Advanced Usage, Using Clon, Top
1671 @chapter Extending Clon
1673 As you know, @clon{} already provides seven built-in option types: flags
1674 and six other types for valued options (@pxref{Built-In Valued
1675 Options}). After using @clon{} for a while, you may find that however
1676 brilliant and perfectly designed it is, none of the provided built-in
1677 types fullfill your requirements exactly. There are two ways around
1678 this: the right way and the wrong way (hint).
1680 @voindex{Strings,stropt}
1681 The wrong, although perhaps quicker way would be to use the
1682 @code{stropt} option type to simply retrieve unprocessed string values,
1683 and then do whatever tweaking required on them. In doing so, you risk
1684 reinventing some of @clon{}'s wheels.
1686 The right way is to define a new option type. Properly defined option
1687 types are a good thing because they allow for reusability and also
1688 extensibility, since new option types can always be defined on top of
1690 @voindex{Enumerations,enum}
1691 In this chapter we explain how to extend @clon{} by providing new option
1692 types. We illustrate the process with the example of the built-in
1695 @cindex Valued Options
1696 @cindex Options, valued
1698 Oh, and I almost forgot. I hope it is obvious to everyone that new
1699 option types are always @emph{valued}. There's no point in extending
1700 @clon{} with options that don't take any arguments, since we already
1704 * New Option Types:: In four steps
1705 * Extension Tips:: Some advice
1712 @node New Option Types, Extension Tips, Extending Clon, Extending Clon
1713 @section New Option Types
1714 @cindex Option Types, in files
1715 @cindex Files, one per option type
1716 @pkgindex{com.dvlsoft.clon}
1717 From a software engineering point of view, it is better to implement new
1718 option types in a file of their own, preferably named after the option
1719 type itself, and to put this file in the @clon{} package, like this:
1723 (in-package :com.dvlsoft.clon)
1727 Creating your own option type involves 5 steps: providing a class for
1728 them, implementing three protocols related to argument/value tweaking,
1729 and providing a constructor function. We now review those 5 steps in
1733 * New Option Classes:: Step 1
1734 * Value Check Protocol:: Step 2
1735 * Argument Conversion Protocol:: Step 3
1736 * Error Management:: In-between steps coffee time!
1737 * Value Stringification Protocol:: Step 4
1738 * Constructor Functions:: Step 5
1741 @node New Option Classes, Value Check Protocol, New Option Types, New Option Types
1742 @subsection New Option Classes
1744 @clsindex{valued-option}
1745 @clon{} maintains a class hierarchy for all option types. The mother of
1746 all option types is the @code{option} abstract class. It handles the
1747 options'short and long names, description and associated environment
1748 variable (@pxref{Common Properties}). Valued options inherit from an
1749 abstract subclass of @code{option} called @code{valued-option}. This
1750 class handles the option's argument name and status (optional or
1751 mandatory), fallback and default values (@pxref{Common Valued Option
1754 @cindex User-Defined Option Classes
1755 @cindex Option Classes, user-defined
1756 In order to create a new option type, use the @code{defoption} macro.
1758 @defmac defoption CLASS SUPERCLASSES SLOTS &rest OPTIONS
1759 Create a new option CLASS and register it with @clon{}.
1760 Syntactically, thismacro behaves like @code{defclass}. Option types
1761 created like this implicitely inherit from @code{valued-option} and in
1762 turn @code{option}, so you don't need to put them explicitely in the
1763 @var{SUPERCLASSES} list.
1766 Let's look at the enumeration example now.
1770 (defoption enum (enum-base)
1771 ((argument-name ;; inherited from the VALUED-OPTION class
1773 (:documentation "The ENUM class.
1774 This class implements options whose values belong to a set of keywords."))
1778 @voindex{Enumerations,enum}
1779 @vopindex{Enumerations,enum,:enum}
1780 @voindex{Extended Switches,xswitch}
1781 @vopindex{Extended Switches,xswitch,:enum}
1782 @clsindex{enum-base}
1783 As you can see, this class inherits from @code{enum-base}, which is the
1784 class handling the @code{:enum} property. The reason for this split is
1785 that there are currently two option types providing enumeration-like
1786 facility: @code{enum} and @code{xswitch}, so @code{xswitch} also
1787 inherits from @code{enum-base}.
1789 @clsindex{valued-option}
1790 @cvopindex{:argument-name}
1791 There are no new slots in this class, but the @code{argument-name} slot
1792 provided by the @code{valued-option} class has its initform changed from
1793 @code{"ARG"} to @code{"TYPE"}.
1795 @node Value Check Protocol, Argument Conversion Protocol, New Option Classes, New Option Types
1796 @subsection Value Check Protocol
1797 @cindex Value Check Protocol
1798 @cindex Protocols, value check
1799 Now that we have our new option class, we need to implement the
1800 so-called @dfn{value check} protocol. This protocol is used to make sure
1801 that values provided for options of your new type actually comply with
1802 the type in question. Values going through this protocol are fallback
1803 values, default values, and values provided from a debugger restart
1804 (@pxenduserref{Error Management}). In the case of fallback and default
1805 values (which, by the way, are provided by @emph{you}, the @clon{}
1806 user), the check is performed only once, when the option object is
1807 created. Values provided from a debugger restart come from the
1808 application end-user, and hence are checked every time.
1810 The value check protocol is implemented through a @code{check} generic
1811 function for which you must provide a method.
1813 @deffn {Generic Function} check OPTION VALUE
1815 @ecindex invalid-value
1816 Check that @var{VALUE} is valid for @var{OPTION}. If @var{VALUE} is
1817 valid, return it. Otherwise, raise an @code{invalid-value} error.
1820 As you can see, you need to provide a method with the first argument
1821 specialized to your new option type. This method must return @var{VALUE}
1822 if it is okay, and raise an @code{invalid-value} error otherwise.
1824 @ecindex invalid-value
1825 @clon{} maintains a hierarchy of error conditions. The
1826 @code{invalid-value} error condition is defined like this:
1830 (define-condition invalid-value (option-error)
1831 ((value :documentation "The invalid value."
1834 (comment :documentation "An additional comment about the error."
1838 (:report (lambda (error stream)
1839 (format stream "Option ~A: invalid value ~S.~@[~%~A~]"
1840 (option error) (value error) (comment error))))
1841 (:documentation "An invalid value error."))
1845 @ecindex invalid-value
1846 @ecsindex{invalid-value,value}
1847 @ecsindex{invalid-value,comment}
1848 When the error is raised, you must fill in the @code{value} and
1849 @code{comment} slots appropriately.
1850 @ecindex option-error
1851 @ecsindex{option-error,option}
1852 The super-condition @code{option-error} provides an additional
1853 @code{option} slot that you must also fill in when the error is raised.
1855 @gfmindex{check,@r{Enumerations (}enum@r{)}}
1856 @voindex{Enumerations,enum}
1857 @vopindex{Enumerations,enum,:enum}
1858 @findex list-to-string
1859 Let's look at the enumeration example now.
1863 (defmethod check ((enum enum) value)
1864 "Check that VALUE is a valid ENUM."
1865 (unless (member value (enum enum))
1866 (error 'invalid-value
1869 :comment (format nil "Valid values are: ~A."
1870 (list-to-string (enum enum)
1871 :key #'prin1-to-string))))
1876 This code should be self-explanatory. We check that the value we got
1877 belongs to the enumeration. @code{list-to-string} is a utility function
1878 that will separate every element with comas in the resulting string.
1880 @node Argument Conversion Protocol, Error Management, Value Check Protocol, New Option Types
1881 @subsection Argument Conversion Protocol
1882 @cindex Argument Conversion Protocol
1883 @cindex Protocols, argument conversion
1884 The next protocol we need to implement is the so-called @dfn{argument
1885 conversion} protocol. This protocol is used to convert option arguments
1886 (that is, strings) to an actual value of the proper type. Arguments
1887 going through this protocol come from the @cmdline{}, the value of an
1888 environment variable or a debugger restart (@pxenduserref{Error
1889 Management}). Also, note that @clon{} assumes that you implement this
1890 protocol correctly, so no value check is performed on values coming from
1891 the conversion of an argument.
1893 The conversion protocol is implemented through a @code{convert} generic
1894 function for which you must provide a method.
1896 @deffn {Generic Function} convert OPTION ARGUMENT
1897 @gfsubindex{convert}
1898 @ecindex invalid-argument
1899 Convert @var{ARGUMENT} to @var{OPTION's} value. If @var{ARGUMENT} is
1900 invalid, raise an @code{invalid-argument} error.
1903 As you can see, you need to provide a method with the first argument
1904 specialized to your new option type. This method must return the
1905 conversion of @var{ARGUMENT} to the appropriate type if it is valid, and
1906 raise an @code{invalid-argument} error otherwise.
1908 @ecindex invalid-argument
1909 The @code{invalid-argument} error condition is defined like this:
1913 (define-condition invalid-argument (option-error)
1914 ((argument :documentation "The invalid argument."
1918 (comment :documentation "An additional comment about the error."
1922 (:report (lambda (error stream)
1923 (format stream "Option ~A: invalid argument ~S.~@[~%~A~]"
1924 (option error) (argument error) (comment error))))
1925 (:documentation "An invalid argument error."))
1929 @ecindex invalid-argument
1930 @ecsindex{invalid-argument,argument}
1931 @ecsindex{invalid-argument,comment}
1932 When the error is raised, you must fill in the @code{argument} and
1933 @code{comment} slots appropriately.
1934 @ecindex option-error
1935 @ecsindex{option-error,option}
1936 As before, the super-condition @code{option-error} provides an
1937 additional @code{option} slot that you must also fill in when the error
1940 @gfmindex{convert,@r{Enumerations (}enum@r{)}}
1941 @voindex{Enumerations,enum}
1942 @vopindex{Enumerations,enum,:enum}
1943 @findex closest-match
1944 Let's look at the enumeration example now.
1948 (defmethod convert ((enum enum) argument)
1949 "Convert ARGUMENT to an ENUM value."
1950 (or (closest-match argument (enum enum) :ignore-case t :key #'symbol-name)
1951 (error 'invalid-argument
1954 :comment (format nil "Valid arguments are: ~A."
1955 (list-to-string (enum enum)
1956 :key (lambda (value)
1957 (stringify enum value)))))))
1962 Since enumerations allow their arguments to be abbreviated, a utility
1963 function named @code{closest-match} is used to find the closest match
1964 between an argument and the possible values. Otherwise, an
1965 @code{invalid-argument} error is raised. For an explanation of
1966 @code{stringify}, @xref{Value Stringification Protocol}.
1968 @node Error Management, Value Stringification Protocol, Argument Conversion Protocol, New Option Types
1969 @subsection Error Management
1971 @cindex Debugger restarts
1972 Let's take a short break in our @clon{} extension process. We have seen
1973 that @clon{} may throw errors in different situations, including invalid
1974 arguments or values. The end-user manual advertises that the interactive
1975 error handler offers a set of ``options to fix problems'' (if you don't
1976 know what I'm talking about, please read @enduserref{Error Management}
1977 and you will know). Well, you may have guessed that these options are
1978 simply ``restarts'' (of course, we don't use that term there, as we
1979 wouldn't want to frighten the casual user, or would we?).
1981 When you ship your application, you are encouraged to disable the
1982 debugger in the standalone executable because that also might scare the
1983 casual user a little bit (the end-user manual only mentions the
1984 @code{none} error-handler to explain that people shouldn't use it). The
1985 way error handling is done in @cl{} standalone executables is
1986 implementation-dependent, so please refer to your favorite compiler's
1987 documentation. More generally, the behavior of @cl{} standalone
1988 executables may depend on:
1992 the state of the Lisp environment when the application was dumped, which
1993 may in turn depend on @cmdline{} options passed to the Lisp itself
1994 (@pxref{Dumping Executables}),
1997 the arguments passed to the dumping function (look at @clon{}'s
1998 @code{dump} macro to see what it does),
2003 No, really, @cl{} is no fun at all.
2005 @node Value Stringification Protocol, Constructor Functions, Error Management, New Option Types
2006 @subsection Value Stringification Protocol
2007 Okay, back to implementing our new option type.
2009 @cindex Value Stringification Protocol
2010 @cindex Protocols, value stringification
2011 The third and last protocol we need to implement is called the
2012 @dfn{value stringification} protocol. This protocol can be seen as the
2013 reverse protocol for argument conversion (@pxref{Argument Conversion
2014 Protocol}): its purpose is to transform an option's value into a
2015 corresponding argument that the end-user could have provided in order to
2019 @cvopindex{:fallback-value}
2020 @cindex Values, source, fallback
2021 @cvopindex{:default-value}
2022 @cindex Values, source, default
2023 @gfmindex{convert,@r{Enumerations (}enum@r{)}}
2024 The main use for this protocol is to advertise the fallback and default
2025 values correctly in help strings: the end-user does not want to see
2026 those @emph{values}, but rather the @emph{argument} that would lead to
2027 them. However, you are free to use it wherever you like (see the
2028 @code{convert} method for @code{enum} options for instance).
2030 The value stringification protocol is implemented through a
2031 @code{stringify} generic function for which you must provide a method.
2033 @deffn {Generic Function} stringify OPTION VALUE
2034 @gfsubindex{stringify}
2035 Transform OPTION's @var{VALUE} into an argument.
2038 I admit that this function could also have been called
2039 @code{argumentize} or even @code{deconvertify}. As you can see, you need
2040 to provide a method with the first argument specialized to your new
2041 option type. You can assume that @var{VALUE} is a valid value for your
2042 option, so no checking is necessary and no error needs to be raised.
2044 @gfmindex{stringify,@r{Enumerations (}enum@r{)}}
2045 @voindex{Enumerations,enum}
2046 Let's look at the enumeration example now.
2050 (defmethod stringify ((enum enum) value)
2051 "Transform ENUM's VALUE into an argument."
2052 (string-downcase (symbol-name value)))
2056 Pretty straightforward, right?
2059 @node Constructor Functions, , Value Stringification Protocol, New Option Types
2060 @subsection Constructor Functions
2061 @cindex Constructors, for options objects
2062 @cindex Option Constructors
2063 The last required step to complete our new option type extension is to
2064 provide a @dfn{constructor} function that wraps around
2065 @code{make-instance} on the corresponding option class. I won't insult
2066 you by explaining how to write a constructor. Let me just give four good
2067 reasons why providing constructors is important.
2069 Providing a constructor for every new option type is important because:
2074 it is a good software engineering practice,
2080 and above all, it makes your new option type automatically available in
2081 calls to @code{defsynopsis} and @code{defgroup} (@pxref{Synopsis Items}
2082 and @ref{Group Definition}).
2086 @voindex{Enumerations,enum}
2088 Let's look at the enumeration example now.
2092 (defun make-enum (&rest keys
2093 &key short-name long-name description
2094 argument-name argument-type
2095 enum env-var fallback-value default-value
2097 "Make a new enum option.
2098 - SHORT-NAME is the option's short name (without the dash).
2100 - LONG-NAME is the option's long name (without the double-dash).
2102 - DESCRIPTION is the option's description appearing in help strings.
2104 - ARGUMENT-NAME is the option's argument name appearing in help strings.
2105 - ARGUMENT-TYPE is one of :required, :mandatory or :optional (:required and
2106 :mandatory are synonyms).
2107 It defaults to :optional.
2108 - ENUM is the set of possible values.
2109 - ENV-VAR is the option's associated environment variable.
2111 - FALLBACK-VALUE is the option's fallback value (for missing optional
2113 - DEFAULT-VALUE is the option's default value, if any.
2114 - When HIDDEN, the option doesn't appear in help strings."
2115 (declare (ignore short-name long-name description
2116 argument-name argument-type
2117 enum env-var fallback-value default-value
2119 (apply #'make-instance 'enum keys))
2123 Woah, what a mouthful for a single line of code@dots{} Yeah, I'm a
2124 maniac and I like redundancy. I always restate all the available keys
2125 explicitely, and everything again in the docstring so that all the
2126 interesting information is directly available (I might change my mind as
2127 I grow older though).
2133 @node Extension Tips, , New Option Types, Extending Clon
2134 @section Extension Tips
2135 So that's it. Now you know how to extend @clon{} with your own option
2136 types. Here is some piece of advice that you might find useful in the
2140 * Incremental Option Types:: Doing without defoption
2141 * Lisp Option Abuse:: Thinking in end-user terms
2144 @node Incremental Option Types, Lisp Option Abuse, Extension Tips, Extension Tips
2145 @subsection Incremental Option Types
2147 If one of the built-in options is almost what you need, you may be
2148 tempted to subclass it directly instead of using @code{defoption}, and
2149 only change what's needed, After all, it's Lisp. Lisp is a world of
2150 mess@t{^D^D^D^D}freedom.
2156 @code{defoption} is not @emph{only} a convenience wrapper around
2157 @code{defclass}. It also arranges for @code{defsynopsis} and
2158 @code{defgroup} to recognize your new option type. So please, do use it
2161 @node Lisp Option Abuse, , Incremental Option Types, Extension Tips
2162 @subsection Lisp Option Abuse
2163 @voindex{Lisp Objects,lispobj}
2164 @vopindex{Lisp Objects,lispobj,:typespec}
2165 Along with the same lines, you may find that the @code{lispobj} type is
2166 all you need in many situations. Let's take an example. Suppose you want
2167 to implement a @code{--stars} option to assign a rank to a movie, from 0
2168 to 5. The lazy approach is to simply create a @code{lispobj} option with
2169 a @code{:typespec} (type specifier) of @code{(integer 0 5)} and you're
2172 But now, remember that the end-user of your application is probably not
2173 a Lisper (in fact, I would hope that @clon{} contributes to increasing
2174 the number of standalone @cl{} applications out there@dots{}). What do
2175 you think would be her reaction, if, after providing a bogus value to
2176 the @code{--stars} option, she get the following error message:
2179 Option 'stars': invalid argument "6".
2180 Argument "6" must evaluate to (integer 0 5).
2183 or worse, a @code{"Cannot parse argument"} error message because of a
2186 Not very friendly, right? In other words, you need to think in terms of
2187 what the end-user of your application will expect. In that particular
2188 situation, you might want to subclass @code{lispobj} (with
2189 @code{defoption}!) only to provide friendlier error messages.
2193 @c ====================================================================
2195 @c ====================================================================
2196 @node Advanced Usage, Conclusion, Extending Clon, Top
2197 @chapter Advanced Usage
2199 This chapter contains information about different features that are
2200 present in @clon{} because of design decisions, but that I expect to be
2201 used only rarely, if at all.
2204 * Multiple Clon Instances:: Different command-lines, synopsis or contexts
2205 * Programmatic Help Strings:: Beyond the --help option
2206 * Version Numbering:: In case you need to conditionalize
2210 @c -----------------------
2211 @c Multiple Clon Instances
2212 @c -----------------------
2213 @node Multiple Clon Instances, Programmatic Help Strings, Advanced Usage, Advanced Usage
2214 @section Multiple @clon{} Instances
2216 It is possible to use different instances of @clon{} in parallel in a
2217 single application, by using a virtual @cmdline{} instead of the real
2218 one, different synopsis and multiple contexts simultaneously.
2221 * Using Different Synopsis:: The default one, and the others
2222 * Using Different Command-Lines:: The real one, and the others
2223 * Using Multiple Contexts:: The current one, and the others
2224 * Potential Uses:: What to do with all that
2227 @node Using Different Synopsis, Using Different Command-Lines, Multiple Clon Instances, Multiple Clon Instances
2228 @subsection Using Different Synopsis
2229 @cindex Synopsis, default
2230 Did you notice that after defining a synopsis, there is actually never
2231 any explicit reference to it anymore? So where is the magick? In fact,
2232 there's no magick at all involved here.
2234 @vindex *default-synopsis*
2235 @foindex{defsynopsis,:make-default}
2236 @cfiaindex{make-synopsis,:make-default}
2237 @clon{} has a global variable named @code{*default-synopsis*} which
2238 holds the@dots{} default synopsis, yeah. When you define/create a
2239 synopsis with either @code{defsynopsis} or @code{make-synopsis}, it is
2240 automatically made the default one, unless you use the
2241 @code{:make-default} option/initarg with a value of @code{nil}, like
2245 (defsynopsis (:make-default nil) ...)
2251 (make-synopsis :make-default nil ...)
2254 @cfindex{make-context}
2255 When you create a context with @code{make-context}, the default synopsis
2256 is used implicitely, but you have two ways to avoid this.
2260 @vindex *default-synopsis*
2261 At any time in your program, you may change the value of
2262 @code{*default-synopsis*}. All subsequent calls to @code{make-context}
2263 will hence use this other synopsis.
2265 @cfiaindex{make-context,:synopsis}@c
2266 If you prefer to use another synopsis only temporarily, you can use the
2267 @code{:synopsis} initarg to @code{make-context} instead.
2270 @node Using Different Command-Lines, Using Multiple Contexts, Using Different Synopsis, Multiple Clon Instances
2271 @subsection Using Different Command-Lines
2272 In @ref{Context Creation}, we saw that a context object describes a
2273 particular instance of your application, most notably depending on the
2274 actual @cmdline{} the end-user provided. It turns out, however that the
2275 @cmdline{} doesn't need to be the actual program's @cmdline{}, as the
2276 user typed it. Any list of strings can act as a @cmdline{}.
2278 @cfiaindex{make-context,:cmdline}
2279 The function @code{make-context} has a @code{:cmdline} key that allows
2280 you to provide any list of strings that will act as the @cmdline{}. Of
2281 course, the default is to use the actual program's one.
2283 @node Using Multiple Contexts, Potential Uses, Using Different Command-Lines, Multiple Clon Instances
2284 @subsection Using Multiple Contexts
2285 @cindex Context, current
2286 Did you also notice that after creating a context, there is actually
2287 never any explicit reference to it anymore? So again, where is the
2288 magick? In fact, there's no magick at all involved here either.
2290 @vindex *current-context*
2291 @cfiaindex{make-context,:make-current}
2292 @clon{} has a global variable named @code{*current-context*} which holds
2293 the@dots{} current context, yeah. When you create a context with
2294 @code{make-context}, it is automatically made current, unless you use
2295 the @code{:make-current} initarg with a value of @code{nil}.
2297 @cindex Runtime Phase
2300 @findex cmdline-options-p
2303 @findex getopt-cmdline
2304 @findex multiple-value-getopt-cmdline
2305 @findex do-cmdline-options
2307 The whole runtime phase API of @clon{} uses a context implicitely. This
2308 involves @code{progname}, @code{remainder}, @code{cmdline-options-p},
2309 @code{cmdline-p}, @code{getopt}, @code{getopt-cmdline},
2310 @code{multiple-value-getopt-cmdline}, @code{do-cmdline-options} and
2311 @code{help}. As a consequence, it is possible to use @clon{} with
2312 multiple contexts at the same time. There are in fact three ways to
2317 @vindex *current-context*
2318 At any time in your program, you may change the value of
2319 @code{*current-context*}. All subsequent calls to the runtime phase API
2320 will hence use this other context.
2322 @clon{} also provides a macro which changes the current context for you.
2323 @defun with-context CONTEXT &body BODY
2324 Execute @var{BODY} with @code{*current-context*} bound to @var{CONTEXT}.
2327 @fkindex{progname,:context}@c
2328 @fkindex{remainder,:context}@c
2329 @fkindex{cmdline-options-p,:context}@c
2330 @fkindex{cmdline-p,:context}@c
2331 @fkindex{getopt,:context}@c
2332 @fkindex{getopt-cmdline,:context}@c
2333 @fkindex{help,:context}@c
2334 @foindex{multiple-value-getopt-cmdline,:context}@c
2335 @foindex{do-cmdline-options,:context}@c
2336 If you prefer to use another context only once, you can use the
2337 @code{:context} key instead. The whole runtime phase API of @clon{}
2338 understands it. For the functions @code{getopt}, @code{getopt-cmdline}
2339 and @code{help}, it's just another key in addition to those we've
2340 already seen. For the macros @code{multiple-value-getopt-cmdline} and
2341 @code{do-cmdline-options}, the key must appear at the end of the first
2342 (list) argument, like this:
2345 (multiple-value-getopt-cmdline (option name value :context ctx) ...)
2346 (do-cmdline-options (option name value :context ctx) ...)
2350 @node Potential Uses, , Using Multiple Contexts, Multiple Clon Instances
2351 @subsection Potential Uses
2352 By combining @clon{}'s ability to use a virtual @cmdline{}, different
2353 synopsis and multiple contexts, you can achieve very neat (read: totally
2354 useless) things. For instance, you could write an application that takes
2355 an option providing @cmdline{} arguments for an external program to be
2356 forked. Some revision control systems do that for controlling external
2357 @code{diff} programs for instance, so no big deal. The big deal is that
2358 you can completely control the validity of the external program's
2359 @cmdline{}, before it is forked, from your original one.
2361 Here is another idea, again related to revision control systems. Some of
2362 them feature a @cmdline{} syntax like the following:
2365 prog [global options] command [command-specific options]
2369 @cindex Command-Line, remainder
2370 @cindex Remainder, of command-line
2371 You can achieve this with @clon{} quite easily. In fact, the
2372 demonstration program called @file{advanced} in the distribution shows
2373 you how to do it. First, define a synopsis which only handles the global
2374 options, and provide a postfix of @code{"command [command-specific
2375 option]"} or something like that. This will authorize a @cmdline{}
2376 remainder which will start with the command name.
2378 Now, for every command in your program, define a specific synopsis with
2379 only the command-specific options. Get the remainder of the original
2380 @cmdline{} (@pxref{Command-Line Remainder}) and figure out which command
2381 was used. Depending on it, create a new context with the appropriate
2382 synopsis and the original @cmdline{}'s remainder as the new, virtual,
2383 @cmdline{}. You're done: retrieve global options from the first context,
2384 and command-specific ones from the second one.
2386 @cindex Help String, display
2388 What's even cooler is that you can display the command-specific options
2389 on demand quite easily as well (like what @file{git} does when you call
2390 it like this: @code{git commit --help} for instance): calling the
2391 @code{help} function on the original context gives you the global
2392 options's help string while calling it on the command-specific one will
2393 display the command-specific usage.
2395 @bioindex{search-path}
2396 @bievindex{SEARCH_PATH}
2397 @bioindex{highlight}
2398 @bievindex{HIGHLIGHT}
2401 @bioindex{line-width}
2402 @bievindex{LINE_WIDTH}
2403 One thing to remember here is that every context/synopsis duet you
2404 create gets its own set of built-in @clon{} options. As a consequence,
2405 there is currently no simple way to have a single set of built-in
2406 options apply to the whole application, for instance, to both a global
2407 and a command-specific context. Let me make this clearer: if your
2408 end-user calls @code{prog --clon-theme=foo command -h}, then the theme
2409 option will have no effect because it would only affect the global help
2410 option. In order to actually use the expected theme, your end-user would
2411 need to use @code{prog command --clon-theme=foo -h}. Depending on which
2412 cerebral emisphere (s)he prefers to use, this may seem logical or not.
2414 Finally, note that you can use the virtual @cmdline{} / specific
2415 synopsis technique recursively to manage complicated @cmdline{} syntax,
2416 for instance alternating options and non-options parts several times.
2418 In the future, @clon{} may provide better ways to achieve this kind of
2419 things (a notion of ``sub-context'' may be in order).
2423 @c -------------------------
2424 @c Programmatic Help Strings
2425 @c -------------------------
2426 @node Programmatic Help Strings, Version Numbering, Multiple Clon Instances, Advanced Usage
2427 @section Programmatic Help Strings
2432 @cindex Themes, standard, @t{refcard}
2433 @cindex Standard Themes, @t{refcard}
2434 So far, we've seen how to use the @code{help} function to implement a
2435 typical @code{--help} option. This is mostly intended for the end-user.
2436 There are also times when this function could be useful to @emph{you},
2437 the application developer. For instance, one could imagine that part of
2438 the compilation phase would involve generating the help string in order
2439 to include it in the manual. Another idea would be that @samp{make
2440 install} creates a @file{REFCARD} file in
2441 @file{/usr/local/share/doc/my-app/} which contains the help string
2442 formatted with the @code{refcard} theme, @etc{}.
2446 @bioindex{search-path}
2447 @bievindex{SEARCH_PATH}
2448 @bioindex{line-width}
2449 @bievindex{LINE_WIDTH}
2450 @bioindex{highlight}
2451 @bievindex{HIGHLIGHT}
2452 In such situations, calling the @code{help} function might not be
2453 directly associated with an end-user level option, or at least not
2454 @code{--help}, and you might not want to honor the end-user level
2455 settings for theme, search path, line-width, or highlighting either
2456 (remember that these settings might come from the environment variables
2457 associated with @bioption{theme}, @bioption{search-path},
2458 @bioption{line-width} and @bioption{highlight}).
2460 @fkindex{help,:theme}
2461 @fkindex{help,:search-path}
2462 @fkindex{help,:line-width}
2463 @fkindex{help,:highlight}
2464 Because of this, the @code{help} function provides additional keys that
2465 allow you to override those settings (they are in fact stored in the
2466 context object). The keys in question are: @code{:theme},
2467 @code{:search-path}, @code{:line-width} and @code{:highlight}.
2469 @fkindex{help,:output-stream}
2470 @vindex *standard-output*
2471 In addition to that, there is an @code{:output-stream} key which
2472 defaults to @code{*standard-output*} which you could use for instance to
2473 write directly to a file. Note that there is no end-user level access to
2478 @c -----------------
2479 @c Version Numbering
2480 @c -----------------
2481 @node Version Numbering, , Programmatic Help Strings, Advanced Usage
2482 @section Version Numbering
2485 As @clon{} evolves over time, you might one day feel the need for
2486 conditionalizing your code on the version of the library. While the
2487 end-user of your application has limited means to access the current
2488 version number of @clon{} (see @enduserref{Clonification} and the
2489 built-in option @bioption{version}), you, the application programmer
2490 and @clon{} user, have a finer grained access to it.
2492 The first thing you can do to access the current version number of
2493 @clon{} is use the @code{version} function (this is in fact the function
2494 bound to the @bioption{version} option).
2496 @defun version &optional (TYPE :number)
2497 Return the current version number of @clon{}. @var{TYPE} can be one of
2498 @code{:number}, @code{:short} or @code{:long}. For @code{:number}, the
2499 returned value is a fixnum. Otherwise, it is a string.
2502 A @clon{} version is characterized by 4 elements as described below.
2505 @vindex +release-major-level+
2506 A major version number stored in the constant
2507 @code{+release-major-level+}.
2509 @vindex +release-minor-level+
2510 A minor version number, stored in the constant
2511 @code{+release-minor-level+}.
2513 @vindex +release-status+
2514 A release status stored in the constant @code{+release-status+}. The
2515 status of a release can be @code{:alpha}, @code{:beta}, @code{:rc}
2516 (standing for ``release candidate'') or @code{:patchlevel}. These are in
2517 effect 4 levels of expected stability.
2519 @vindex +release-status-level+
2520 A status-specific version number stored in the constant
2521 @code{+release-status-level+}. Status levels start at 1 (alpha 1, beta 1
2522 and release candidate 1) except for stable versions, in which case patch
2523 levels start at 0 (@eg{} 2.4.0).
2526 @vindex +release-name+
2527 In addition to that, each version of @clon{} (in the sense
2528 @emph{major.minor}, regardless of the status) has a name, stored in the
2529 constant @code{+release-name+}. The general theme for @clon{} is ``Great
2530 Jazz Musicians'', and specifically for the 1.x series: ``Great Saxophone
2531 Players''. Anyone daring to mention Kenny G at that point will be shot
2534 Here is how the @code{version} function computes its value.
2537 A version @code{:number} is computed as @emph{major . 10000 + minor .
2538 100 + patchlevel}, effectively leaving two digits for each level. Note
2539 that alpha, beta and release candidate status are ignored in version
2540 numbers (this is as if the corresponding status level was considered to
2541 be always 0). Only stable releases have their level taken into account.
2543 A @code{:short} version will appear like this for unstable releases:
2544 1.3a4, 2.5b8 or 4.2rc1. Remember that alpha, beta or release candidate
2545 levels start at 1. Patchlevels for stable releases start at 0 but 0 is
2546 ignored in the output. So for instance, version 4.3.2 will appear as-is,
2547 while version 1.3.0 will appear as just 1.3.
2549 A @code{:long} version is expanded from the short one, and includes the
2550 release name. For instance, 1.3 alpha 4 "Bill Evans", 2.5 beta 8 "Scott
2551 Henderson", 4.2 release candidate 1 "Herbie Hancock" or 4.3.2 "Chick
2552 Corea". As for the short version, a patchlevel of 0 is ignored in the
2553 output: 1.3 "Bill Evans".
2558 @c ====================================================================
2560 @c ====================================================================
2561 @node Conclusion, Technical Notes, Advanced Usage, Top
2564 So that's it I guess. You know all about @clon{} now. The next step is
2565 to actually use it to clonify your favorite application, write new
2566 applications using it and contaminate the world with standalone @cl{}
2567 programs, featuring unprecedented @cmdline{} power and thrill-a-minute
2570 Now, go Luke. The Attack of the @clon{} is ready to begin.
2574 @c ====================================================================
2576 @c ====================================================================
2577 @node Technical Notes, API Quick Reference, Conclusion, Top
2578 @appendix Technical Notes
2580 This chapter contains important information about the library's
2581 configuration, supported platforms, non-ANSI features and
2582 portability concerns.
2585 * Configuration:: Pre-loading parameters
2586 * Non-ANSI Features:: Requiring operating system access
2587 * Supported Platforms:: Systems, compilers and dependencies
2588 * Dumping Executables:: Convenience wrappers
2589 * Not Dumping Executables:: Using Clon interactively
2596 @node Configuration, Non-ANSI Features, Technical Notes, Technical Notes
2597 @section Configuration
2598 @cindex Configuration
2599 @vindex com.dvlsoft.clon.configuration
2600 Some aspects of @clon{}'s behavior can be configured @emph{before} the
2601 ASDF system is actually loaded. @clon{} looks for configuration options
2602 in a variable called @code{com.dvlsoft.clon.configuration} in the
2603 @code{cl-user} package. If set, this variable should contain a property
2604 list of configuration options and their corresponding values. Currently,
2605 the following options are provided.
2608 @item :swank-eval-in-emacs
2609 @coindex{swank-eval-in-emacs}@c
2610 @vindex slime-enable-evaluate-in-emacs
2611 This option is only useful if you use Slime, and mostly if you plan on
2612 hacking @clon{} itself. The library provides indentation information for
2613 some of its functions directly embedded in the code. This information
2614 can be automatically transmitted to (X)Emacs when the ASDF system is
2615 loaded if you set this option to @code{t}. However, note that for this
2616 to work, the Slime variable @code{slime-enable-evaluate-in-emacs} must
2617 also be set to @code{t} in your (X)Emacs session. If you're interested
2618 to know how this process works, I have described it in the following
2620 @uref{http://www.didierverna.com/sciblog/index.php?post/2011/07/20/One-more-indentation-hack}.
2622 @coindex{restricted}@c
2623 @cindex Restricted Mode
2624 Some non-ANSI features of @clon{} require external functionality that
2625 may not be available in all contexts. Normally, @clon{} should
2626 autodetect this and switch to so-called @emph{restricted mode} at
2627 build-time (@pxref{Non-ANSI Features}). If @clon{} has failed to
2628 autodetect the problem (in which case I would like to know), or if for
2629 some reason, you explicitly want to disable those features, you may set
2630 the @code{:restricted} configuration option to @code{t}.
2633 This option is only used by the ABCL port. @ref{Dumping Executables},
2634 provides more information on its use.
2638 @c -----------------
2639 @c Non-ANSI Features
2640 @c -----------------
2641 @node Non-ANSI Features, Supported Platforms, Configuration, Technical Notes
2642 @section Non-ANSI Features
2643 One feature of @clon{} that is beyond the ANSI standard is terminal
2644 autodetection (it requires an @code{ioctl} call and hence a foreign
2645 function interface). Terminal autodetection is used in several
2646 situations, for turning on highlighting automatically and for detecting
2647 a terminal line width.
2649 @cindex Restricted Mode
2650 If, for some reason, terminal autodetection is not available, @clon{}
2651 will work in so-called @emph{restricted mode}. This means that
2652 @bioption{highlight=auto} won't work (highlighting will @emph{not} be
2653 turned on automatically on a @tty{}). For the same reason, unless
2654 otherwise specified via either the @code{COLUMNS} environment variable
2655 or the @bioption{line-width} option, terminal output will be formatted
2656 for 80 columns regardless of the actual terminal width
2657 (@pxenduserref{Global Control}).
2660 @c ----------------------
2661 @c Supported Platforms
2662 @c ----------------------
2663 @node Supported Platforms, Dumping Executables, Non-ANSI Features, Technical Notes
2664 @section Supported Platforms
2665 @clon{} currently works on Unix (including MacOS X) and Windows (Cygwin
2666 or MinGW) and has been ported to 6 @cl{} implementations. The following
2667 table lists the supported platforms.
2669 @multitable {Compiler} {Minimum Version} {@code{cffi} (optional)}
2670 @headitem Compiler @tab Minimum Version @tab Dependencies
2681 @tab 11.1.2@footnote{more precisely, git revision
2682 3e2e5f9dc3c5176ef6ef8d7794bfa43f1af8f8db}
2686 @tab @code{cffi} (optional)
2688 @tab 0.24.0@footnote{more precisely, svn trunk revision 13156}
2692 @unnumberedsubsec ABCL specificities
2693 @clon{}'s ABCL port currently has two limitations:
2696 @bioindex{highlight}@c
2697 @bioindex{line-width}@c
2699 @cindex Restricted Mode
2700 It only works in restricted mode (@pxref{Non-ANSI Features}).
2702 Since Java doesn't have a @code{putenv} or @code{setenv} function (!!),
2703 the @code{modify-environment} restart, normally proposed when an
2704 environment variable is set to a bogus value, is unavailable
2705 (@pxenduserref{Error Management}).
2708 @unnumberedsubsec CLISP specificities
2709 @cindex Restricted Mode
2710 As mentioned in the above table, CLISP's dependency on @code{cffi} is
2711 optional. CLISP needs @code{cffi} in order to implement terminal
2712 autodetection only (note that many other implementations come with their
2713 own foreign function interface). If @code{cffi} cannot be found when the
2714 ASDF system is loaded (or if CLISP itself has been compiled without
2715 @code{ffi} support), you get a big red blinking light and a warning but
2716 that's all. @clon{} will still work, although in restricted mode.
2719 @c -------------------
2720 @c Dumping Executables
2721 @c -------------------
2722 @node Dumping Executables, Not Dumping Executables, Supported Platforms, Technical Notes
2723 @section Dumping Executables
2725 Creating standalone executables is orthogonal to @clon{}. @clon{} is
2726 just a library that you might want to use, and in fact, it is also
2727 possible to use it without dumping executables at all (@pxref{Not
2728 Dumping Executables}).
2732 Unfortunately, there is no standard way to dump executables from Lisp.
2733 We're entering the portability mine field here. @clon{}, however, wants
2734 to help. We've already seen that it provides utility wrappers like
2735 @code{exit} and @code{dump} to make your life easier (I mean, more
2736 portable) in @ref{Quick Start}. If you're not interested in portability
2737 or if you prefer to do it your own way, you don't @emph{need} to use
2738 those wrappers. If you do, however, please read on.
2740 Continuing on the quickstart example, the table below provides
2741 ready-to-use @cmdline{} samples for dumping the program with the
2742 compilers currently supported. Remember that they work in conjunction
2743 with the @code{dump} macro mentionned above.
2747 @code{CC=gcc sbcl --script quickstart.lisp}@*
2748 The @code{CC=gcc} bit is needed for the @code{sb-grovel} contrib module
2751 @code{lisp -noinit -nositeinit -load quickstart.lisp}
2753 @code{ccl --no-init --load quickstart.lisp}
2755 ECL doesn't work like the other Lisp compilers. In particular, creating
2756 an executable does not involve dumping a Lisp image, but compiling the
2757 source into separate object files and then linking them. The consequence
2758 is that there is no simple @cmdline{} recipe to show here. Instead, you
2759 might want to look at the file @file{demos/dump.lisp} in the
2760 distribution for an example.
2762 Because the dumping scheme is different with ECL, it is also less
2763 straightforward to write portable code for standalone applications. The
2764 demo programs in the distribution both contain comments that are worth
2765 reading at the top of them.
2768 One specific difference between ECL and the other Lisp compilers is that
2769 it doesn't require you to specify a particular function as the entry
2770 point for your executable, but instead relies on having code to execute
2771 directly at the toplevel of some file. @clon{}'s @code{dump} macro helps
2772 you with this: it normally expands to a compiler-specific function which
2773 saves the current Lisp image, but for ECL, it simply expands to the
2774 ``main'' function call, hence consituting the entry point to the code
2777 @code{CC=gcc clisp -norc -i quickstart.lisp}@*
2778 The @code{CC=gcc} bit lets you choose your preferred C compiler for
2779 @code{cffi}. Please note that executables dumped (the @clon{} way) by
2780 CLISP still understand lisp-specific @cmdline{} options when they are
2781 prefixed with @code{--clisp-}, so you should obviously avoid defining
2782 options by those names.
2784 ABCL is a totally different beast because it's a Java-based @cl{}
2785 implementation. Most notably, you don't create standalone executables in
2786 Java, so the normal way of running ABCL is by telling it to load some
2787 lisp code. If you want to run the quickstart program in the usual way,
2788 you will typically type this:
2790 abcl --noinform --noinit --nosystem --load quickstart.lisp
2792 Note that for this to work, the @code{dump} macro expands to the
2793 ``main'' function call for ABCL, just as for ECL.
2795 There's more to it than that though. It is possible to get closer to
2796 standalone executables with ABCL by 1/ providing your whole application
2797 in a @code{jar} file directly, and 2/ overriding ABCL's entry point by
2798 providing your own interpreter which runs your main function
2799 automatically. I have described this process in more details in the
2800 following blog entry:
2801 @uref{http://www.didierverna.com/sciblog/index.php?post/2011/01/22/Towards-ABCL-Standalone-Executables}.
2804 @clon{} helps you to do this to some extend. If the @code{:dump}
2805 configuration option is set (@pxref{Configuration}), then the
2806 @code{dump} macro doesn't expand to a call to the ``main'' function, but
2807 instead dumps a Java file containing an alternate ABCL interpreter that
2808 you can compile and add to the original ABCL @code{jar} file, along with
2809 @file{quickstart.lisp}. If you want more details on this, you will need
2810 to look at the @file{Makefile} in the @code{demo} directory and also at
2811 the file @file{Makefile.inc} at the toplevel.
2815 @c -----------------------
2816 @c Not Dumping Executables
2817 @c -----------------------
2818 @node Not Dumping Executables, , Dumping Executables, Technical Notes
2819 @section Not Dumping Executables
2820 Although @cmdline{} processing really makes sense for standalone
2821 executables, you may want to preserve interactivity with your
2822 application during the development phase, for instance for testing or
2825 It is possible to use @clon{} interactively, that is, within a regular
2826 Lisp REPL, without dumping anything. First of all, we have already seen
2827 that it is possible to use a virtual @cmdline{} (@pxref{Using Different
2828 Command-Lines}). You can also use @clon{} interactively with the actual
2829 Lisp invocation's @cmdline{}, although a word of advice is in order
2834 As you might expect, the problem in that situation lies in the way the
2835 different Lisp implementations treat their own @cmdline{}. Guess what,
2836 it's a mess. When you dump an executable the @clon{} way, the
2837 @code{cmdline} function will always contain user options only (the
2838 @code{dump} macro instructs the compilers to @emph{not} process the
2839 @cmdline{} at all). When you use @clon{} interactively and mix
2840 compiler-specific options with application ones when invoking your Lisp
2841 environment, the situation is as follows:
2845 SBCL processes its own options and leaves the others unprocessed on the
2846 @cmdline{}. This means that as long as there is no overlap between
2847 SBCL's options and yours, you can just put them all together on the
2848 @cmdline{}. In case of overlap however, you need to separate SBCL's
2849 options from yours with a call to @code{--end-toplevel-options} (that's
2850 an SBCL specific option separator).
2852 @cindex Command-Line, remainder
2853 @cindex Remainder, of command-line
2854 CMUCL processes its own options, issues a warning about the options it
2855 doesn't know about, but in any case, it eats the whole @cmdline{}.
2856 Consequently, if you want to provide options to your application, you
2857 need to put them after a @code{--} separator. Note that you can still
2858 use a second such separator to provide @clon{} with both some options
2859 and a remainder (@pxenduserref{Option Separator}).
2863 CCL, ECL and CLISP all process their own options but will abort on
2864 unknown ones. Consequently, if you want to provide options to your
2865 application, you need to put them after a @code{--} separator. Note that
2866 you can still use a second such separator to provide @clon{} with both
2867 some options and a remainder (@pxenduserref{Option Separator}).
2869 Finally, ABCL processes its own options and leaves the others
2870 unprocessed on the @cmdline{}. This means that as long as there is no
2871 overlap between ABCL's options and yours, you can just put them all
2872 together on the @cmdline{}. In case of overlap however, you need to
2873 separate ABCL's options from yours with a @code{--} separator. Note that
2874 you can still use a second such separator to provide @clon{} with both
2875 some options and a remainder (@pxenduserref{Option Separator}).
2880 @c ====================================================================
2881 @c API Quick Reference
2882 @c ====================================================================
2883 @node API Quick Reference, Indexes, Technical Notes, Top
2884 @appendix API Quick Reference
2887 * Utilities:: Miscellaneous stuff
2888 * Initialization Phase API:: Synopsis, items and context creation
2889 * Runtime Phase API:: Option retrieval and help formatting
2890 * Extension API:: New option types
2891 * Versioning API:: Release identification
2898 @node Utilities, Initialization Phase API, API Quick Reference, API Quick Reference
2901 @defmac dump NAME FUNCTION
2902 See @ref{Quick Start}.
2905 @defun exit &optional (STATUS 0)
2906 See @ref{Quick Start}.
2909 @cindex Command-Line
2911 See @ref{Option Retrieval}.
2914 @cindex Package, nicknames
2915 @defun nickname-package &optional NICKNAME
2916 See @ref{Quick Start}.
2920 @c ------------------------
2921 @c Initialization Phase API
2922 @c ------------------------
2923 @node Initialization Phase API, Runtime Phase API, Utilities, API Quick Reference
2924 @section Initialization Phase API
2926 @defun make-text &key CONTENTS HIDDEN
2927 @cfsubindex{make-text}
2928 @cfiaindex{make-text,:contents}
2929 @cfiaindex{make-text,:hidden}
2930 @defunx make-@var{OPTION} :INITARG INITVAL@dots{}
2931 @cfsubindex{make-@var{OPTION}}
2933 @cfindex make-stropt
2934 @cfindex make-lispobj
2937 @cfindex make-switch
2938 @cfindex make-xswitch
2939 @defunx make-group &key HEADER HIDDEN ITEM
2940 @cfsubindex{make-group}
2941 @cfiaindex{make-group,:header}
2942 @cfiaindex{make-group,:hidden}
2943 @cfiaindex{make-group,:item}
2944 @defunx make-synopsis &key POSTFIX ITEM (MAKE-DEFAULT t)
2945 @cfsubindex{make-synopsis}
2946 @cfiaindex{make-synopsis,:postfix}
2947 @cfiaindex{make-synopsis,:item}
2948 @cfiaindex{make-synopsis,:make-default}
2949 See @ref{Constructors} and @ref{Using Different Synopsis}.
2952 @defmac defgroup (&key HEADER HIDDEN) &body FORMS
2953 @foindex{defgroup,:header}
2954 @foindex{defgroup,:hidden}
2955 @xref{Group Definition}.
2958 @defmac defsynopsis (&key POSTFIX MAKE-DEFAULT) &body FORMS
2959 @foindex{defsynopsis,:postfix}
2960 @foindex{defsynopsis,:make-default}
2961 @fiindex{defsynopsis,text}
2962 @fiindex{defsynopsis,options}
2963 @fiindex{defsynopsis,group}
2964 See @ref{Synopsis Definition} and @ref{Using Different Synopsis}.
2967 @defopt *default-synopsis*
2968 @xref{Using Different Synopsis}.
2971 @defun make-context &key (SYNOPSIS *default-synopsis*) CMDLINE @
2973 @cfsubindex{make-context}
2974 @cfiaindex{make-context,:synopsis}
2975 @cfiaindex{make-context,:cmdline}
2976 @cfiaindex{make-context,:make-current}
2977 @xref{Context Creation}, @ref{Using Different Synopsis} and @ref{Using
2978 Different Command-Lines}.
2983 @c -----------------
2984 @c Runtime Phase API
2985 @c -----------------
2986 @node Runtime Phase API, Extension API, Initialization Phase API, API Quick Reference
2987 @section Runtime Phase API
2989 @defopt *current-context*
2990 @xref{Using Multiple Contexts}.
2993 @defun with-context CONTEXT &body BODY
2994 @xref{Using Multiple Contexts}.
2997 @defun progname &key (CONTEXT *current-context*)
2998 @fkindex{progname,:context}
2999 See @ref{Contextual Information} and @ref{Using Multiple Contexts}.
3002 @defun remainder &key (CONTEXT *current-context*)
3003 @fkindex{remainder,:context}
3004 See @ref{Contextual Information} and @ref{Using Multiple Contexts}.
3007 @defun cmdline-options-p &key (CONTEXT *current-context*)
3008 @fkindex{cmdline-options-p,:context}
3009 See @ref{Command-Line Polling} and @ref{Using Multiple Contexts}.
3012 @defun cmdline-p &key (CONTEXT *current-context*)
3013 @fkindex{cmdline-p,:context}
3014 See @ref{Command-Line Polling} and @ref{Using Multiple Contexts}.
3017 @defun getopt &key (CONTEXT *current-context*) SHORT-NAME LONG-NAME @
3019 @fkindex{getopt,:context}
3020 @fkindex{getopt,:short-name}
3021 @fkindex{getopt,:long-name}
3022 @fkindex{getopt,:option}
3023 @vindex *current-context*
3024 See @ref{Explicit Retrieval} and @ref{Using Multiple Contexts}.
3027 @defun getopt-cmdline &key (CONTEXT *current-context*)
3028 @fkindex{getopt-cmdline,:context}
3029 @vindex *current-context*
3030 See @ref{Sequential Retrieval} and @ref{Using Multiple Contexts}.
3033 @defmac multiple-value-getopt-cmdline (OPTION NAME VALUE SOURCE &key CONTEXT) @
3035 @defmacx do-cmdline-options (OPTION NAME VALUE SOURCE &key CONTEXT) @
3037 @foindex{multiple-value-getopt-cmdline,:context}
3038 @foindex{do-cmdline-options,:context}
3039 See @ref{Sequential Retrieval} and @ref{Using Multiple Contexts}.
3042 @deffn Reader short-name OPTION
3043 @rfsubindex{short-name}
3044 @deffnx Reader long-name OPTION
3045 @rfsubindex long-name
3046 @xref{Sequential Retrieval}.
3049 @defun help &key (CONTEXT *current-context*) @
3050 (ITEM (synopsis context)) @
3051 (OUTPUT-STREAM *standard-output*) @
3052 (SEARCH-PATH (search-path context)) @
3053 (THEME (theme context)) @
3054 (LINE-WIDTH (line-width context)) @
3055 (HIGHLIGHT (highlight context)))
3056 @fkindex{help,:context}
3057 @fkindex{help,:item}
3058 @fkindex{help,:output-stream}
3059 @fkindex{help,:theme}
3060 @fkindex{help,:search-path}
3061 @fkindex{help,:line-width}
3062 @fkindex{help,:highlight}
3063 @vindex *current-context*
3064 @vindex *standard-output*
3065 @xref{Help}, @ref{Using Multiple Contexts} and @ref{Programmatic Help
3073 @node Extension API, Versioning API, Runtime Phase API, API Quick Reference
3074 @section Extension API
3076 @defmac defoption CLASS SUPERCLASSES SLOTS &rest OPTIONS
3077 @pxref{New Option Classes}
3080 @deffn {Generic Function} check OPTION VALUE
3082 @xref{Value Check Protocol}.
3085 @deftp {Error Condition} option-error OPTION
3086 @ecsubindex{option-error}
3087 @ecsindex{option-error,option}
3088 @deftpx {Error Condition} invalid-value VALUE COMMENT
3089 @ecsubindex{invalid-value}
3090 @ecsindex{invalid-value,value}
3091 @ecsindex{invalid-value,comment}
3092 @xref{Value Check Protocol}.
3095 @deffn {Generic Function} convert OPTION ARGUMENT
3096 @gfsubindex{convert}
3097 @xref{Argument Conversion Protocol}.
3100 @deftp {Error Condition} invalid-argument ARGUMENT COMMENT
3101 @ecsubindex{invalid-argument}
3102 @ecsindex{invalid-argument,argument}
3103 @ecsindex{invalid-argument,comment}
3104 @xref{Argument Conversion Protocol}.
3107 @deffn {Generic Function} stringify OPTION VALUE
3108 @gfsubindex{stringify}
3109 @xref{Value Stringification Protocol}.
3116 @node Versioning API, , Extension API, API Quick Reference
3117 @section Versioning API
3119 @defun version &optional (TYPE :number)
3120 @xref{Version Numbering}.
3123 @defvr Constant +release-major-level+
3124 @defvrx Constant +release-minor-level+
3125 @defvrx Constant +release-status+
3126 @defvrx Constant +release-status-level+
3127 @defvrx Constant +release-name+
3128 @xref{Version Numbering}.
3133 @c ====================================================================
3135 @c ====================================================================
3136 @node Indexes, Acknowledgments, API Quick Reference, Top
3140 * Concept Index:: Well, the concept index
3141 * Function Index:: Well, the function index
3142 * Variable Index:: Well, the variable index
3143 * Data Type Index:: Well, the data type index
3150 @node Concept Index, Function Index, Indexes, Indexes
3159 @node Function Index, Variable Index, Concept Index, Indexes
3168 @node Variable Index, Data Type Index, Function Index, Indexes
3177 @node Data Type Index, , Variable Index, Indexes
3183 @c ====================================================================
3185 @c ====================================================================
3186 @node Acknowledgments, , Indexes, Top
3187 @appendix Acknowledgments
3188 The following people have contributed bug reports or fixes, suggestions,
3189 compiler support or any other kind of help. You have my gratitude!
3191 @multitable @columnfractions .99
3195 François-René Rideau@*
3202 @c LocalWords: Clon clon cmdline Clonification tty emph CmdLine clonified SGR
3203 @c LocalWords: clonfiscated clonistified clonificated clonificationated samp
3204 @c LocalWords: cindex subsubsection pxref Didier Nuker postfix Runtime cth
3205 @c LocalWords: cartouche toplevel prepended IEC
3207 @c user.texi ends here