Module: RakeCommander::Options::Arguments::ClassMethods

Includes:
Name
Defined in:
lib/rake-commander/options/arguments.rb

Constant Summary

Constants included from Name

Name::BOOLEAN_NAME_REGEX, Name::BOOLEAN_TOKEN, Name::DOUBLE_HYPHEN_REGEX, Name::HYPEN_REGEX, Name::HYPHEN_START_REGEX, Name::OPTIONAL_REGEX, Name::SINGLE_HYPHEN_REGEX, Name::UNDERSCORE_REGEX, Name::WORD_DELIMITER

Instance Method Summary collapse

Methods included from Name

#argument_optional?, #argument_required?, #boolean_name?, #capture_argument_with!, #capture_arguments_name!, #capture_arguments_short!, #double_hyphen?, #name_argument, #name_argument?, #name_hyphen, #name_sym, #name_word_sym, #short_hyphen, #short_sym, #single_hyphen?, #valid_name?, #valid_short?

Instance Method Details

#argv_cropping_for_rake(value = :not_used) ⇒ Boolean

Note:
  1. When true it will enable
    • A patch on Rake::Application, provided that ARGV is cropped before Rake identifies **tasks and rake native options. Note that this specific patch only works if rake commander was loaded BEFORE Rake::Application#run is invoked.
  2. When false, an implicit exit(0) is added at the end of a rake task defined via RakeCommander, as a work-around that prevents Rake from chaining option arguments as if they were actual tasks.
Note:
  1. This only refers to what comes after RAKE_COMMAND_EXTENDED_OPTIONS_START (--)

Configuration setting Whether the additional arguments (extended options) managed by this gem should be removed/consumed from ARGV before Rake processes option arguments.

Returns:

  • (Boolean) 


41
42
43
44
45
 
# File 'lib/rake-commander/options/arguments.rb', line 41

def argv_cropping_for_rake(value = :not_used)
  @argv_cropping_for_rake = true if @argv_cropping_for_rake.nil?
  return @argv_cropping_for_rake if value == :not_used
  @argv_cropping_for_rake = !!value
end

#argv_extended_options(argv = ARGV.dup) ⇒ Array<String>

Note:

please observe that Rake has it's own options. For this reason using a delimiter (RAKE_COMMAND_EXTENDED_OPTIONS_START) shows up to be necessary to create some sort of command line argument namespacing.

It returns the part of ARGV that are arguments of RakeCommander::Options parsing.

Parameters:

  • argv (Array<String>) (defaults to: ARGV.dup) —

    the command line arguments array.

Returns:

  • (Array<String>) —

    the target arguments to be parsed by RakeCommander::Options



53
54
55
56
57
58
59
 
# File 'lib/rake-commander/options/arguments.rb', line 53

def argv_extended_options(argv = ARGV.dup)
  if idx = argv.index(RAKE_COMMAND_EXTENDED_OPTIONS_START)
    argv[idx+1..-1]
  else
    []
  end
end

#argv_pre_parsed(argv = ARGV, options:) ⇒ Array<String>

Note:
  1. Any word or letter with hypen -`or _double hypen_--` is interpreted as option(s)
  2. To overcome this limitation, you may enclose in double quotes and argument with that start (i,e, "--argument").

Options with arguments should not take another option as value. OptionParser can do this even if the the argument is optional. This method re-arranges the arguments based on options that receive parameters, provided that an option is not taken as a value of a previous option that accepts arguments. If an option with argument is missing the argument, but has a default value, that default value will be inserted after the option in the array to prevent the OptionParser::MissingArgument error to stop the parsing process.

Examples:

1. `-abc ARGUMENT` where only `c` receives the argument becomes `-ab -c ARGUMENT`
3. `-abc ARGUMENT` where `b` and `c` are argument receivers becomes `-a -b nil -c ARGUMENT`
2. `-acb ARGUMENT` where only `c` receives the argument becomes `-a -c nil -b ARGUMENT`
4. `-c --some-option ARGUMENT` where both options receive argument, becomes `-c nil --some-option ARGUMENT`
5. `-c --some-option -d ARGUMENT` where both options receive argument, becomes `-c nil --some-option nil -d ARGUMENT`
6. `-cd ARGUMENT` where `c` default is `"yeah"`, becomes `-c yeah -d ARGUMENT`

Parameters:

  • argv (Array<String>) (defaults to: ARGV)
  • options (Hash) —

    the defined RakeCommander::Option to re-arrange argv with.

Returns:

  • (Array<String>) —

    the re-arranged argv



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/rake-commander/options/arguments.rb', line 107

def argv_pre_parsed(argv = ARGV, options:)
  pre_parsed = explicit_argument_options(argv, options)
  compact_short = ''
  pre_parsed.each_with_object([]) do |(opt_ref, args), out|
    next out.push(*args) unless opt_ref.is_a?(Symbol)
    is_short = opt_ref.to_s.length == 1
    next compact_short << opt_ref.to_s if is_short && args.empty?
    out.push("-#{compact_short}") unless compact_short.empty?
    compact_short = ''
    opt_str = is_short ? "-#{opt_ref}" : name_hyphen(opt_ref)
    out.push(opt_str, *args)
  end.tap do |out|
    out.push("-#{compact_short}") unless compact_short.empty?
  end
end

#argv_rake_native_arguments(argv = ARGV.dup) ⇒ Array<String>

Note:

this is necessary to prevent Rake to interpret them.

It slices from the original ARGV the extended_options of this gem.

Returns:

  • (Array<String>) —

    the argv without the extended options of this gem.



64
65
66
67
68
69
70
 
# File 'lib/rake-commander/options/arguments.rb', line 64

def argv_rake_native_arguments(argv = ARGV.dup)
  return argv unless argv_cropping_for_rake
  if idx = argv.index(RAKE_COMMAND_EXTENDED_OPTIONS_START)
    argv = argv[0..idx]
  end
  argv
end

#argv_with_enhanced_syntax?(argv = ARGV) ⇒ Boolean

Note:

it assumes ARGV has been left unaltered.

Returns whether enhanced parsing should be switched on or off.

Returns:

  • (Boolean) —

    whether enhanced parsing should be switched on or off.



21
22
23
24
 
# File 'lib/rake-commander/options/arguments.rb', line 21

def argv_with_enhanced_syntax?(argv = ARGV)
  return false unless argv.is_a?(Array)
  argv.include?(RAKE_COMMAND_EXTENDED_OPTIONS_START)
end

#parse_options(argv = ARGV, *args, **kargs, &block) ⇒ Object

Note:
  1. Without this ARGV cut, it will throw OptionParser::InvalidOption error
    • So some tidy up is necessary and the head of the command (i.e. rake some:task --) should be excluded from arguments to input to the options parser.

Re-open parse_options method, provided that we slice ARGV to only include the extended options of this gem, which start at RAKE_COMMAND_EXTENDED_OPTIONS_START.

See Also:

  • RakeCommander::Options::Arguments::ClassMethods.`RakeCommander`RakeCommander::Options`RakeCommander::Options#parse_options`


80
81
82
83
84
 
# File 'lib/rake-commander/options/arguments.rb', line 80

def parse_options(argv = ARGV, *args, **kargs, &block)
  argv = argv_extended_options(argv)
  argv = argv_pre_parsed(argv, options: options_hash(with_implicit: true))
  super(argv, *args, **kargs, &block)
end