Here are brief instructions for using the different scripts in this directory. The tutorial files aren’t described here; instead, the tutorial (on the website) describes them.
== Command-line arguments ==
+ Help is generated for you:
prompt> ruby command-line.rb –help
+ Options are placed into a hash, as is the argument list
prompt> ruby command-line.rb –choice cho sophie paul dawn me
+ The usual variant ways of specifying options
prompt> ruby command-line.rb -c choice prompt> ruby command-line.rb -cchoice prompt> ruby command-line.rb –choi choice prompt> ruby command-line.rb –choi choice – -name1- -name2-
+ There are error messages for extra and malformed options
prompt> ruby command-line.rb –choice prompt> ruby command-line.rb –other 3 – choice
== Default values ==
+ You can specify default values when you define choices.
prompt> ruby default-values.rb –choice specific prompt> ruby default-values.rb
+ Note: defaulting behavior applies to other sources of choices, not
just command lines.
== Optional arguments ==
+ When single optional arguments are required, the result is not a
list - it's either the value or nothing.
prompt> ruby default-values.rb only-arg
+ There are ways to describe what kind of thing an argument
is. (Currently limited.)
prompt> ruby types.rb –a-or-b not-a argument prompt> ruby types.rb –must-be-integer 1d argument prompt> ruby types.rb –option-list first,second argument
+ Integer-valued options are converted into integers, not left as
strings:
prompt> ruby types.rb –must-be-integer 3 argument
+ Type-checking and type conversions apply to all sources, not just
command lines.
== Required Arguments ==
+ You can require exactly one argument:
prompt> ruby types.rb prompt> ruby types.rb argument extra-argument
== Switches (values without arguments) ==
+ Switches can also be specified. Typically, their values are either
true or false (rather than strings or numbers).
+ How they are given on the command line may be unfamiliar to you:
prompt> ruby switches.rb –help
+ Examples of use:
prompt> ruby switches.rb 1 2 prompt> ruby switches.rb –switch 1 2 prompt> ruby switches.rb -s 2 1 prompt> ruby switches.rb –no-switch 1 2
+ You can require that the number of arguments be in a range. In this
case, it's 2-4:
prompt> ruby switches.rb 1 prompt> ruby switches.rb 1 2 prompt> ruby switches.rb 1 2 3 4 prompt> ruby switches.rb 1 2 3 4 5
+ You can also require any particular exact number of arguments:
prompt> ruby two-args.rb 1 prompt> ruby two-args.rb 1 2 prompt> ruby two-args.rb 1 2 3
== Postprocessing ==
+ You can also postprocess choices into a form more convenient for the
rest of the program.
prompt> ruby postprocess.rb 1 2
== Multiple Sources ==
+ First see what happens when no arguments are given.
prompt> ruby command-line.rb
+ Create a file named ms-config.xml in your home / login folder, and
put the following in it. (Note the underscore in "ordinary_choice" -
this is the name of the choice, not the representation of that choice
on the command line.)
<config>
<ordinary_choice>greetings</ordinary_choice>
</config>
prompt> ruby multiple-sources.rb
Set an environment variable ms_ordinary_choice with value ‘hi’.
prompt> ruby multiple-sources.rb
Which takes precedence, the environment or the configuration file? (This is configurable.)
The command line arguments have highest precedence of all:
prompt> ruby multiple-sources.rb –ordinary-choice hello