README.txt

Path: examples/older/README.txt
Last Update: Sat Aug 18 15:00:50 -0500 2007

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

Type checks and conversions

+ 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

A range of arguments ==

+ 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

[Validate]