home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ruby164.zip / rbemx164.zip / ruby / share / doc / optparse-0.8.2 / getopts.test.en < prev    next >
Text File  |  2001-06-18  |  4KB  |  136 lines
  1. # -*- rd -*-
  2. =begin
  3. = sample for optparse
  4. This script is comes from "sample/getopts.rb" contained in Ruby
  5. standard distribution and modified in order to show usage of
  6. ((<optparse>)).
  7. =end
  8. =begin undocumented
  9. == Global constant
  10. : Version
  11.   It's not mandatory, however, (({--version})) option gets available if defined.
  12. =end
  13. =begin
  14. == Default values
  15. Defining options' default values.
  16.  
  17. Since scope of local variables appear in a block is restricted within the block,
  18. they must be initialized before.
  19.  
  20. Otherwise, global or instance variables don't require initialization
  21. cause they aren't restricted by block, however, I suggest
  22. initialization even in such case.
  23. ((- Also recommended as "initialize even if it's just nil" in the Ruby book. -))
  24. =end
  25. =begin
  26. == Script name
  27. Trimming script name to just base name.
  28. =end
  29. =begin
  30. == Options block
  31. If given a block, (({ARGV.options})) passes the OptionParser
  32. instance(creating if needed). It's return value is the value returned
  33. from the block itself.
  34.  
  35. Also, in the block, (({OptionParser::ParseError}))'s would be
  36. (({rescue}))d and only error message would be printed to (({STDERR})).
  37. In this case, (({nil})) is returned.
  38. =end
  39. =begin
  40. === Banner
  41. The banner message on the top of help message. It's used as-is.
  42. =end
  43. =begin
  44. === No argument option
  45. --- -d --debug debug message
  46.     String starts with (({-})) means short, one with (({--})) means long style option switch,
  47.     or mean argument specifications with (({=})).
  48.     Any other strings are descriptions shown in the help message.
  49.     There is no features folding long lines, however, since multiple
  50.     description are available, cut too long lines.
  51.     
  52.     In this case, (({true})) is assigned to ((|debug|)).
  53.     
  54.     As block parameter, since it's required just assignable, not only
  55.     local variable, global or outer variable, instance variable or
  56.     even accessor are available.
  57. =end
  58. =begin
  59. === Required argument option & argument conversion
  60. --- --x
  61. --- --y
  62.     When switch string contains '=', the option requires an argument.
  63.     Also, a (({Class})) given, the argument would be passed to the
  64.     block with converting to desired object((({Integer})) in the
  65.     case).
  66.     If no argument present or it doesn't match the class, an exception
  67.     will be caused.
  68.     
  69.     Convertible(as default) classes are:
  70.     * Object      arbitrary string(default class)
  71.     * String      non-empty string
  72.     * Integer      integral number
  73.     * Float      floating point number
  74.     * Numeric      Integer or Float
  75.     * TrueClass      boolean((({true})) if present)
  76.     * FalseClass  boolean((({false})) if present)
  77. =end
  78. =begin
  79. === Optional argument option
  80. --- -f
  81.     When argument spec is surrounded with (({[]})), the argument is
  82.     optional, that is, the option may take an argument or not.
  83. =end
  84. =begin
  85. === Argument conversion
  86. --- --geometry
  87.     When Regexp(object responds to (({match}))) passed to (({on})),
  88.     it is assigned as the pattern the argument must match to it.
  89.     
  90.     The argument string to the option is passed to (({match})), and
  91.     the result (({nil})) or (({false})) causes invalid argument
  92.     exception.
  93.     
  94.     The result of (({match})) passed to the block with converted to array.
  95.     Typically, using Regexp, you want to refer substrings within the block,
  96.     note that they're passed as strings and shoud be converted.
  97. =end
  98. =begin alternative
  99.     You can reparse the separated strings by the OptionParser object.
  100.       q.on('--geometry=GEOM', 'geometry XxY', /(\d+)x(\d+)/) {|geom, x, y|
  101.         q.parse('--x', x, '--y', y)
  102.       }
  103.     or
  104.       q.on('--geometry=GEOM', 'geometry XxY', /(\d+)x(\d+)/) {|geom, x, y|
  105.         ARGV[0, 0] = ['--x', x, '--y', y]
  106.       }
  107.     This provides the way to make an option equivalent to some options.
  108. =end
  109. =begin
  110. == Parse
  111. Here, command line arguments, ARGV, are parsed.
  112. =end
  113. =begin
  114. == Check for options
  115. Checking whether minimal options specified, and since the expression
  116. is the last one of the block, this results ARGV.options.
  117.  
  118. Otherwise, you may want to abort with message when number of
  119. none-option argument is not correct, use
  120.   ARGV.empty?
  121. or
  122.   ARGV.size == 2
  123.  
  124. ((-You can check illegal combination of options in each handlers.-))
  125. =end
  126. =begin
  127. Aborting here with help message, if any errors occurred while parsing or mandatory option is missing.
  128.  
  129. Note that the script does ((*NOT*)) abort when (({parse!}))d within ARGV.options block,
  130. just error message would be displayed.
  131. =end
  132. =begin
  133. == Miscellaneous
  134. Showing the result of parsing.
  135. =end
  136.