3 @c user.texi --- User manual
5 @c Copyright (C) 2010, 2011 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
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\}
188 @macro foindex{func,opt}
189 @findex \func\@r{, options, }\opt\
193 @macro fiindex{func,item}
194 @findex \func\@r{, items, }\item\
198 @macro fkindex{func,key}
199 @findex \func\@r{, keys, }\key\
203 @macro fiaindex{func,arg}
204 @findex \func\@r{, initargs, }\arg\
207 @c Generic functions sub-index
208 @macro gfsubindex{func}
209 @findex @r{Generic Functions, }\func\
218 @c Generic function methods
219 @macro gfmindex{func,method}
220 @findex \func\@r{, methods, }\method\
221 @findex @r{Generic Functions, }\func\@r{, methods, }\method\
224 @c #### FIXME: I need this because when using @defun, the function is
225 @c referenced directly but not under the Constructors sub-index. This
226 @c sucks because what I would like is the ability to define my own
227 @c @defXXX macros, which apparently I can't. Besides, doing this
228 @c produces 2 separate index entries, instead of only one with two pagerefs.
229 @c This problem stands for @gfsubindex (see above), @rfsubindex (see
230 @c below) and @ecsubindex (see below) as well.
231 @c Constructor functions sub-index
232 @macro cfsubindex{func}
233 @findex @r{Constructors, }\func\
236 @c Constructor functions
242 @c Constructor function initargs
243 @macro cfiaindex{func,arg}
244 @fiaindex{\func\, \arg\}
245 @findex @r{Constructors, }\func\@r{, initargs, }\arg\
248 @c Reader functions subindex
249 @macro rfsubindex{func}
250 @findex @r{Readers, }\func\
263 @c Environment variables
266 @vindex @r{Environment, }\var\
269 @c Built-in environment variables
270 @macro bievindex{var}
281 @tpindex @r{Classes, }\cls\
285 @macro clssindex{cls,slot}
286 @tpindex \cls\@r{, slots, }\slot\
287 @tpindex @r{Classes, }\cls\@r{, slots, }\slot\
291 @macro clsiaindex{cls,arg}
292 @tpindex \cls\@r{, initargs, }\arg\
293 @tpindex @r{Classes, }\cls\@r{, initargs, }\arg\
299 @tpindex @r{Option Classes, }\cls\
302 @c Error conditions subindex
303 @macro ecsubindex{cond}
304 @tpindex @r{Error Conditions, }\cond\
313 @c Error condition slots
314 @macro ecsindex{cond,slot}
315 @tpindex \cond\@r{, slots, }\slot\
316 @tpindex @r{Error Conditions, }\cond\@r{, slots, }\slot\
320 @macro pkgindex{name}
322 @tpindex @r{Packages, }\name\
326 @macro sysindex{name}
328 @tpindex @r{Systems, }\name\
333 @c ====================================================================
334 @c Info Category and Directory
335 @c ====================================================================
336 @dircategory Common Lisp
338 * Clon User: (clon-user). The Clon User Manual.
343 @c ====================================================================
345 @c ====================================================================
348 Copyright @copyright{} @value{COPYRIGHT_DATE} Didier Verna
350 Permission is granted to make and distribute verbatim copies of this
351 manual provided the copyright notice and this permission notice are
352 preserved on all copies.
355 Permission is granted to process this file through TeX and print the
356 results, provided the printed document carries a copying permission
357 notice identical to this one except for the removal of this paragraph
358 (this paragraph not being relevant to the printed manual).
361 Permission is granted to copy and distribute modified versions of this
362 manual under the conditions for verbatim copying, provided also that the
363 section entitled ``Copying'' is included exactly as in the original.
365 Permission is granted to copy and distribute translations of this manual
366 into another language, under the above conditions for modified versions,
367 except that this permission notice may be translated as well.
373 @c ====================================================================
375 @c ====================================================================
377 @title The Clon User Manual
378 @subtitle The @CmdLine{} Options Nuker, Version @value{VERSION}
381 @author Didier Verna <@email{didier@@lrde.epita.fr}>
383 @vskip 0pt plus 1filll
386 @hfill Cover art by Alexis Angelidis.
391 @c ====================================================================
393 @c ====================================================================
398 @c ====================================================================
400 @c ====================================================================
402 @node Top, Copying, (dir), (dir)
403 @top The Clon User Manual
405 This is the @clon{} User Manual for @clon{} version @value{VERSION}:
406 it explains how to use @clon{} in your application.
409 * Copying:: The BSD license
410 * Introduction:: What Clon is all about
411 * Quick Start:: For the brave and the impatient
412 * Using Clon:: Clonificating your application
413 * Extending Clon:: Creating your own option types
414 * Advanced Usage:: Things rarely needed
415 * Conclusion:: That's all folks
416 * Portability:: The mine field
417 * API Quick Reference:: The Complete protocols
418 * Indexes:: Concept, Function and Variable
419 * Acknowledgments:: Hall of Pride
427 @c ====================================================================
429 @c ====================================================================
430 @node Copying, Introduction, Top, Top
434 Permission to use, copy, modify, and distribute this software for any
435 purpose with or without fee is hereby granted, provided that the above
436 copyright notice and this permission notice appear in all copies.
438 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
439 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
440 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
441 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
442 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
443 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
444 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
449 @c ====================================================================
451 @c ====================================================================
452 @node Introduction, Quick Start, Copying, Top
453 @chapter Introduction
455 @clon{} is a library for managing @cmdline{} options in standalone @cl{}
456 applications. It provides a unified option syntax with both short and
457 long names, automatic completion of partial names and automatic
458 retrieval/conversion of option arguments from the @cmdline{}, associated
459 environment variables, fallback or default values. @clon{} comes with a
460 set of extensible option types (switches, paths, strings @etc{}).
461 @clon{} also provides automatic generation and formatting of help
462 strings, with support for highlighting on @tty{}'s through ISO/IEC 6429
463 SGR. This formatting is customizable through @emph{themes}.
465 Depending on the target audience, @clon{} stands for either ``The
466 @CmdLine{} Options Nuker'' or ``The @cl{} Options Nuker''. @clon{} also
467 has a recursive acronym: ``@clon{} Likes Options Nuking'', and a reverse
468 one: ``Never Omit to Link with @clon{}''. Other possible expansions of
469 the acronym are still being investigated.
471 This manual is for the @clon{} @emph{user}, that is, the developer of a
472 @cl{} application who wants to use @clon{} for @cmdline{} option
473 management@footnote{An application using @clon{} for its @cmdline{}
474 option management is said to be @emph{clonified}. It is also possible to
475 say @emph{clonfiscated}. However, we advise against using
476 @emph{clonistified}. The term @emph{clonificated} is also considered bad
477 style, and the use of @emph{clonificationated} is strictly prohibited.}.
478 As opposed to the user of the @emph{library}, the user of an
479 @emph{application} powered by @clon{} is called an @emph{end-user}.
480 @clon{} provides both a user manual (this one) and an end-user manual
481 (@pxenduserref{Top}). Everybody should read the end-user manual first.
483 @ref{Quick Start} provides a very short example in order to give an
484 overview of what's coming next. @ref{Using Clon} explains in detail how
485 to clonify your application, and @ref{Extending Clon} describe how to
486 extend @clon{} with your own option types.
490 @c ====================================================================
492 @c ====================================================================
493 @node Quick Start, Using Clon, Introduction, Top
495 In this chapter, we assume that you have properly installed @clon{} (see
496 the @file{INSTALL} file in the distribution), and we build a very short
497 program to get you started (let's call it @file{quickstart.lisp}).
500 * Full Source:: The complete source code
501 * Explanation:: Step-by-step code walking
508 @node Full Source, Explanation, Quick Start, Quick Start
510 For cut'n paste convenience, the complete source code is given below.
511 For a slightly longer example, have a look at the demonstration program
512 called @file{simple} in the distribution.
516 (in-package :cl-user)
519 (asdf:operate 'asdf:load-op :com.dvlsoft.clon)
520 (use-package :com.dvlsoft.clon)
522 (defsynopsis (:postfix "FILES...")
523 (text :contents "A very short program.")
524 (group (:header "Immediate exit options:")
525 (flag :short-name "h" :long-name "help"
526 :description "Print this help and exit.")
527 (flag :short-name "v" :long-name "version"
528 :description "Print version number and exit.")))
531 "Entry point for our standalone application."
533 (when (getopt :short-name "h")
536 (do-cmdline-options (option name value source)
537 (print (list option name value source)))
541 (dump "quickstart" main)
549 @node Explanation, , Full Source, Quick Start
551 Let's examine this program step-by-step now.
553 @pkgindex{com.dvlsoft.clon}
554 @sysindex{com.dvlsoft.clon}
555 First, we put ourselves in the @cl{} user package, and load @clon{} from
556 its ASDF system @samp{com.dvlsoft.clon}. Next, we use the @clon{}
557 package, also named @samp{com.dvlsoft.clon}.
561 (in-package :cl-user)
564 (asdf:operate 'asdf:load-op :com.dvlsoft.clon)
565 (use-package :com.dvlsoft.clon)
569 In fact, using the @clon{} package directly is done here for simplicity,
570 but is not recommended. In case you find the package name too long to
571 prefix every symbol with, @clon{} provides a utility function that
572 allows you to add (and use) a shorter nickname instead (the
573 demonstration programs in the distribution show how to use it):
575 @cindex Package, nicknames
576 @defun nickname-package &optional NICKNAME
577 Add NICKNAME (:CLON by default) to the :COM.DVLSOFT.CLON package.
583 @cindex Text, in synopsis
584 @cindex Options, in synopsis
585 @cindex Groups, in synopsis
587 The next thing you want to do is to create a set of options, groups or
588 texts that your application will recognize and/or display in its help
589 string. The structure of your @cmdline{} is known to @clon{} as the
590 @dfn{synopsis}. In order to create it, use the macro @code{defsynopsis}.
592 @foindex{defsynopsis,:postfix}
593 @fiindex{defsynopsis,text}
594 @fiindex{defsynopsis,options}
595 @fiindex{defsynopsis,group}
598 (defsynopsis (:postfix "FILES...")
599 (text :contents "A very short program.")
600 (group (:header "Immediate exit options:")
601 (flag :short-name "h" :long-name "help"
602 :description "Print this help and exit.")
603 (flag :short-name "v" :long-name "version"
604 :description "Print version number and exit.")))
608 Note that the synopsis has a double role: it not only serves to define
609 the options recognized by your application, but also the order in which
610 every element appears in the help string. In that particular example, we
611 define a line of text and a group with a header and two flags.
614 @cfindex{make-context}
615 Now, we are going to define a function @code{main} for our standalone
616 application. The first thing that we need to do is create a
617 @dfn{context}. A context is an object that @clon{} uses to store various
618 things, including some state related to the parsing of the @cmdline{}.
619 You create a context with the function @code{make-context}.
624 "Entry point for our standalone application."
629 @cindex Options Retrieval, explicit
630 @cindex Retrieval, of options, explicit
632 @cindex Help String, display
634 At that point, @clon{} is ready to retrieve the options you want from
635 the @cmdline{}. Let's first see if the user has called the option
636 @option{-h}, and give him the help string. Option retrieval is done with
637 the function @code{getopt}, and automatic help string output with the
638 function @code{help}. Note that what we do here is @emph{not} process
639 the @cmdline{} in sequence, but look directly for a specific option by
640 name (this retrieval method is said to be @dfn{explicit}).
642 @fkindex{getopt,:short-name}
645 (when (getopt :short-name "h")
652 The @code{exit} function is a wrapper around an
653 implementation-dependent way to exit (shall I say quit?) the @cl{}
654 environment, hence the program. It takes an optional argument that
655 stands for the exit status.
657 @cindex Options Retrieval, sequential
658 @cindex Retrieval, of options, sequential
659 @findex do-cmdline-options
660 And now, we are going to retrieve the other options and simply print
661 them. This time however, we process the @cmdline{} sequentially (so this
662 retrieval method is said to be @dfn{sequential}). This is done with the
663 @code{do-cmdline-options} macro. We also close the @code{main} function.
667 (do-cmdline-options (option name value source)
668 (print (list option name value source)))
674 Finally, time to save the Lisp image.
679 (dump "quickstart" main)
683 The first argument to @code{dump} is the name of the executable to
684 produce, and the second argument is the name of the function to call
685 automatically at startup.
687 In order to get a standalone executable from this program, all you need
688 to do now is to type @samp{CC=gcc sbcl --script quickstart.lisp}. Note
689 that the actual way of dumping executables is compiler-dependent. For
690 more information on the proper way to do it and on the compilers
691 currently supported, see @ref{Portability}.
695 @c ====================================================================
697 @c ====================================================================
698 @node Using Clon, Extending Clon, Quick Start, Top
701 Using @clon{} in your application is a two stages process. In phase 1,
702 you create a @dfn{synopsis}, which is a description of your
703 application's @cmdline{} and a @dfn{context}, which describes this
704 specific execution of the program. In phase 2, you retrieve the option
705 values and possibly display help strings. Phase 1 is called the
706 @dfn{initialization phase}, while phase 2 is called the @dfn{runtime
710 * Synopsis Definition:: Describing your command-line
711 * Context Creation:: Instantiating your command-line
712 * Integrity Checks:: Verifying the Clon semantics
713 * Option Retrieval:: Getting the options values
714 * Help:: Generating the help string
718 @c -------------------
719 @c Synopsis Definition
720 @c -------------------
721 @node Synopsis Definition, Context Creation, Using Clon, Using Clon
722 @section Synopsis Definition
724 @cindex Initialization Phase
725 @cindex Phase, initialization
728 Step one of the @clon{} initialization phase consists in defining a
729 @dfn{synopsis}. A synopsis is essentially a description of your
730 application's @cmdline{}: it describes what are the available options,
731 whether your application has a postfix @etc{} The synopsis, however,
732 plays a second role: it also describes the contents of your
733 application's help string. When you create a synopsis, you describe the
734 @cmdline{} and the help string at the same time.
737 * Synopsis Items:: Defsynopsis and its contents
738 * Built-In Option Types:: The exhaustive list
739 * Advanced Synopsis Creation:: The non-declarative way
742 @node Synopsis Items, Built-In Option Types, Synopsis Definition, Synopsis Definition
743 @subsection Synopsis Items
744 Look again at the synopsis definition provided in @ref{Quick Start}.
748 (defsynopsis (:postfix "FILES...")
749 (text :contents "A very short program.")
750 (group (:header "Immediate exit options:")
751 (flag :short-name "h" :long-name "help"
752 :description "Print this help and exit.")
753 (flag :short-name "v" :long-name "version"
754 :description "Print version number and exit.")))
758 You define a synopsis with the @code{defsynopsis} macro.
760 @defmac defsynopsis ([OPTIONS@dots{}]) ITEMS@dots{}
761 Define a new synopsis and return it. @var{OPTIONS} are key/value pairs.
762 @var{ITEMS} are text, group or option descriptions.
764 The following @var{OPTIONS} are currently available.
768 @foindex{defsynopsis,:postfix}@c
769 @cindex Command-Line, remainder
770 @cindex Remainder, of command-line
771 A string which will appear at the end of the synopsis line in the help
772 string. When you provide a postfix, you also implicitely tell @clon{}
773 that your application accepts non-option arguments at the end of the
774 @cmdline{} (this is called the @dfn{remainder} of the @cmdline{}). See
775 @enduserref{Option Separator} for more information on the behavior of
776 @clon{} with respect to postfixes. Also, see @ref{Command-Line
777 Remainder} on how to access the @cmdline{} remainder.
781 We now examine the syntax for each possible @var{ITEM}.
783 * Text:: Adding arbitrary text
784 * Options:: Adding options
785 * Groups:: Adding groups
788 @node Text, Options, Synopsis Items, Synopsis Items
791 @cindex Text, in synopsis
792 @fiindex{defsynopsis,text}
793 In order to add arbitrary text to your help string, use the following
797 @t{(text} [@var{OPTIONS@dots{}}]@t{)}
799 @var{OPTIONS} are key/value pairs. The following @var{OPTIONS} are
803 @cindex Text, contents
804 The actual text string. Try to make proper sentences when adding
805 arbitrary text. You can use explicit newline characters in your text if
806 you really want to go next line, but in general, you should not worry
807 about the formatting because the themes are here to do so. In
808 particular, don't finish your text with a newline. This would break
809 potential theme specifications.
814 When non-@code{nil}, the text won't appear in the help string. Hidden
815 texts can still be displayed individually though (@pxref{Help}).
818 @node Options, Groups, Text, Synopsis Items
819 @subsubsection Options
821 @cindex Options, in synopsis
822 @fiindex{defsynopsis,options}
823 In order to add an option to your help string, you must provide a list
824 beginning with the option type and followed by key/value pairs
825 describing the option's properties. For instance, to add a flag with a
826 short name and a description, you could do this:
829 (flag :short-name "h" :description "Print this help and exit.")
832 Option properties vary depending on the option type. The exact list of
833 available option types, and the corresponding properties are described
834 in @ref{Built-In Option Types}.
836 @node Groups, , Options, Synopsis Items
837 @subsubsection Groups
839 @cindex Groups, in synopsis
840 @fiindex{defsynopsis,group}
841 In order to add a group to your help string, use the following form:
844 @t{(group} ([@var{OPTIONS@dots{}}]) @var{ITEMS@dots{}}@t{)}
846 @cindex Text, in groups
847 @cindex Options, in groups
848 @cindex Groups, in groups
849 @var{OPTIONS} are key/value pairs. @var{ITEMS} simply are arbitrary
850 text, option or sub-group descriptions as we've just seen.
852 The following @var{OPTIONS} are currently available.
856 @cindex Header, in group
857 @foindex{defgroup,:header}@c
858 A string which will be displayed above the group's contents in the help
859 string. The same formatting recommendations as for arbitrary text apply
862 @cindex Hidden Groups
863 @cindex Groups, hidden
864 @foindex{defgroup,:hidden}@c
866 @cindex Built-In Groups
867 @cindex Groups, built-in
869 When non-@code{nil}, the group won't appear in the help string. Hidden
870 groups can still be displayed individually though (@pxref{Help}). For
871 instance, the @clon{} built-in group is hidden in the regular help
872 string, but the @bioption{help} option still displays it individually.
875 @node Built-In Option Types, Advanced Synopsis Creation, Synopsis Items, Synopsis Definition
876 @subsection Built-In Option Types
877 @cindex Built-In Option Types
878 @cindex Options, built-in types
879 @cindex Option Types, built-in
880 In this section, we will review all the built-in option types that
881 @clon{} provides, along with their corresponding properties. You can use
882 them directly in your synopsis description. For adding personal option
883 types to @clon{}, see @ref{New Option Types}.
886 * Common Properties:: For all options
887 * Flags:: Built-in options without arguments
888 * Common Valued Option Properties:: For all valued options
889 * Built-In Valued Options:: Built-in options with arguments
892 @node Common Properties, Flags, Built-In Option Types, Built-In Option Types
893 @subsubsection Common Properties
894 @cindex Options, common properties
895 @cindex Common Option Properties
897 All option types in @clon{}, including those you define yourself
898 (@pxref{New Option Types}), have a set of basic, common properties. Here
903 @copindex{:short-name}
904 The option's short name. A string or @code{nil}.
906 @copindex{:long-name}
907 The option's long name. A string or @code{nil}.
909 @copindex{:description}
910 The option's descriptive text. A string or @code{nil}. The same
911 formatting recommendations as for arbitrary text apply (@pxref{Text}).
914 The option's associated environment variable. A string or @code{nil}.
917 @cindex Hidden Options
918 @cindex Options, hidden
920 When non-@code{nil}, the option won't appear in the help string. Hidden
921 options can still be displayed individually though (@pxref{Help}).
924 Note that an option is required to have at least one name (either short
925 or long). Non-@code{nil} but empty names are also prohibited, and of
926 course, a short name cannot begin with a dash (otherwise, it would be
927 mistaken for a long name, but did I really need to mention this?).
929 @node Flags, Common Valued Option Properties, Common Properties, Built-In Option Types
932 In @clon{}, options that don't take any argument are of type
933 @code{flag}. These options don't provide additional properties on top of
934 the common set described in @ref{Common Properties}. All properties
935 default to @code{nil}.
937 @node Common Valued Option Properties, Built-In Valued Options, Flags, Built-In Option Types
938 @subsubsection Common Valued Option Properties
939 @cindex Valued Options
940 @cindex Options, valued
941 @clsindex{valued-option}
942 All non-flag options in @clon{} are said to be @dfn{valued}. All valued
943 options, including those you define yourself (@pxref{New Option Types}),
944 share a set of additional properties. Here is a list of them.
946 @cindex Valued Options, common properties
947 @cindex Common Valued Option Properties
948 @cindex Options, valued, common properties
951 @cvopindex{:argument-name}
952 The name of the option's argument, as it appears in the help string. It
953 defaults to @code{"ARG"}, so that for instance, a @samp{name} option
954 would appear like this: @samp{--name=ARG}.
956 @cvopindex{:argument-type}
957 The status of the argument. Possible values are @code{:required} (the
958 default) and @code{:mandatory} which are synonyms, or @code{:optional}.
959 @item :fallback-value
960 @cvopindex{:fallback-value}
961 @cindex Values, source, fallback
963 @cvopindex{:default-value}
964 @cindex Values, source, default
965 The option's fallback and default values. Remember that a fallback value
966 only makes sense when the argument is optional. Besides, also when the
967 argument is optional, you need to provide at least a fallback or a
968 default value (or both of course; see @enduserref{Value Sources}).
971 @node Built-In Valued Options, , Common Valued Option Properties, Built-In Option Types
972 @subsubsection Built-In Valued Options
973 @cindex Option Types, valued
974 @cindex Built-In Option Types, valued
975 @cindex Options, built-in types, valued
976 @cindex Option Types, built-in, valued
977 @clon{} currently defines 6 built-in valued option types. These option
978 types may change the default value for some common properties, and / or
979 provide additional properties of their own. All of this is described
984 @voindex{Strings,stropt}@c
985 @cvopindex{:argument-name}@c
986 This option type is for options taking strings as their argument. String
987 options don't provide any additional properties, but their default
988 argument name is changed from @code{"ARG"} to @code{"STR"}.
990 @voindex{Lisp Objects,lispobj}@c
991 @cvopindex{:argument-name}@c
992 @vopindex{Lisp Objects,lispobj,:typespec}@c
993 @bioindex{line-width}@c
994 This option type is for options taking any kind of Lisp object as their
995 argument. @code{lispobj} options change their default argument name from
996 @code{"ARG"} to @code{"OBJ"}. Also, they provide an additional property
997 called @code{:typespec} which must be a @cl{} type specifier that the
998 argument must satisfy. It defaults to @code{t}. Look at the
999 @bioption{line-width} built-in option for an example.
1001 @voindex{Enumerations,enum}@c
1002 @cvopindex{:argument-name}@c
1003 @vopindex{Enumerations,enum,:enum}@c
1004 @bioindex{version}@c
1005 This option type is for options taking values from an enumerated set of
1006 keywords. @code{enum} options change their default argument name from
1007 @code{"ARG"} to @code{"TYPE"}. Also, they provide an additional property
1008 called @code{:enum} to store the list of @cl{} keywords enumerating the
1009 possible values. The end-user does not use a colon when providing an
1010 argument to an @code{enum} option. Only the keyword's name. The end-user
1011 also has the ability to abbreviate the possible values. An empty
1012 argument is considered as an abbreviation for the first element in the
1013 set. Look at the @bioption{version} built-in option for an example.
1015 @bioindex{search-path}@c
1017 @voindex{Paths,path}@c
1018 @cvopindex{:argument-name}@c
1019 @vopindex{Paths,path,:type}@c
1020 This option type is for options taking a colon-separated list of
1021 pathnames as argument. @code{path} options change their default argument
1022 name from @code{"ARG"} to @code{"PATH"}. Also, they provide an
1023 additional property called @code{:type} which specifies the kind of path
1024 which is expected. Possible values are: @code{:file}, @code{:directory},
1025 @code{:file-list}, @code{:directory-list} or @code{nil} (meaning that
1026 anything is allowed). Null paths are allowed, and may be provided by an
1027 empty argument. Look at the @bioption{search-path} and
1028 @bioption{theme} built-in options for examples.
1030 @voindex{Switches,switch}@c
1031 @cvopindex{:argument-name}@c
1032 @cvopindex{:argument-type}@c
1033 @vopindex{Switches,switch,:argument-style}@c
1034 This option type is for Boolean options. @code{switch} options change
1035 their default argument type from required to optional and provide a
1036 fallback value of @code{t} automatically for optional arguments.
1037 @code{switch} options provide a new property called
1038 @code{:argument-style}. Possible values are @code{:yes/no} (the
1039 default), @code{:on/off}, @code{:true/false}, @code{:yup/nope},
1040 @code{:yeah/nah}. This property affects the way the argument name and
1041 true or false values are advertized in help strings. However, all
1042 possible arguments forms (@pxenduserref{Switches}) are always available
1045 @voindex{Extended Switches,xswitch}@c
1046 @cvopindex{:argument-name}@c
1047 @cvopindex{:argument-type}@c
1048 @vopindex{Extended Switches,xswitch,:argument-style}@c
1049 @vopindex{Extended Switches,xswitch,:enum}@c
1050 @bioindex{highlight}@c
1051 This option type stands for @dfn{extended} switch. Extended switches
1052 result from the mating of a male switch and a female enumeration, or the
1053 other way around (elementary decency prevents me from describing this
1054 mating process in detail): their possible values are either Boolean or
1055 from an @code{:enum} property as in the case of @code{enum} options. As
1056 simple switches, @code{xswitch} options change their default argument
1057 type from required to optional and provide a fallback value of @code{t}
1058 automatically for optional arguments. They also provide the
1059 @code{:argument-style} property. Contrary to switches, however, this
1060 property does not affect the argument name. It only affects the way true
1061 or false values are displayed in help strings. Look at the
1062 @bioption{highlight} built-in option for an example.
1065 @node Advanced Synopsis Creation, , Built-In Option Types, Synopsis Definition
1066 @subsection Advanced Synopsis Creation
1068 The fact that @code{defsynopsis} lets you define things in a
1069 @emph{declarative} way has not escaped you. Declarative is nice but
1070 sometimes it gets in the way, so it is time to see how things work under
1071 the hood. Every item in a synopsis is in fact implemented as an object
1072 (an instance of some class), so it turns out that @code{defsynopsis}
1073 simply is a convenience wrapper around the corresponding constructor
1074 functions for all such objects. Instead of using @code{defsynopsis}, you
1075 can then use those constructor functions explicitely.
1078 * Constructors:: The expansion of defsynopsis
1079 * Advantages:: Yes, but why?
1080 * Group Definition:: The declarative way
1083 @node Constructors, Advantages, Advanced Synopsis Creation, Advanced Synopsis Creation
1084 @subsubsection Constructors
1085 Let's have a look at the expansion of @code{defsynopsis} from the quick
1086 start example (@pxref{Quick Start}).
1088 The original code is like this:
1092 (defsynopsis (:postfix "FILES...")
1093 (text :contents "A very short program.")
1094 (group (:header "Immediate exit options:")
1095 (flag :short-name "h" :long-name "help"
1096 :description "Print this help and exit.")
1097 (flag :short-name "v" :long-name "version"
1098 :description "Print version number and exit.")))
1102 And once the macro is expanded, it will look like this:
1104 @cfindex make-synopsis
1108 @findex defsynopsis@r{, expansion}
1111 (make-synopsis :postfix "FILES..."
1112 :item (make-text :contents "A very short program.")
1113 :item (make-group :header "Immediate exit options:"
1114 :item (make-flag :short-name "h"
1116 :description "Print this help and exit.")
1117 :item (make-flag :short-name "v"
1118 :long-name "version"
1119 :description "Print version number and exit.")))
1123 As you can see, every synopsis element has a corresponding
1124 @code{make-@var{SOMETHING}} constructor, and the keywords used here and
1125 there in @code{defsyopsis} are in fact initargs to those constructors.
1126 We now examine those constructors in greater detail.
1128 @cindex Options, creation
1129 @defun make-text [@code{:hidden} BOOL] @code{:contents} STRING
1130 @cfsubindex{make-text}
1131 @cfiaindex{make-text,:contents}
1132 @cfiaindex{make-text,:hidden}
1133 Create an arbitrary text object, possibly hidden, whose contents is
1137 @c #### FIXME: I would like an environment without indexing here.
1138 @defun make-@var{OPTION} :INITARG INITVAL@dots{}
1139 @cfsubindex{make-@var{OPTION}}
1141 @cfindex make-stropt
1142 @cfindex make-lispobj
1145 @cfindex make-switch
1146 @cfindex make-xswitch
1147 Create a new @var{OPTION} object, @var{OPTION} being any built-in option
1148 type (@code{flag}, @code{stropt} @etc{}, see @ref{Built-In Valued
1149 Options}) or user-defined one (@pxref{New Option Types}). For a list of
1150 available initialization arguments (depending on the option type), see
1151 @ref{Built-In Option Types}.
1154 @defun make-group [@code{:header} STRING @code{:hidden} BOOL] @
1155 @code{:item} ITEM1 @code{:item} ITEM2@dots{}
1156 @cfsubindex{make-group}
1157 @cfiaindex{make-group,:header}
1158 @cfiaindex{make-group,:hidden}
1159 @cfiaindex{make-group,:item}
1161 Create a group object, possibly hidden, whose header is @var{STRING}.
1162 Every @var{ITEM} is an arbitrary text object, option object or group
1163 object. The order is important as it determines the display of the help
1167 @defun make-synopsis [@code{:postfix} STRING] @
1168 @code{:item} ITEM1 @code{:item} ITEM2@dots{}
1169 @cfsubindex{make-synopsis}
1170 @cfiaindex{make-synopsis,:postfix}
1171 @cfiaindex{make-synopsis,:item}
1173 Create a synopsis object whose postfix is @var{STRING}. Every @var{ITEM} is
1174 an arbitrary text object, option object or group object. The order is
1175 important as it determines the display of the help string.
1178 In fact, the @code{defsynopsis} macro allows you to freely mix
1179 declarative forms, constructor calls or whatever Lisp code you may want
1180 to use. The way this works is as follows: if a synopsis @var{ITEM}
1181 (@pxref{Synopsis Items}) is a list whose @code{car} is @code{text},
1182 @code{group}, or any option type (inluding those you define yourselves;
1183 see @ref{New Option Types}), then the @var{ITEM} is expanded as
1184 explained earlier. Otherwise, it is just left @emph{as-is}.
1186 To sum up, here's a example of things you can do in @code{defsynopsis}.
1190 (com.dvlsoft.clon:defsynopsis ()
1193 (setq *another-option* (com.dvlsoft.clon:make-switch #| ... |#)))
1198 @node Advantages, Group Definition, Constructors, Advanced Synopsis Creation
1199 @subsubsection Advantages
1201 So, why would you want to use constructors directly or mix declarative
1202 and imperative forms in @code{defsynopsis}? There are several reasons
1206 Some people prefer to declare (or should I say, create) their arbitrary
1207 texts, options and groups locally, in files, modules or ASDF components
1208 where they belong. In such a case, you need to keep references to the
1209 corresponding objects in order to compute the synopsis in the end.
1211 Since using constructors explicitely allows you to keep references to
1212 the created objects, these objects can be @emph{reused}. For instance,
1213 you can use the same text at different places, you can also use a single
1214 option several times, or even a single group several times so that its
1215 items appear in different places @etc{} Note that @clon{} knows its way
1216 around multiple occurrences of the same object: even if you use the same
1217 option object several times in a synopsis, @clon{} only maintains a
1218 single option definition.
1221 @node Group Definition, , Advantages, Advanced Synopsis Creation
1222 @subsubsection Group Definition
1223 There is one last point we need to address in order to complete this
1224 section. There might be times when you need to manipulate an explicit
1225 group object, but the object itself can still be created in a
1226 declarative (or mixed) way because you don't need to keep references on
1227 its items. For this, @clon{} provides a macro called @code{defgroup}.
1229 @defmac defgroup (OPTIONS@dots{}) ITEMS@dots{}
1230 @cindex Groups, in synopsis
1231 @fiindex{defsynopsis,group}
1232 @foindex{defgroup,:header}
1233 @foindex{defgroup,:hidden}
1234 Define a new group and return it. This macro behaves exactly like the
1235 @code{group} form in a call to @code{defsynopsis} (@pxref{Groups}). In
1236 fact, an intermediate step in the expansion of the @code{defsynopsis}
1237 macro is to transform @code{group} forms into @code{defgroup} macro
1238 calls. As for @code{defsynopsis}, @code{defgroup} allows you to mix
1239 declarative forms, constructor calls or any kind of Lisp code.
1247 @node Context Creation, Integrity Checks, Synopsis Definition, Using Clon
1248 @section Context Creation
1250 @cindex Initialization Phase
1251 @cindex Phase, initialization
1253 Step two of the @clon{} initialization phase consists in creating a
1254 @dfn{context}. A context is an object representing a particular instance
1255 of your program, for example (and most notably) with an actual
1256 @cmdline{} as the user typed it.
1259 * Making A Context:: The Constructor function
1260 * Contextual Information:: Interesting context slots
1263 @node Making A Context, Contextual Information, Context Creation, Context Creation
1264 @subsection Making A Context
1266 @cfindex{make-context}
1267 You create a context with the @code{make-context} function.
1270 @cfsubindex{make-context}
1271 Create a new context. That's it.
1274 @node Contextual Information, , Making A Context, Context Creation
1275 @subsection Contextual Information
1277 Once a context object is created, you have access to some interesting
1278 contextual information.
1281 * Program Name:: As it appear on the command-line
1282 * Command-Line Remainder:: The non-options part
1283 * Command-Line Polling:: Whether something is left
1286 @node Program Name, Command-Line Remainder, Contextual Information, Contextual Information
1287 @subsubsection Program Name
1288 The application's program name, as it appears on the @cmdline{}, may be
1289 accessed from @clon{}. You may find it easier to do this way, as @clon{}
1290 wraps around implementation-dependent access methods to @code{argv[0]}.
1293 In order to retrieve @code{argv[0]}, use the @code{progname} function
1294 like this: @code{(progname)}.
1296 @node Command-Line Remainder, Command-Line Polling, Program Name, Contextual Information
1297 @subsubsection Command-Line Remainder
1298 @cindex Remainder, of command-line
1299 @cindex Command-Line, remainder
1300 In the case your @cmdline{} has a remainder (that is, a non-options
1301 part; see @enduserref{Option Separator} and @ref{Synopsis Items}), you
1302 may need to access it in order to process it independently from @clon{}.
1303 Since @clon{} is responsible for parsing the @cmdline{}, it is also in
1304 charge of figuring out where the remainder of the @cmdline{} begins.
1307 The @cmdline{} remainder is known to @clon{} as soon as a context is
1308 created. You can retrieve it by using the @code{remainder} function like
1309 this: @code{(remainder)}. The remainder is provided as a list of strings.
1311 @node Command-Line Polling, , Command-Line Remainder, Contextual Information
1312 @subsubsection Command-Line Polling
1313 @cindex Polling, of command-line
1314 @cindex Command-Line, polling
1316 @clon{} provides two utility functions to inquire on the current status
1319 @findex cmdline-options-p
1321 The function @code{cmdline-options-p} returns true if there are still
1322 unprocessed options on the @cmdline{}. The function @code{cmdline-p}
1323 returns true if there's @emph{anything} left on the @cmdline{}, that is,
1324 either unprocessed options, or a remainder. A potential use of
1325 @code{cmdline-p} at a very early stage of your application could be to
1326 automatically display a help string if the @cmdline{} is effectively
1333 @node Integrity Checks, Option Retrieval, Context Creation, Using Clon
1334 @section Integrity Checks
1336 @cfindex{make-context}
1337 At this point, you know about the two necessary steps to initialize
1338 @clon{}: defining a synopsis and creating a context. If you paid
1339 attention to the quick start application (@pxref{Quick Start}), you may
1340 have noticed that @code{defsynopsis} was called as a top-level form
1341 whereas @code{make-context} was called from the function @code{main}. So
1344 First, I hope that you see why a context cannot be created as a toplevel
1345 form. If you do that, you will end-up creating a context relevant to the
1346 Lisp environment from which the application is created, not run.
1348 The synopsis, on the other hand, could be defined either as a toplevel
1349 form, as done in the quick start and the demo programs, or in the
1350 function @code{main}, just before making a context. There is a very good
1351 reason to prefer a toplevel form however: that reason is called
1352 ``integrity checks''.
1354 When you define a synopsis (or any synopsis item, for that matter),
1355 @clon{} performs a number of checks to make sure that you're making a
1356 sensible use of the library. In fact, the number of semantic mistakes
1357 that you can make is quite puzzling. You could for instance define
1358 several options with identical names, forget to provide a fallback or
1359 default value when it is required, provide invalid fallback or default
1360 values, and the list goes on and on. These are just a few examples but
1361 there are many more, and @clon{} checks all of those (I think).
1363 Since those mistakes relate to the definition of the application itself,
1364 they do not depend on a particular execution of it. Consequently, the
1365 sooner @clon{} catches them, the better. If you define your
1366 application's synopsis as a toplevel form, @clon{} will be able to
1367 perform its integrity checks when the application is created, not only
1368 when it is used. In other words, you won't be able to get a working
1369 application until your use of @clon{} is semantically correct.
1371 This is why it is strongly recommended to create synopsis from toplevel
1372 forms, and this also explains why @clon{} chooses @emph{not} to provide
1373 an @code{initialize} function that would wrap around @code{defsynopsis}
1374 and @code{make-context} together.
1381 @node Option Retrieval, Help, Integrity Checks, Using Clon
1382 @section Option Retrieval
1383 @cindex Runtime Phase
1384 @cindex Phase, runtime
1385 @cindex Retrieval, of options
1386 @cindex Options Retrieval
1388 During the runtime phase of @clon{}, your main activity will be to
1389 retrieve options and their values. @clon{} provides two techniques for
1390 retrieving options: you can request the value for a specific option
1391 directly, or you can process the @cmdline{} sequentially, which is the
1392 more traditional approach.
1394 @cindex Command-Line
1396 Both of these techniques can be freely combined together at any time,
1397 because @clon{} keeps track of the current status of the @cmdline{}. In
1398 fact, @clon{} never works on the original @cmdline{}, but uses a mutable
1399 @emph{copy} of it after parsing. If you want to access the real
1400 @cmdline{} of your application, you may use the @code{cmdline} function,
1401 which is a wrapper around an implementation-dependent way to access it.
1404 Finally, remember that the @cmdline{} is scanned from left to right
1405 during option retrieval (@pxenduserref{Option Retrieval}).
1408 * Explicit Retrieval:: Accessing options by name
1409 * Sequential Retrieval:: Accessing options in order
1412 @node Explicit Retrieval, Sequential Retrieval, Option Retrieval, Option Retrieval
1413 @subsection Explicit Retrieval
1414 @cindex Options Retrieval, explicit
1415 @cindex Retrieval, of options, explicit
1416 Since @clon{} lets you retrieve options on demand (at any time), it
1417 makes sense to be able to request the value of a specific option
1418 explicitely. For instance, you might want to try the @samp{--help}
1419 option first, without looking at the rest of the @cmdline{} because the
1420 application will in fact quit immediately after having displayed the
1423 @defun getopt :KEY VALUE@dots{}
1424 Retrieve the value of a specific option. The following @var{:KEY}s are
1425 currently available.
1430 @fkindex{getopt,:short-name}
1431 @fkindex{getopt,:long-name}
1432 Use one of these 2 keys to specify the name of the option you wish to
1435 @fkindex{getopt,:option}
1436 Alternatively, you can use a reference to an option object
1437 (@pxref{Constructors}).
1440 This function return two values: the option's value and the value's
1441 source (@pxenduserref{Value Sources}).
1444 The value's source may have the following forms:
1446 @item (:cmdline @var{NAME})
1447 @cindex Values, source, @cmdline{}
1448 This is for options found on the @cmdline{}. @var{NAME} is the name used
1449 on the @cmdline{}. It can be the option's long or short name, or a
1450 completed long name if the option's name was abbreviated. A completed
1451 name displays the omitted parts in parentheses (@code{"he(lp)"} for
1453 @item (:fallback @var{NAME})
1454 @cvopindex{:fallback-value}
1455 @cindex Values, source, fallback
1456 The same but when the fallback value is used, that is, when an option is
1457 not provided with its (optional) argument.
1458 @item (:default @var{NAME})
1459 @cvopindex{:default-value}
1460 @cindex Values, source, default
1461 The same, but when the default value is used (because there is no
1463 @item (:environment @var{VAR})
1465 @cindex Values, source, environment
1466 This is for options not found on the @cmdline{} but for which there is
1467 an associated environment variable set in the application's environment.
1468 @var{VAR} is the name of the corresponding environment variable.
1470 @cvopindex{:default-value}
1471 @cindex Values, source, default
1472 This is for options not found anywhere, but for which a default value
1478 Note that because flags don't take any argument, @code{getopt} returns a
1479 virtual value of @code{t} when they are found or a corresponding
1480 environment variable exists in the environment. For the same reason, a
1481 flag's value source may ony be @code{(:cmdline @var{NAME})} or
1482 @code{(:environment @var{VAR})}.
1485 When an option is not found anywhere and there is no default value,
1486 @code{getopt} just returns nil (no second value). Also, note that when
1487 your option accepts @code{nil} as a value, you @emph{need} to handle the
1488 second retrun value to make the difference between an option not found,
1489 and an actual value of @code{nil}.
1492 @node Sequential Retrieval, , Explicit Retrieval, Option Retrieval
1493 @subsection Sequential Retrieval
1494 @cindex Options Retrieval, sequential
1495 @cindex Retrieval, of options, sequential
1496 The more traditional approach to option retrieval is to scan the
1497 @cmdline{} for options in their order of appearance. @clon{} supports
1498 this by providing you with one function and two macros, as explained
1501 @defun getopt-cmdline
1502 Get the @dfn{next} @cmdline{} option, that is, the first option on the
1503 @cmdline{} that has not been previously retrieved, either explicitely or
1506 When there are no more options on the @cmdline{}, this function returns
1507 @code{nil}. Otherwise, four values are returned: the corresponding
1508 option object from the synopsis definition (@pxref{Constructors}), the
1509 name used on the @cmdline{}, the option's value and the value source
1510 (@code{:cmdline}, @code{:fallback} or @code{:default}). As in the case
1511 of explicit retrieval (@pxref{Explicit Retrieval}), the option's name
1512 may be completed in case of abbreviation.
1514 @rfindex{short-name}
1516 @copindex{:short-name}
1517 @copindex{:long-name}
1518 Unless you keep references to all your option objects (and thus can
1519 compare them directly to the one returned by this function), you can
1520 still identify the retrieved option by using the @code{short-name} and
1521 @code{long-name} readers on it: simply use @code{(long-name
1522 @var{OPTION})} or @code{(short-name @var{OPTION})} and you will get the
1523 corresponding strings.
1526 @defmac multiple-value-getopt-cmdline (OPTION NAME VALUE SOURCE) BODY
1527 Evaluate @var{BODY} with @var{OPTION}, @var{NAME}, @var{VALUE} and
1528 @var{SOURCE} bound to the values returned by the @code{getopt-cmdline}
1529 function above. Note that @var{BODY} is not evaluated if there was no
1530 remaining option on the @cmdline{}, so you don't need to conditionalize
1531 on @var{OPTION} being @code{null} yourself.
1534 @defmac do-cmdline-options (OPTION NAME VALUE SOURCE) BODY
1535 As above, but loop over all @cmdline{} options.
1542 @node Help, , Option Retrieval, Using Clon
1545 One of the first motivations in the design of @clon{} was to automate
1546 the generation of the help string, which is a very boring maintenance
1547 task to do by hand. The application's synopsis contains all the
1548 necessary information to do so. In order to print your application's
1549 help string, use the @code{help} function.
1551 @defun help [@code{:item} ITEM]
1552 @bioindex{search-path}
1553 @bievindex{SEARCH_PATH}
1554 @bioindex{highlight}
1555 @bievindex{HIGHLIGHT}
1558 @bioindex{line-width}
1559 @bievindex{LINE_WIDTH}
1560 Print the application's help string. Printing honors the search path,
1561 theme, line width and highlight settings provided by the corresponding
1562 built-in options (@pxenduserref{Theme Mechanism}).
1565 @fkindex{help,:item}
1566 By default, @code{help} prints the whole application help string,
1567 excluding hidden items. However, if you have kept a reference to any
1568 synopsis item (option, text, group), you can pass it as the value of the
1569 @code{:item} key, and @clon{} will only print the help string for that
1570 particular item. In this case however, the hidden state of the item is
1571 discarded (but @emph{not} the ones of sub-items).
1574 @cindex Built-In Groups
1575 @cindex Groups, built-in
1576 @cindex Hidden Groups
1577 @cindex Groups, hidden
1578 For instance, the @clon{} built-in group is normally hidden, so it
1579 doesn't show up in the global help string, but the @bioption{help}
1580 option uses the @code{help} function on it explicitely, so it discards
1583 Here is a potentially useful application of hidden groups in conjunction
1584 with the @code{:item} key. Look at ImageMagick's @file{convert}
1585 program's help string for instance: it is 276 lines long. Gosh. The help
1586 string is decomposed into several categories: image settings, image
1587 operators, misc options @etc{}. If I were to implement this program, I
1588 would rather have the @option{--help} option display an overview of the
1589 program, advertise @option{--version} and a couple of others, and I
1590 would then implement @option{--help} as an enumeration for listing every
1591 option category individually (they would normally be stored in hidden
1592 groups). The user could then use @option{--help=settings},
1593 @option{--help=operators} and so on to display only the category she's
1596 Finally, here is potentially useful application of hidden options that
1597 are never ever displayed in any help string whatsoever, and I mean,
1598 like, ever. This is the perfect tool for backdoor'ing a program. For
1599 instance, if you ever need to implement a
1600 @option{--discard-all-security-measures-and-blow-the-nuke} option, then
1601 you'd better have it hidden@dots{}
1605 @c ====================================================================
1607 @c ====================================================================
1608 @node Extending Clon, Advanced Usage, Using Clon, Top
1609 @chapter Extending Clon
1611 As you know, @clon{} already provides seven built-in option types: flags
1612 and six other types for valued options (@pxref{Built-In Valued
1613 Options}). After using @clon{} for a while, you may find that however
1614 brilliant and perfectly designed it is, none of the provided built-in
1615 types fullfill your requirements exactly. There are two ways around
1616 this: the right way and the wrong way (hint).
1618 @voindex{Strings,stropt}
1619 The wrong, although perhaps quicker way would be to use the
1620 @code{stropt} option type to simply retrieve unprocessed string values,
1621 and then do whatever tweaking required on them. In doing so, you risk
1622 reinventing some of @clon{}'s wheels.
1624 The right way is to define a new option type. Properly defined option
1625 types are a good thing because they allow for reusability and also
1626 extensibility, since new option types can always be defined on top of
1628 @voindex{Enumerations,enum}
1629 In this chapter we explain how to extend @clon{} by providing new option
1630 types. We illustrate the process with the example of the built-in
1633 @cindex Valued Options
1634 @cindex Options, valued
1636 Oh, and I almost forgot. I hope it is obvious to everyone that new
1637 option types are always @emph{valued}. There's no point in extending
1638 @clon{} with options that don't take any arguments, since we already
1642 * New Option Types:: In four steps
1643 * Extension Tips:: Some advice
1650 @node New Option Types, Extension Tips, Extending Clon, Extending Clon
1651 @section New Option Types
1652 @cindex Option Types, in files
1653 @cindex Files, one per option type
1654 @pkgindex{com.dvlsoft.clon}
1655 From a software engineering point of view, it is better to implement new
1656 option types in a file of their own, preferably named after the option
1657 type itself, and to put this file in the @clon{} package, like this:
1661 (in-package :com.dvlsoft.clon)
1665 Creating your own option type involves 5 steps: providing a class for
1666 them, implementing three protocols related to argument/value tweaking,
1667 and providing a constructor function. We now review those 5 steps in
1671 * New Option Classes:: Step 1
1672 * Value Check Protocol:: Step 2
1673 * Argument Conversion Protocol:: Step 3
1674 * Error Management:: In-between steps coffee time!
1675 * Value Stringification Protocol:: Step 4
1676 * Constructor Functions:: Step 5
1679 @node New Option Classes, Value Check Protocol, New Option Types, New Option Types
1680 @subsection New Option Classes
1682 @clsindex{valued-option}
1683 @clon{} maintains a class hierarchy for all option types. The mother of
1684 all option types is the @code{option} abstract class. It handles the
1685 options'short and long names, description and associated environment
1686 variable (@pxref{Common Properties}). Valued options inherit from an
1687 abstract subclass of @code{option} called @code{valued-option}. This
1688 class handles the option's argument name and status (optional or
1689 mandatory), fallback and default values (@pxref{Common Valued Option
1692 @cindex User-Defined Option Classes
1693 @cindex Option Classes, user-defined
1694 In order to create a new option type, use the @code{defoption} macro.
1696 @defmac defoption CLASS SUPERCLASSES SLOTS &rest OPTIONS
1697 Create a new option CLASS and register it with @clon{}.
1698 Syntactically, thismacro behaves like @code{defclass}. Option types
1699 created like this implicitely inherit from @code{valued-option} and in
1700 turn @code{option}, so you don't need to put them explicitely in the
1701 @var{SUPERCLASSES} list.
1704 Let's look at the enumeration example now.
1708 (defoption enum (enum-base)
1709 ((argument-name ;; inherited from the VALUED-OPTION class
1711 (:documentation "The ENUM class.
1712 This class implements options whose values belong to a set of keywords."))
1716 @voindex{Enumerations,enum}
1717 @vopindex{Enumerations,enum,:enum}
1718 @voindex{Extended Switches,xswitch}
1719 @vopindex{Extended Switches,xswitch,:enum}
1720 @clsindex{enum-base}
1721 As you can see, this class inherits from @code{enum-base}, which is the
1722 class handling the @code{:enum} property. The reason for this split is
1723 that there are currently two option types providing enumeration-like
1724 facility: @code{enum} and @code{xswitch}, so @code{xswitch} also
1725 inherits from @code{enum-base}.
1727 @clsindex{valued-option}
1728 @cvopindex{:argument-name}
1729 There are no new slots in this class, but the @code{argument-name} slot
1730 provided by the @code{valued-option} class has its initform changed from
1731 @code{"ARG"} to @code{"TYPE"}.
1733 @node Value Check Protocol, Argument Conversion Protocol, New Option Classes, New Option Types
1734 @subsection Value Check Protocol
1735 @cindex Value Check Protocol
1736 @cindex Protocols, value check
1737 Now that we have our new option class, we need to implement the
1738 so-called @dfn{value check} protocol. This protocol is used to make sure
1739 that values provided for options of your new type actually comply with
1740 the type in question. Values going through this protocol are fallback
1741 values, default values, and values provided from a debugger restart
1742 (@pxenduserref{Error Management}). In the case of fallback and default
1743 values (which, by the way, are provided by @emph{you}, the @clon{}
1744 user), the check is performed only once, when the option object is
1745 created. Values provided from a debugger restart come from the
1746 application end-user, and hence are checked every time.
1748 The value check protocol is implemented through a @code{check} generic
1749 function for which you must provide a method.
1751 @deffn {Generic Function} check OPTION VALUE
1753 @ecindex invalid-value
1754 Check that @var{VALUE} is valid for @var{OPTION}. If @var{VALUE} is
1755 valid, return it. Otherwise, raise an @code{invalid-value} error.
1758 As you can see, you need to provide a method with the first argument
1759 specialized to your new option type. This method must return @var{VALUE}
1760 if it is okay, and raise an @code{invalid-value} error otherwise.
1762 @ecindex invalid-value
1763 @clon{} maintains a hierarchy of error conditions. The
1764 @code{invalid-value} error condition is defined like this:
1768 (define-condition invalid-value (option-error)
1769 ((value :documentation "The invalid value."
1772 (comment :documentation "An additional comment about the error."
1776 (:report (lambda (error stream)
1777 (format stream "Option ~A: invalid value ~S.~@[~%~A~]"
1778 (option error) (value error) (comment error))))
1779 (:documentation "An invalid value error."))
1783 @ecindex invalid-value
1784 @ecsindex{invalid-value,value}
1785 @ecsindex{invalid-value,comment}
1786 When the error is raised, you must fill in the @code{value} and
1787 @code{comment} slots appropriately.
1788 @ecindex option-error
1789 @ecsindex{option-error,option}
1790 The super-condition @code{option-error} provides an additional
1791 @code{option} slot that you must also fill in when the error is raised.
1793 @gfmindex{check,@r{Enumerations (}enum@r{)}}
1794 @voindex{Enumerations,enum}
1795 @vopindex{Enumerations,enum,:enum}
1796 @findex list-to-string
1797 Let's look at the enumeration example now.
1801 (defmethod check ((enum enum) value)
1802 "Check that VALUE is a valid ENUM."
1803 (unless (member value (enum enum))
1804 (error 'invalid-value
1807 :comment (format nil "Valid values are: ~A."
1808 (list-to-string (enum enum)
1809 :key #'prin1-to-string))))
1814 This code should be self-explanatory. We check that the value we got
1815 belongs to the enumeration. @code{list-to-string} is a utility function
1816 that will separate every element with comas in the resulting string.
1818 @node Argument Conversion Protocol, Error Management, Value Check Protocol, New Option Types
1819 @subsection Argument Conversion Protocol
1820 @cindex Argument Conversion Protocol
1821 @cindex Protocols, argument conversion
1822 The next protocol we need to implement is the so-called @dfn{argument
1823 conversion} protocol. This protocol is used to convert option arguments
1824 (that is, strings) to an actual value of the proper type. Arguments
1825 going through this protocol come from the @cmdline{}, the value of an
1826 environment variable or a debugger restart (@pxenduserref{Error
1827 Management}). Also, note that @clon{} assumes that you implement this
1828 protocol correctly, so no value check is performed on values coming from
1829 the conversion of an argument.
1831 The conversion protocol is implemented through a @code{convert} generic
1832 function for which you must provide a method.
1834 @deffn {Generic Function} convert OPTION ARGUMENT
1835 @gfsubindex{convert}
1836 @ecindex invalid-argument
1837 Convert @var{ARGUMENT} to @var{OPTION's} value. If @var{ARGUMENT} is
1838 invalid, raise an @code{invalid-argument} error.
1841 As you can see, you need to provide a method with the first argument
1842 specialized to your new option type. This method must return the
1843 conversion of @var{ARGUMENT} to the appropriate type if it is valid, and
1844 raise an @code{invalid-argument} error otherwise.
1846 @ecindex invalid-argument
1847 The @code{invalid-argument} error condition is defined like this:
1851 (define-condition invalid-argument (option-error)
1852 ((argument :documentation "The invalid argument."
1856 (comment :documentation "An additional comment about the error."
1860 (:report (lambda (error stream)
1861 (format stream "Option ~A: invalid argument ~S.~@[~%~A~]"
1862 (option error) (argument error) (comment error))))
1863 (:documentation "An invalid argument error."))
1867 @ecindex invalid-argument
1868 @ecsindex{invalid-argument,argument}
1869 @ecsindex{invalid-argument,comment}
1870 When the error is raised, you must fill in the @code{argument} and
1871 @code{comment} slots appropriately.
1872 @ecindex option-error
1873 @ecsindex{option-error,option}
1874 As before, the super-condition @code{option-error} provides an
1875 additional @code{option} slot that you must also fill in when the error
1878 @gfmindex{convert,@r{Enumerations (}enum@r{)}}
1879 @voindex{Enumerations,enum}
1880 @vopindex{Enumerations,enum,:enum}
1881 @findex closest-match
1882 Let's look at the enumeration example now.
1886 (defmethod convert ((enum enum) argument)
1887 "Convert ARGUMENT to an ENUM value."
1888 (or (closest-match argument (enum enum) :ignore-case t :key #'symbol-name)
1889 (error 'invalid-argument
1892 :comment (format nil "Valid arguments are: ~A."
1893 (list-to-string (enum enum)
1894 :key (lambda (value)
1895 (stringify enum value)))))))
1900 Since enumerations allow their arguments to be abbreviated, a utility
1901 function named @code{closest-match} is used to find the closest match
1902 between an argument and the possible values. Otherwise, an
1903 @code{invalid-argument} error is raised. For an explanation of
1904 @code{stringify}, @xref{Value Stringification Protocol}.
1906 @node Error Management, Value Stringification Protocol, Argument Conversion Protocol, New Option Types
1907 @subsection Error Management
1909 @cindex Debugger restarts
1910 Let's take a short break in our @clon{} extension process. We have seen
1911 that @clon{} may throw errors in different situations, including invalid
1912 arguments or values. The end-user manual advertises that the interactive
1913 error handler offers a set of ``options to fix problems'' (if you don't
1914 know what I'm talking about, please read @enduserref{Error Management}
1915 and you will know). Well, you may have guessed that these options are
1916 simply ``restarts'' (of course, we don't use that term there, as we
1917 wouldn't want to frighten the casual user, or would we?).
1919 When you ship your application, you are encouraged to disable the
1920 debugger in the standalone executable because that also might scare the
1921 casual user a little bit (the end-user manual only mentions the
1922 @code{none} error-handler to explain that people shouldn't use it). The
1923 way error handling is done in @cl{} standalone executables is
1924 implementation-dependent, so please refer to your favorite compiler's
1925 documentation. More generally, the behavior of @cl{} standalone
1926 executables may depend on:
1929 the state of the Lisp environment when the application was dumped, which
1930 may in turn depend on command-line options passed to the Lisp itself
1931 (@pxref{Portability}),
1934 the arguments passed to the dumping function (look at @clon{}'s
1935 @code{dump} macro to see what it does),
1940 No, really, @cl{} is no fun at all.
1942 @node Value Stringification Protocol, Constructor Functions, Error Management, New Option Types
1943 @subsection Value Stringification Protocol
1944 Okay, back to implementing our new option type.
1946 @cindex Value Stringification Protocol
1947 @cindex Protocols, value stringification
1948 The third and last protocol we need to implement is called the
1949 @dfn{value stringification} protocol. This protocol can be seen as the
1950 reverse protocol for argument conversion (@pxref{Argument Conversion
1951 Protocol}): its purpose is to transform an option's value into a
1952 corresponding argument that the end-user could have provided in order to
1956 @cvopindex{:fallback-value}
1957 @cindex Values, source, fallback
1958 @cvopindex{:default-value}
1959 @cindex Values, source, default
1960 @gfmindex{convert,@r{Enumerations (}enum@r{)}}
1961 The main use for this protocol is to advertise the fallback and default
1962 values correctly in help strings: the end-user does not want to see
1963 those @emph{values}, but rather the @emph{argument} that would lead to
1964 them. However, you are free to use it wherever you like (see the
1965 @code{convert} method for @code{enum} options for instance).
1967 The value stringification protocol is implemented through a
1968 @code{stringify} generic function for which you must provide a method.
1970 @deffn {Generic Function} stringify OPTION VALUE
1971 @gfsubindex{stringify}
1972 Transform OPTION's @var{VALUE} into an argument.
1975 I admit that this function could also have been called
1976 @code{argumentize} or even @code{deconvertify}. As you can see, you need
1977 to provide a method with the first argument specialized to your new
1978 option type. You can assume that @var{VALUE} is a valid value for your
1979 option, so no checking is necessary and no error needs to be raised.
1981 @gfmindex{stringify,@r{Enumerations (}enum@r{)}}
1982 @voindex{Enumerations,enum}
1983 Let's look at the enumeration example now.
1987 (defmethod stringify ((enum enum) value)
1988 "Transform ENUM's VALUE into an argument."
1989 (string-downcase (symbol-name value)))
1993 Pretty straightforward, right?
1996 @node Constructor Functions, , Value Stringification Protocol, New Option Types
1997 @subsection Constructor Functions
1998 @cindex Constructors, for options objects
1999 @cindex Option Constructors
2000 The last required step to complete our new option type extension is to
2001 provide a @dfn{constructor} function that wraps around
2002 @code{make-instance} on the corresponding option class. I won't insult
2003 you by explaining how to write a constructor. Let me just give four good
2004 reasons why providing constructors is important.
2006 Providing a constructor for every new option type is important because:
2011 it is a good software engineering practice,
2017 and above all, it makes your new option type automatically available in
2018 calls to @code{defsynopsis} and @code{defgroup} (@pxref{Synopsis Items}
2019 and @ref{Group Definition}).
2023 @voindex{Enumerations,enum}
2025 Let's look at the enumeration example now.
2029 (defun make-enum (&rest keys
2030 &key short-name long-name description
2031 argument-name argument-type
2032 enum env-var fallback-value default-value
2034 "Make a new enum option.
2035 - SHORT-NAME is the option's short name (without the dash).
2037 - LONG-NAME is the option's long name (without the double-dash).
2039 - DESCRIPTION is the option's description appearing in help strings.
2041 - ARGUMENT-NAME is the option's argument name appearing in help strings.
2042 - ARGUMENT-TYPE is one of :required, :mandatory or :optional (:required and
2043 :mandatory are synonyms).
2044 It defaults to :optional.
2045 - ENUM is the set of possible values.
2046 - ENV-VAR is the option's associated environment variable.
2048 - FALLBACK-VALUE is the option's fallback value (for missing optional
2050 - DEFAULT-VALUE is the option's default value, if any.
2051 - When HIDDEN, the option doesn't appear in help strings."
2052 (declare (ignore short-name long-name description
2053 argument-name argument-type
2054 enum env-var fallback-value default-value
2056 (apply #'make-instance 'enum keys))
2060 Woah, what a mouthful for a single line of code@dots{} Yeah, I'm a
2061 maniac and I like redundancy. I always restate all the available keys
2062 explicitely, and everything again in the docstring so that all the
2063 interesting information is directly available (I might change my mind as
2064 I grow older though).
2070 @node Extension Tips, , New Option Types, Extending Clon
2071 @section Extension Tips
2072 So that's it. Now you know how to extend @clon{} with your own option
2073 types. Here is some piece of advice that you might find useful in the
2077 * Incremental Option Types:: Doing without defoption
2078 * Lisp Option Abuse:: Thinking in end-user terms
2081 @node Incremental Option Types, Lisp Option Abuse, Extension Tips, Extension Tips
2082 @subsection Incremental Option Types
2084 If one of the built-in options is almost what you need, you may be
2085 tempted to subclass it directly instead of using @code{defoption}, and
2086 only change what's needed, After all, it's Lisp. Lisp is a world of
2087 mess@t{^D^D^D^D}freedom.
2093 @code{defoption} is not @emph{only} a convenience wrapper around
2094 @code{defclass}. It also arranges for @code{defsynopsis} and
2095 @code{defgroup} to recognize your new option type. So please, do use it
2098 @node Lisp Option Abuse, , Incremental Option Types, Extension Tips
2099 @subsection Lisp Option Abuse
2100 @voindex{Lisp Objects,lispobj}
2101 @vopindex{Lisp Objects,lispobj,:typespec}
2102 Along with the same lines, you may find that the @code{lispobj} type is
2103 all you need in many situations. Let's take an example. Suppose you want
2104 to implement a @code{--stars} option to assign a rank to a movie, from 0
2105 to 5. The lazy approach is to simply create a @code{lispobj} option with
2106 a @code{:typespec} (type specifier) of @code{(integer 0 5)} and you're
2109 But now, remember that the end-user of your application is probably not
2110 a Lisper (in fact, I would hope that @clon{} contributes to increasing
2111 the number of standalone @cl{} applications out there@dots{}). What do
2112 you think would be her reaction, if, after providing a bogus value to
2113 the @code{--stars} option, she get the following error message:
2116 Option 'stars': invalid argument "6".
2117 Argument "6" must evaluate to (integer 0 5).
2120 or worse, a @code{"Cannot parse argument"} error message because of a
2123 Not very friendly, right? In other words, you need to think in terms of
2124 what the end-user of your application will expect. In that particular
2125 situation, you might want to subclass @code{lispobj} (with
2126 @code{defoption}!) only to provide friendlier error messages.
2130 @c ====================================================================
2132 @c ====================================================================
2133 @node Advanced Usage, Conclusion, Extending Clon, Top
2134 @chapter Advanced Usage
2136 This chapter contains information about different features that are
2137 present in @clon{} because of design decisions, but that I expect to be
2138 used only rarely, if at all.
2141 * Multiple Clon Instances:: Different command-lines, synopsis or contexts
2142 * Programmatic Help Strings:: Beyond the --help option
2143 * Version Numbering:: In case you need to conditionalize
2147 @c -----------------------
2148 @c Multiple Clon Instances
2149 @c -----------------------
2150 @node Multiple Clon Instances, Programmatic Help Strings, Advanced Usage, Advanced Usage
2151 @section Multiple @clon{} Instances
2153 It is possible to use different instances of @clon{} in parallel in a
2154 single application, by using a virtual @cmdline{} instead of the real
2155 one, different synopsis and multiple contexts simultaneously.
2158 * Using Different Synopsis:: The default one, and the others
2159 * Using Different Command-Lines:: The real one, and the others
2160 * Using Multiple Contexts:: The current one, and the others
2161 * Potential Uses:: What to do with all that
2164 @node Using Different Synopsis, Using Different Command-Lines, Multiple Clon Instances, Multiple Clon Instances
2165 @subsection Using Different Synopsis
2166 @cindex Synopsis, default
2167 Did you notice that after defining a synopsis, there is actually never
2168 any explicit reference to it anymore? So where is the magick? In fact,
2169 there's no magick at all involved here.
2171 @vindex *default-synopsis*
2172 @foindex{defsynopsis,:make-default}
2173 @cfiaindex{make-synopsis,:make-default}
2174 @clon{} has a global variable named @code{*default-synopsis*} which
2175 holds the@dots{} default synopsis, yeah. When you define/create a
2176 synopsis with either @code{defsynopsis} or @code{make-synopsis}, it is
2177 automatically made the default one, unless you use the
2178 @code{:make-default} option/initarg with a value of @code{nil}, like
2182 (defsynopsis (:make-default nil) ...)
2188 (make-synopsis :make-default nil ...)
2191 @cfindex{make-context}
2192 When you create a context with @code{make-context}, the default synopsis
2193 is used implicitely, but you have two ways to avoid this.
2197 @vindex *default-synopsis*
2198 At any time in your program, you may change the value of
2199 @code{*default-synopsis*}. All subsequent calls to @code{make-context}
2200 will hence use this other synopsis.
2202 @cfiaindex{make-context,:synopsis}@c
2203 If you prefer to use another synopsis only temporarily, you can use the
2204 @code{:synopsis} initarg to @code{make-context} instead.
2207 @node Using Different Command-Lines, Using Multiple Contexts, Using Different Synopsis, Multiple Clon Instances
2208 @subsection Using Different Command-Lines
2209 In @ref{Context Creation}, we saw that a context object describes a
2210 particular instance of your application, most notably depending on the
2211 actual @cmdline{} the end-user provided. It turns out, however that the
2212 @cmdline{} doesn't need to be the actual program's @cmdline{}, as the
2213 user typed it. Any list of strings can act as a @cmdline{}.
2215 @cfiaindex{make-context,:cmdline}
2216 The function @code{make-context} has a @code{:cmdline} key that allows
2217 you to provide any list of strings that will act as the @cmdline{}. Of
2218 course, the default is to use the actual program's one.
2220 @node Using Multiple Contexts, Potential Uses, Using Different Command-Lines, Multiple Clon Instances
2221 @subsection Using Multiple Contexts
2222 @cindex Context, current
2223 Did you also notice that after creating a context, there is actually
2224 never any explicit reference to it anymore? So again, where is the
2225 magick? In fact, there's no magick at all involved here either.
2227 @vindex *current-context*
2228 @cfiaindex{make-context,:make-current}
2229 @clon{} has a global variable named @code{*current-context*} which holds
2230 the@dots{} current context, yeah. When you create a context with
2231 @code{make-context}, it is automatically made current, unless you use
2232 the @code{:make-current} initarg with a value of @code{nil}.
2234 @cindex Runtime Phase
2237 @findex cmdline-options-p
2240 @findex getopt-cmdline
2241 @findex multiple-value-getopt-cmdline
2242 @findex do-cmdline-options
2244 The whole runtime phase API of @clon{} uses a context implicitely. This
2245 involves @code{progname}, @code{remainder}, @code{cmdline-options-p},
2246 @code{cmdline-p}, @code{getopt}, @code{getopt-cmdline},
2247 @code{multiple-value-getopt-cmdline}, @code{do-cmdline-options} and
2248 @code{help}. As a consequence, it is possible to use @clon{} with
2249 multiple contexts at the same time. There are in fact three ways to
2254 @vindex *current-context*
2255 At any time in your program, you may change the value of
2256 @code{*current-context*}. All subsequent calls to the runtime phase API
2257 will hence use this other context.
2259 @clon{} also provides a macro which changes the current context for you.
2260 @defun with-context CONTEXT &body BODY
2261 Execute @var{BODY} with @code{*current-context*} bound to @var{CONTEXT}.
2264 @fkindex{progname,:context}@c
2265 @fkindex{remainder,:context}@c
2266 @fkindex{cmdline-options-p,:context}@c
2267 @fkindex{cmdline-p,:context}@c
2268 @fkindex{getopt,:context}@c
2269 @fkindex{getopt-cmdline,:context}@c
2270 @fkindex{help,:context}@c
2271 @foindex{multiple-value-getopt-cmdline,:context}@c
2272 @foindex{do-cmdline-options,:context}@c
2273 If you prefer to use another context only once, you can use the
2274 @code{:context} key instead. The whole runtime phase API of @clon{}
2275 understands it. For the functions @code{getopt}, @code{getopt-cmdline}
2276 and @code{help}, it's just another key in addition to those we've
2277 already seen. For the macros @code{multiple-value-getopt-cmdline} and
2278 @code{do-cmdline-options}, the key must appear at the end of the first
2279 (list) argument, like this:
2282 (multiple-value-getopt-cmdline (option name value :context ctx) ...)
2283 (do-cmdline-options (option name value :context ctx) ...)
2287 @node Potential Uses, , Using Multiple Contexts, Multiple Clon Instances
2288 @subsection Potential Uses
2289 By combining @clon{}'s ability to use a virtual @cmdline{}, different
2290 synopsis and multiple contexts, you can achieve very neat (read: totally
2291 useless) things. For instance, you could write an application that takes
2292 an option providing @cmdline{} arguments for an external program to be
2293 forked. Some revision control systems do that for controlling external
2294 @code{diff} programs for instance, so no big deal. The big deal is that
2295 you can completely control the validity of the external program's
2296 @cmdline{}, before it is forked, from your original one.
2298 Here is another idea, again related to revision control systems. Some of
2299 them feature a @cmdline{} syntax like the following:
2302 prog [global options] command [command-specific options]
2306 @cindex Command-Line, remainder
2307 @cindex Remainder, of command-line
2308 You can achieve this with @clon{} quite easily. In fact, the
2309 demonstration program called @file{advanced} in the distribution shows
2310 you how to do it. First, define a synopsis which only handles the global
2311 options, and provide a postfix of @code{"command [command-specific
2312 option]"} or something like that. This will authorize a @cmdline{}
2313 remainder which will start with the command name.
2315 Now, for every command in your program, define a specific synopsis with
2316 only the command-specific options. Get the remainder of the original
2317 @cmdline{} (@pxref{Command-Line Remainder}) and figure out which command
2318 was used. Depending on it, create a new context with the appropriate
2319 synopsis and the original @cmdline{}'s remainder as the new, virtual,
2320 @cmdline{}. You're done: retrieve global options from the first context,
2321 and command-specific ones from the second one.
2323 @cindex Help String, display
2325 What's even cooler is that you can display the command-specific options
2326 on demand quite easily as well (like what @file{git} does when you call
2327 it like this: @code{git commit --help} for instance): calling the
2328 @code{help} function on the original context gives you the global
2329 options's help string while calling it on the command-specific one will
2330 display the command-specific usage.
2332 @bioindex{search-path}
2333 @bievindex{SEARCH_PATH}
2334 @bioindex{highlight}
2335 @bievindex{HIGHLIGHT}
2338 @bioindex{line-width}
2339 @bievindex{LINE_WIDTH}
2340 One thing to remember here is that every context/synopsis duet you
2341 create gets its own set of built-in @clon{} options. As a consequence,
2342 there is currently no simple way to have a single set of built-in
2343 options apply to the whole application, for instance, to both a global
2344 and a command-specific context. Let me make this clearer: if your
2345 end-user calls @code{prog --clon-theme=foo command -h}, then the theme
2346 option will have no effect because it would only affect the global help
2347 option. In order to actually use the expected theme, your end-user would
2348 need to use @code{prog command --clon-theme=foo -h}. Depending on which
2349 cerebral emisphere (s)he prefers to use, this may seem logical or not.
2351 Finally, note that you can use the virtual @cmdline{} / specific
2352 synopsis technique recursively to manage complicated @cmdline{} syntax,
2353 for instance alternating options and non-options parts several times.
2355 In the future, @clon{} may provide better ways to achieve this kind of
2356 things (a notion of ``sub-context'' may be in order).
2360 @c -------------------------
2361 @c Programmatic Help Strings
2362 @c -------------------------
2363 @node Programmatic Help Strings, Version Numbering, Multiple Clon Instances, Advanced Usage
2364 @section Programmatic Help Strings
2369 @cindex Themes, standard, @t{refcard}
2370 @cindex Standard Themes, @t{refcard}
2371 So far, we've seen how to use the @code{help} function to implement a
2372 typical @code{--help} option. This is mostly intended for the end-user.
2373 There are also times when this function could be useful to @emph{you},
2374 the application developer. For instance, one could imagine that part of
2375 the compilation phase would involve generating the help string in order
2376 to include it in the manual. Another idea would be that @samp{make
2377 install} creates a @file{REFCARD} file in
2378 @file{/usr/local/share/doc/my-app/} which contains the help string
2379 formatted with the @code{refcard} theme, @etc{}.
2383 @bioindex{search-path}
2384 @bievindex{SEARCH_PATH}
2385 @bioindex{line-width}
2386 @bievindex{LINE_WIDTH}
2387 @bioindex{highlight}
2388 @bievindex{HIGHLIGHT}
2389 In such situations, calling the @code{help} function might not be
2390 directly associated with an end-user level option, or at least not
2391 @code{--help}, and you might not want to honor the end-user level
2392 settings for theme, search path, line-width, or highlighting either
2393 (remember that these settings might come from the environment variables
2394 associated with @bioption{theme}, @bioption{search-path},
2395 @bioption{line-width} and @bioption{highlight}).
2397 @fkindex{help,:theme}
2398 @fkindex{help,:search-path}
2399 @fkindex{help,:line-width}
2400 @fkindex{help,:highlight}
2401 Because of this, the @code{help} function provides additional keys that
2402 allow you to override those settings (they are in fact stored in the
2403 context object). The keys in question are: @code{:theme},
2404 @code{:search-path}, @code{:line-width} and @code{:highlight}.
2406 @fkindex{help,:output-stream}
2407 @vindex *standard-output*
2408 In addition to that, there is an @code{:output-stream} key which
2409 defaults to @code{*standard-output*} which you could use for instance to
2410 write directly to a file. Note that there is no end-user level access to
2415 @c -----------------
2416 @c Version Numbering
2417 @c -----------------
2418 @node Version Numbering, , Programmatic Help Strings, Advanced Usage
2419 @section Version Numbering
2422 As @clon{} evolves over time, you might one day feel the need for
2423 conditionalizing your code on the version of the library. While the
2424 end-user of your application has limited means to access the current
2425 version number of @clon{} (see @enduserref{Clonification} and the
2426 built-in option @bioption{version}), you, the application programmer
2427 and @clon{} user, have a finer grained access to it.
2429 The first thing you can do to access the current version number of
2430 @clon{} is use the @code{version} function (this is in fact the function
2431 bound to the @bioption{version} option).
2433 @defun version &optional (TYPE :number)
2434 Return the current version number of @clon{}. @var{TYPE} can be one of
2435 @code{:number}, @code{:short} or @code{:long}. For @code{:number}, the
2436 returned value is a fixnum. Otherwise, it is a string.
2439 A @clon{} version is characterized by 4 elements as described below.
2442 @vindex +release-major-level+
2443 A major version number stored in the constant
2444 @code{+release-major-level+}.
2446 @vindex +release-minor-level+
2447 A minor version number, stored in the constant
2448 @code{+release-minor-level+}.
2450 @vindex +release-status+
2451 A release status stored in the constant @code{+release-status+}. The
2452 status of a release can be @code{:alpha}, @code{:beta}, @code{:rc}
2453 (standing for ``release candidate'') or @code{:patchlevel}. These are in
2454 effect 4 levels of expected stability.
2456 @vindex +release-status-level+
2457 A status-specific version number stored in the constant
2458 @code{+release-status-level+}. Status levels start at 1 (alpha 1, beta 1
2459 and release candidate 1) except for stable versions, in which case patch
2460 levels start at 0 (@eg{} 2.4.0).
2463 @vindex +release-name+
2464 In addition to that, each version of @clon{} (in the sense
2465 @emph{major.minor}, regardless of the status) has a name, stored in the
2466 constant @code{+release-name+}. The general theme for @clon{} is ``Great
2467 Jazz Musicians'', and specifically for the 1.x series: ``Great Saxophone
2468 Players''. Anyone daring to mention Kenny G at that point will be shot
2471 Here is how the @code{version} function computes its value.
2474 A version @code{:number} is computed as @emph{major . 10000 + minor .
2475 100 + patchlevel}, effectively leaving two digits for each level. Note
2476 that alpha, beta and release candidate status are ignored in version
2477 numbers (this is as if the corresponding status level was considered to
2478 be always 0). Only stable releases have their level taken into account.
2480 A @code{:short} version will appear like this for unstable releases:
2481 1.3a4, 2.5b8 or 4.2rc1. Remember that alpha, beta or release candidate
2482 levels start at 1. Patchlevels for stable releases start at 0 but 0 is
2483 ignored in the output. So for instance, version 4.3.2 will appear as-is,
2484 while version 1.3.0 will appear as just 1.3.
2486 A @code{:long} version is expanded from the short one, and includes the
2487 release name. For instance, 1.3 alpha 4 "Bill Evans", 2.5 beta 8 "Scott
2488 Henderson", 4.2 release candidate 1 "Herbie Hancock" or 4.3.2 "Chick
2489 Corea". As for the short version, a patchlevel of 0 is ignored in the
2490 output: 1.3 "Bill Evans".
2495 @c ====================================================================
2497 @c ====================================================================
2498 @node Conclusion, Portability, Advanced Usage, Top
2501 So that's it I guess. You know all about @clon{} now. The next step is
2502 to actually use it to clonify your favorite application, write new
2503 applications using it and contaminate the world with standalone @cl{}
2504 programs, featuring unprecedented @cmdline{} power and thrill-a-minute
2507 Now, go Luke. The Attack of the @clon{} is ready to begin.
2511 @c ====================================================================
2513 @c ====================================================================
2514 @node Portability, API Quick Reference, Conclusion, Top
2515 @appendix Portability
2517 @clon{} is mostly portable and has virtually no dependency at all, by
2518 design. There are a couple of spots however where portability might be a
2519 direct concern for you.
2522 * Supported Environments:: Systems, compilers and dependencies
2523 * Dumping Executables:: Convenience wrappers
2527 @c ----------------------
2528 @c Supported Environments
2529 @c ----------------------
2530 @node Supported Environments, Dumping Executables, Portability, Portability
2531 @section Supported Environments
2532 @clon{} currently works on Unix systems (including MacOS X) and has been
2533 ported to 6 @cl{} implementations. I have no idea about Windows right
2534 now. The following table lists the supported environments.
2536 @multitable {Compiler} {Minimum Version} {@code{cffi} (optional)}
2537 @headitem Compiler @tab Minimum Version @tab Dependencies
2552 @tab @code{cffi} (optional)
2554 @tab 0.24.0@footnote{more precisely, svn trunk revision 13156}
2558 @unnumberedsubsec ABCL specificities
2559 @clon{}'s ABCL port currently has two limitations:
2562 @bioindex{highlight}@c
2563 @bioindex{line-width}@c
2565 Terminal autodetection is not supported. This means that
2566 @bioption{highlight=auto} doesn't work (highlighting is @emph{not}
2567 turned on automatically on a @tty{}). For the same reason, unless
2568 otherwise specified via either the @code{COLUMNS} environment variable
2569 or the @bioption{line-width} option, terminal output will be formatted
2570 for 80 columns regardless of the actual width (@pxenduserref{Global
2573 Since Java doesn't have a @code{putenv} or @code{setenv} function (!!),
2574 the @code{modify-environment} restart, normally proposed when an
2575 environment variable is set to a bogus value, is unavailable
2576 (@pxenduserref{Error Management}).
2579 @unnumberedsubsec CLISP specificities
2580 As mentioned in the above table, CLISP's dependency on @code{cffi} is
2581 optional. CLISP needs @code{cffi} in order to implement terminal
2582 autodetection only. If @code{cffi} cannot be found when the ASDF system
2583 is loaded, you get a big red blinking light and a warning but that's
2584 all. @clon{} will still work, although exhibiting the same limitation as
2588 @c -------------------
2589 @c Dumping Executables
2590 @c -------------------
2591 @node Dumping Executables, , Supported Environments, Portability
2592 @section Dumping Executables
2594 Creating standalone executables is orthogonal to @clon{}. @clon{} is
2595 just a library that you might want to use, and in fact, it is also
2596 possible to use it without dumping executables at all.
2600 Unfortunately, there is no standard way to dump executables from Lisp.
2601 We're entering the portability mine field here. @clon{}, however, wants
2602 to help. We've already seen that it provides utility wrappers like
2603 @code{exit} and @code{dump} to make your life easier (I mean, more
2604 portable) in @ref{Quick Start}. If you're not interested in portability
2605 or if you prefer to do it your own way, you don't @emph{need} to use
2606 those wrappers. If you do, however, please read on.
2608 Continuing on the quickstart example, the table below provides
2609 ready-to-use @cmdline{} samples for dumping the program with the
2610 compilers currently supported. Remember that they work in conjunction
2611 with the @code{dump} macro mentionned above.
2615 @code{CC=gcc sbcl --script quickstart.lisp}@*
2616 The @code{CC=gcc} bit is needed for the @code{sb-grovel} contrib module
2619 @code{lisp -noinit -nositeinit -load quickstart.lisp}
2621 @code{ccl --no-init --load quickstart.lisp}
2623 ECL doesn't work like the other Lisp compilers. In particular, creating
2624 an executable does not involve dumping a Lisp image, but compiling the
2625 source into separate object files and then linking them. The consequence
2626 is that there is no simple @cmdline{} recipe to show here. Instead, you
2627 might want to look at the file @file{demos/dump.lisp} in the
2628 distribution for an example.
2630 Because the dumping scheme is different with ECL, it is also less
2631 straightforward to write portable code for standalone applications. The
2632 demo programs in the distribution both contain comments that are worth
2633 reading at the top of them.
2636 One specific difference between ECL and the other Lisp compilers is that
2637 it doesn't require you to specify a particular function as the entry
2638 point for your executable, but instead relies on having code to execute
2639 directly at the toplevel of some file. @clon{}'s @code{dump} macro helps
2640 you with this: it normally expands to a compiler-specific function which
2641 saves the current Lisp image, but for ECL, it simply expands to the
2642 ``main'' function call, hence consituting the entry point to the code
2645 @code{CC=gcc clisp -norc -i quickstart.lisp}@*
2646 The @code{CC=gcc} bit lets you choose your preferred C compiler for
2647 @code{cffi}. Please note that executables dumped (the @clon{} way) by
2648 CLISP still understand lisp-specific command-line options when they are
2649 prefixed with @code{--clisp-}, so you should obviously avoid defining
2650 options by those names.
2652 ABCL is a totally different beast because it's a Java-based @cl{}
2653 implementation. Most notably, you don't create standalone executables in
2654 Java, so the normal way of running ABCL is by telling it to load some
2655 lisp code. If you want to run the quickstart program in the usual way,
2656 you will typically type this:
2658 abcl --noinform --noinit --nosystem --load quickstart.lisp
2660 Note that for this to work, the @code{dump} macro expands to the
2661 ``main'' function call for ABCL, just as for ECL.
2663 There's more to it than that though. It is possible to get closer to
2664 standalone executables with ABCL by 1/ providing your whole application
2665 in a @code{jar} file directly, and 2/ overriding ABCL's entry point by
2666 providing your own interpreter which runs your main function
2669 @vindex com.dvlsoft.clon.dump
2670 @clon{} helps you to do this to some extend. If the variable
2671 @code{com.dvlsoft.clon.dump} is bound in the @code{cl-user} package,
2672 then the @code{dump} macro doesn't expand to a call to the ``main''
2673 function, but instead dumps a Java file containing an alternate ABCL
2674 interpreter that you can compile and add to the original ABCL @code{jar}
2675 file, along with @file{quickstart.lisp}. If you want more details on
2676 this, you will need to look at the @file{Makefile} in the @code{demo}
2682 @c ====================================================================
2683 @c API Quick Reference
2684 @c ====================================================================
2685 @node API Quick Reference, Indexes, Portability, Top
2686 @appendix API Quick Reference
2689 * Utilities:: Miscellaneous stuff
2690 * Initialization Phase API:: Synopsis, items and context creation
2691 * Runtime Phase API:: Option retrieval and help formatting
2692 * Extension API:: New option types
2693 * Versioning API:: Release identification
2700 @node Utilities, Initialization Phase API, API Quick Reference, API Quick Reference
2703 @defmac dump NAME FUNCTION
2704 See @ref{Quick Start}.
2707 @defun exit &optional (STATUS 0)
2708 See @ref{Quick Start}.
2711 @cindex Command-Line
2713 See @ref{Option Retrieval}.
2716 @cindex Package, nicknames
2717 @defun nickname-package &optional NICKNAME
2718 See @ref{Quick Start}.
2722 @c ------------------------
2723 @c Initialization Phase API
2724 @c ------------------------
2725 @node Initialization Phase API, Runtime Phase API, Utilities, API Quick Reference
2726 @section Initialization Phase API
2728 @defun make-text &key CONTENTS HIDDEN
2729 @cfsubindex{make-text}
2730 @cfiaindex{make-text,:contents}
2731 @cfiaindex{make-text,:hidden}
2732 @defunx make-@var{OPTION} :INITARG INITVAL@dots{}
2733 @cfsubindex{make-@var{OPTION}}
2735 @cfindex make-stropt
2736 @cfindex make-lispobj
2739 @cfindex make-switch
2740 @cfindex make-xswitch
2741 @defunx make-group &key HEADER HIDDEN ITEM
2742 @cfsubindex{make-group}
2743 @cfiaindex{make-group,:header}
2744 @cfiaindex{make-group,:hidden}
2745 @cfiaindex{make-group,:item}
2746 @defunx make-synopsis &key POSTFIX ITEM (MAKE-DEFAULT t)
2747 @cfsubindex{make-synopsis}
2748 @cfiaindex{make-synopsis,:postfix}
2749 @cfiaindex{make-synopsis,:item}
2750 @cfiaindex{make-synopsis,:make-default}
2751 See @ref{Constructors} and @ref{Using Different Synopsis}.
2754 @defmac defgroup (&key HEADER HIDDEN) &body FORMS
2755 @foindex{defgroup,:header}
2756 @foindex{defgroup,:hidden}
2757 @xref{Group Definition}.
2760 @defmac defsynopsis (&key POSTFIX MAKE-DEFAULT) &body FORMS
2761 @foindex{defsynopsis,:postfix}
2762 @foindex{defsynopsis,:make-default}
2763 @fiindex{defsynopsis,text}
2764 @fiindex{defsynopsis,options}
2765 @fiindex{defsynopsis,group}
2766 See @ref{Synopsis Definition} and @ref{Using Different Synopsis}.
2769 @defopt *default-synopsis*
2770 @xref{Using Different Synopsis}.
2773 @defun make-context &key (SYNOPSIS *default-synopsis*) CMDLINE @
2775 @cfsubindex{make-context}
2776 @cfiaindex{make-context,:synopsis}
2777 @cfiaindex{make-context,:cmdline}
2778 @cfiaindex{make-context,:make-current}
2779 @xref{Context Creation}, @ref{Using Different Synopsis} and @ref{Using
2780 Different Command-Lines}.
2785 @c -----------------
2786 @c Runtime Phase API
2787 @c -----------------
2788 @node Runtime Phase API, Extension API, Initialization Phase API, API Quick Reference
2789 @section Runtime Phase API
2791 @defopt *current-context*
2792 @xref{Using Multiple Contexts}.
2795 @defun with-context CONTEXT &body BODY
2796 @xref{Using Multiple Contexts}.
2799 @defun progname &key (CONTEXT *current-context*)
2800 @fkindex{progname,:context}
2801 See @ref{Contextual Information} and @ref{Using Multiple Contexts}.
2804 @defun remainder &key (CONTEXT *current-context*)
2805 @fkindex{remainder,:context}
2806 See @ref{Contextual Information} and @ref{Using Multiple Contexts}.
2809 @defun cmdline-options-p &key (CONTEXT *current-context*)
2810 @fkindex{cmdline-options-p,:context}
2811 See @ref{Command-Line Polling} and @ref{Using Multiple Contexts}.
2814 @defun cmdline-p &key (CONTEXT *current-context*)
2815 @fkindex{cmdline-p,:context}
2816 See @ref{Command-Line Polling} and @ref{Using Multiple Contexts}.
2819 @defun getopt &key (CONTEXT *current-context*) SHORT-NAME LONG-NAME @
2821 @fkindex{getopt,:context}
2822 @fkindex{getopt,:short-name}
2823 @fkindex{getopt,:long-name}
2824 @fkindex{getopt,:option}
2825 @vindex *current-context*
2826 See @ref{Explicit Retrieval} and @ref{Using Multiple Contexts}.
2829 @defun getopt-cmdline &key (CONTEXT *current-context*)
2830 @fkindex{getopt-cmdline,:context}
2831 @vindex *current-context*
2832 See @ref{Sequential Retrieval} and @ref{Using Multiple Contexts}.
2835 @defmac multiple-value-getopt-cmdline (OPTION NAME VALUE SOURCE &key CONTEXT) @
2837 @defmacx do-cmdline-options (OPTION NAME VALUE SOURCE &key CONTEXT) @
2839 @foindex{multiple-value-getopt-cmdline,:context}
2840 @foindex{do-cmdline-options,:context}
2841 See @ref{Sequential Retrieval} and @ref{Using Multiple Contexts}.
2844 @deffn Reader short-name OPTION
2845 @rfsubindex{short-name}
2846 @deffnx Reader long-name OPTION
2847 @rfsubindex long-name
2848 @xref{Sequential Retrieval}.
2851 @defun help &key (CONTEXT *current-context*) @
2852 (ITEM (synopsis context)) @
2853 (OUTPUT-STREAM *standard-output*) @
2854 (SEARCH-PATH (search-path context)) @
2855 (THEME (theme context)) @
2856 (LINE-WIDTH (line-width context)) @
2857 (HIGHLIGHT (highlight context)))
2858 @fkindex{help,:context}
2859 @fkindex{help,:item}
2860 @fkindex{help,:output-stream}
2861 @fkindex{help,:theme}
2862 @fkindex{help,:search-path}
2863 @fkindex{help,:line-width}
2864 @fkindex{help,:highlight}
2865 @vindex *current-context*
2866 @vindex *standard-output*
2867 @xref{Help}, @ref{Using Multiple Contexts} and @ref{Programmatic Help
2875 @node Extension API, Versioning API, Runtime Phase API, API Quick Reference
2876 @section Extension API
2878 @defmac defoption CLASS SUPERCLASSES SLOTS &rest OPTIONS
2879 @pxref{New Option Classes}
2882 @deffn {Generic Function} check OPTION VALUE
2884 @xref{Value Check Protocol}.
2887 @deftp {Error Condition} option-error OPTION
2888 @ecsubindex{option-error}
2889 @ecsindex{option-error,option}
2890 @deftpx {Error Condition} invalid-value VALUE COMMENT
2891 @ecsubindex{invalid-value}
2892 @ecsindex{invalid-value,value}
2893 @ecsindex{invalid-value,comment}
2894 @xref{Value Check Protocol}.
2897 @deffn {Generic Function} convert OPTION ARGUMENT
2898 @gfsubindex{convert}
2899 @xref{Argument Conversion Protocol}.
2902 @deftp {Error Condition} invalid-argument ARGUMENT COMMENT
2903 @ecsubindex{invalid-argument}
2904 @ecsindex{invalid-argument,argument}
2905 @ecsindex{invalid-argument,comment}
2906 @xref{Argument Conversion Protocol}.
2909 @deffn {Generic Function} stringify OPTION VALUE
2910 @gfsubindex{stringify}
2911 @xref{Value Stringification Protocol}.
2918 @node Versioning API, , Extension API, API Quick Reference
2919 @section Versioning API
2921 @defun version &optional (TYPE :number)
2922 @xref{Version Numbering}.
2925 @defvr Constant +release-major-level+
2926 @defvrx Constant +release-minor-level+
2927 @defvrx Constant +release-status+
2928 @defvrx Constant +release-status-level+
2929 @defvrx Constant +release-name+
2930 @xref{Version Numbering}.
2935 @c ====================================================================
2937 @c ====================================================================
2938 @node Indexes, Acknowledgments, API Quick Reference, Top
2942 * Concept Index:: Well, the concept index
2943 * Function Index:: Well, the function index
2944 * Variable Index:: Well, the variable index
2945 * Data Type Index:: Well, the data type index
2952 @node Concept Index, Function Index, Indexes, Indexes
2961 @node Function Index, Variable Index, Concept Index, Indexes
2970 @node Variable Index, Data Type Index, Function Index, Indexes
2979 @node Data Type Index, , Variable Index, Indexes
2985 @c ====================================================================
2987 @c ====================================================================
2988 @node Acknowledgments, , Indexes, Top
2989 @appendix Acknowledgments
2990 The following people have contributed bug reports or fixes, suggestions,
2991 compiler support or any other kind of help. You have my gratitude!
2993 @multitable @columnfractions .99
2997 François-René Rideau@*
3004 @c LocalWords: Clon clon cmdline Clonification tty emph CmdLine clonified SGR
3005 @c LocalWords: clonfiscated clonistified clonificated clonificationated samp
3006 @c LocalWords: cindex subsubsection pxref Didier Nuker postfix Runtime cth
3007 @c LocalWords: cartouche toplevel prepended IEC
3009 @c user.texi ends here