optparse 0.3.1 → 0.5.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -1,10 +1,10 @@
1
1
  == Tutorial
2
2
 
3
- === Why \OptionParser?
3
+ === Why +OptionParser+?
4
4
 
5
5
  When a Ruby program executes, it captures its command-line arguments
6
6
  and options into variable ARGV.
7
- This simple program just prints its \ARGV:
7
+ This simple program just prints its +ARGV+:
8
8
 
9
9
  :include: ruby/argv.rb
10
10
 
@@ -18,7 +18,7 @@ the command-line options.
18
18
 
19
19
  OptionParser offers methods for parsing and handling those options.
20
20
 
21
- With \OptionParser, you can define options so that for each option:
21
+ With +OptionParser+, you can define options so that for each option:
22
22
 
23
23
  - The code that defines the option and code that handles that option
24
24
  are in the same place.
@@ -55,7 +55,7 @@ The class also has method #help, which displays automatically-generated help tex
55
55
  - {Argument Converters}[#label-Argument+Converters]
56
56
  - {Help}[#label-Help]
57
57
  - {Top List and Base List}[#label-Top+List+and+Base+List]
58
- - {Defining Options}[#label-Defining+Options]
58
+ - {Methods for Defining Options}[#label-Methods+for+Defining+Options]
59
59
  - {Parsing}[#label-Parsing]
60
60
  - {Method parse!}[#label-Method+parse-21]
61
61
  - {Method parse}[#label-Method+parse]
@@ -66,10 +66,10 @@ The class also has method #help, which displays automatically-generated help tex
66
66
 
67
67
  === To Begin With
68
68
 
69
- To use \OptionParser:
69
+ To use +OptionParser+:
70
70
 
71
- 1. Require the \OptionParser code.
72
- 2. Create an \OptionParser object.
71
+ 1. Require the +OptionParser+ code.
72
+ 2. Create an +OptionParser+ object.
73
73
  3. Define one or more options.
74
74
  4. Parse the command line.
75
75
 
@@ -92,9 +92,9 @@ the block defined for the option is called with the argument value.
92
92
  An invalid option raises an exception.
93
93
 
94
94
  Method #parse!, which is used most often in this tutorial,
95
- removes from \ARGV the options and arguments it finds,
95
+ removes from +ARGV+ the options and arguments it finds,
96
96
  leaving other non-option arguments for the program to handle on its own.
97
- The method returns the possibly-reduced \ARGV array.
97
+ The method returns the possibly-reduced +ARGV+ array.
98
98
 
99
99
  Executions:
100
100
 
@@ -115,7 +115,7 @@ Executions:
115
115
 
116
116
  === Defining Options
117
117
 
118
- A common way to define an option in \OptionParser
118
+ A common way to define an option in +OptionParser+
119
119
  is with instance method OptionParser#on.
120
120
 
121
121
  The method may be called with any number of arguments
@@ -351,6 +351,29 @@ Executions:
351
351
 
352
352
  Omitting an optional argument does not raise an error.
353
353
 
354
+ ==== Argument Abbreviations
355
+
356
+ Specify an argument list as an Array or a Hash.
357
+
358
+ :include: ruby/argument_abbreviation.rb
359
+
360
+ When an argument is abbreviated, the expanded argument yielded.
361
+
362
+ Executions:
363
+
364
+ $ ruby argument_abbreviation.rb --help
365
+ Usage: argument_abbreviation [options]
366
+ Usage: argument_abbreviation [options]
367
+ -x, --xxx=VALUE Argument abbreviations
368
+ -y, --yyy=VALUE Argument abbreviations
369
+ $ ruby argument_abbreviation.rb --xxx A
370
+ ["--xxx", "ABC"]
371
+ $ ruby argument_abbreviation.rb --xxx c
372
+ argument_abbreviation.rb:9:in `<main>': invalid argument: --xxx c (OptionParser::InvalidArgument)
373
+ $ ruby argument_abbreviation.rb --yyy a --yyy d
374
+ ["--yyy", "XYZ"]
375
+ ["--yyy", "FOO"]
376
+
354
377
  === Argument Values
355
378
 
356
379
  Permissible argument values may be restricted
@@ -522,11 +545,11 @@ Executions:
522
545
  === Argument Converters
523
546
 
524
547
  An option can specify that its argument is to be converted
525
- from the default \String to an instance of another class.
548
+ from the default +String+ to an instance of another class.
526
549
  There are a number of built-in converters.
527
550
 
528
551
  Example: File +date.rb+
529
- defines an option whose argument is to be converted to a \Date object.
552
+ defines an option whose argument is to be converted to a +Date+ object.
530
553
  The argument is converted by method Date#parse.
531
554
 
532
555
  :include: ruby/date.rb
@@ -546,7 +569,7 @@ for both built-in and custom converters.
546
569
 
547
570
  === Help
548
571
 
549
- \OptionParser makes automatically generated help text available.
572
+ +OptionParser+ makes automatically generated help text available.
550
573
 
551
574
  The help text consists of:
552
575
 
@@ -614,49 +637,49 @@ Execution:
614
637
 
615
638
  === Top List and Base List
616
639
 
617
- An \OptionParser object maintains a stack of \OptionParser::List objects,
640
+ An +OptionParser+ object maintains a stack of OptionParser::List objects,
618
641
  each of which has a collection of zero or more options.
619
642
  It is unlikely that you'll need to add or take away from that stack.
620
643
 
621
644
  The stack includes:
622
645
 
623
- - The <em>top list</em>, given by \OptionParser#top.
624
- - The <em>base list</em>, given by \OptionParser#base.
646
+ - The <em>top list</em>, given by OptionParser#top.
647
+ - The <em>base list</em>, given by OptionParser#base.
625
648
 
626
- When \OptionParser builds its help text, the options in the top list
649
+ When +OptionParser+ builds its help text, the options in the top list
627
650
  precede those in the base list.
628
651
 
629
- === Defining Options
652
+ === Methods for Defining Options
630
653
 
631
654
  Option-defining methods allow you to create an option, and also append/prepend it
632
655
  to the top list or append it to the base list.
633
656
 
634
657
  Each of these next three methods accepts a sequence of parameter arguments and a block,
635
- creates an option object using method \Option#make_switch (see below),
658
+ creates an option object using method OptionParser#make_switch (see below),
636
659
  and returns the created option:
637
660
 
638
- - \Method \OptionParser#define appends the created option to the top list.
661
+ - \Method OptionParser#define appends the created option to the top list.
639
662
 
640
- - \Method \OptionParser#define_head prepends the created option to the top list.
663
+ - \Method OptionParser#define_head prepends the created option to the top list.
641
664
 
642
- - \Method \OptionParser#define_tail appends the created option to the base list.
665
+ - \Method OptionParser#define_tail appends the created option to the base list.
643
666
 
644
667
  These next three methods are identical to the three above,
645
668
  except for their return values:
646
669
 
647
- - \Method \OptionParser#on is identical to method \OptionParser#define,
670
+ - \Method OptionParser#on is identical to method OptionParser#define,
648
671
  except that it returns the parser object +self+.
649
672
 
650
- - \Method \OptionParser#on_head is identical to method \OptionParser#define_head,
673
+ - \Method OptionParser#on_head is identical to method OptionParser#define_head,
651
674
  except that it returns the parser object +self+.
652
675
 
653
- - \Method \OptionParser#on_tail is identical to method \OptionParser#define_tail,
676
+ - \Method OptionParser#on_tail is identical to method OptionParser#define_tail,
654
677
  except that it returns the parser object +self+.
655
678
 
656
679
  Though you may never need to call it directly,
657
680
  here's the core method for defining an option:
658
681
 
659
- - \Method \OptionParser#make_switch accepts an array of parameters and a block.
682
+ - \Method OptionParser#make_switch accepts an array of parameters and a block.
660
683
  See {Parameters for New Options}[optparse/option_params.rdoc].
661
684
  This method is unlike others here in that it:
662
685
  - Accepts an <em>array of parameters</em>;
@@ -668,7 +691,7 @@ here's the core method for defining an option:
668
691
 
669
692
  === Parsing
670
693
 
671
- \OptionParser has six instance methods for parsing.
694
+ +OptionParser+ has six instance methods for parsing.
672
695
 
673
696
  Three have names ending with a "bang" (<tt>!</tt>):
674
697
 
@@ -699,9 +722,9 @@ Each of these methods:
699
722
  (see {Keyword Argument into}[#label-Keyword+Argument+into]).
700
723
  - Returns +argv+, possibly with some elements removed.
701
724
 
702
- ==== \Method parse!
725
+ ==== \Method +parse!+
703
726
 
704
- \Method parse!:
727
+ \Method +parse!+:
705
728
 
706
729
  - Accepts an optional array of string arguments +argv+;
707
730
  if not given, +argv+ defaults to the value of OptionParser#default_argv,
@@ -756,9 +779,9 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
756
779
  ["--xxx", true]
757
780
  Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
758
781
 
759
- ==== \Method parse
782
+ ==== \Method +parse+
760
783
 
761
- \Method parse:
784
+ \Method +parse+:
762
785
 
763
786
  - Accepts an array of string arguments
764
787
  _or_ zero or more string arguments.
@@ -810,25 +833,25 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
810
833
  ["--xxx", true]
811
834
  Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
812
835
 
813
- ==== \Method order!
836
+ ==== \Method +order!+
814
837
 
815
838
  Calling method OptionParser#order! gives exactly the same result as
816
839
  calling method OptionParser#parse! with environment variable
817
840
  +POSIXLY_CORRECT+ defined.
818
841
 
819
- ==== \Method order
842
+ ==== \Method +order+
820
843
 
821
844
  Calling method OptionParser#order gives exactly the same result as
822
845
  calling method OptionParser#parse with environment variable
823
846
  +POSIXLY_CORRECT+ defined.
824
847
 
825
- ==== \Method permute!
848
+ ==== \Method +permute!+
826
849
 
827
850
  Calling method OptionParser#permute! gives exactly the same result as
828
851
  calling method OptionParser#parse! with environment variable
829
852
  +POSIXLY_CORRECT+ _not_ defined.
830
853
 
831
- ==== \Method permute
854
+ ==== \Method +permute+
832
855
 
833
856
  Calling method OptionParser#permute gives exactly the same result as
834
857
  calling method OptionParser#parse with environment variable
data/lib/optparse/ac.rb CHANGED
@@ -1,7 +1,11 @@
1
1
  # frozen_string_literal: false
2
2
  require_relative '../optparse'
3
3
 
4
+ #
5
+ # autoconf-like options.
6
+ #
4
7
  class OptionParser::AC < OptionParser
8
+ # :stopdoc:
5
9
  private
6
10
 
7
11
  def _check_ac_args(name, block)
@@ -14,6 +18,7 @@ class OptionParser::AC < OptionParser
14
18
  end
15
19
 
16
20
  ARG_CONV = proc {|val| val.nil? ? true : val}
21
+ private_constant :ARG_CONV
17
22
 
18
23
  def _ac_arg_enable(prefix, name, help_string, block)
19
24
  _check_ac_args(name, block)
@@ -29,16 +34,27 @@ class OptionParser::AC < OptionParser
29
34
  enable
30
35
  end
31
36
 
37
+ # :startdoc:
38
+
32
39
  public
33
40
 
41
+ # Define <tt>--enable</tt> / <tt>--disable</tt> style option
42
+ #
43
+ # Appears as <tt>--enable-<i>name</i></tt> in help message.
34
44
  def ac_arg_enable(name, help_string, &block)
35
45
  _ac_arg_enable("enable", name, help_string, block)
36
46
  end
37
47
 
48
+ # Define <tt>--enable</tt> / <tt>--disable</tt> style option
49
+ #
50
+ # Appears as <tt>--disable-<i>name</i></tt> in help message.
38
51
  def ac_arg_disable(name, help_string, &block)
39
52
  _ac_arg_enable("disable", name, help_string, block)
40
53
  end
41
54
 
55
+ # Define <tt>--with</tt> / <tt>--without</tt> style option
56
+ #
57
+ # Appears as <tt>--with-<i>name</i></tt> in help message.
42
58
  def ac_arg_with(name, help_string, &block)
43
59
  _check_ac_args(name, block)
44
60
 
@@ -7,12 +7,17 @@ class OptionParser
7
7
  #
8
8
  # :include: ../../doc/optparse/creates_option.rdoc
9
9
  #
10
- def define_by_keywords(options, meth, **opts)
11
- meth.parameters.each do |type, name|
10
+ # Defines options which set in to _options_ for keyword parameters
11
+ # of _method_.
12
+ #
13
+ # Parameters for each keywords are given as elements of _params_.
14
+ #
15
+ def define_by_keywords(options, method, **params)
16
+ method.parameters.each do |type, name|
12
17
  case type
13
18
  when :key, :keyreq
14
19
  op, cl = *(type == :key ? %w"[ ]" : ["", ""])
15
- define("--#{name}=#{op}#{name.upcase}#{cl}", *opts[name]) do |o|
20
+ define("--#{name}=#{op}#{name.upcase}#{cl}", *params[name]) do |o|
16
21
  options[name] = o
17
22
  end
18
23
  end
@@ -2,6 +2,11 @@
2
2
  # OptionParser internal utility
3
3
 
4
4
  class << OptionParser
5
+ #
6
+ # Shows version string in packages if Version is defined.
7
+ #
8
+ # +pkgs+:: package list
9
+ #
5
10
  def show_version(*pkgs)
6
11
  progname = ARGV.options.program_name
7
12
  result = false
@@ -47,6 +52,8 @@ class << OptionParser
47
52
  result
48
53
  end
49
54
 
55
+ # :stopdoc:
56
+
50
57
  def each_const(path, base = ::Object)
51
58
  path.split(/::|\//).inject(base) do |klass, name|
52
59
  raise NameError, path unless Module === klass
@@ -68,4 +75,6 @@ class << OptionParser
68
75
  end
69
76
  end
70
77
  end
78
+
79
+ # :startdoc:
71
80
  end