Class: LibCLImate::Climate
- Inherits:
-
Object
- Object
- LibCLImate::Climate
- Includes:
- Xqsr3::Quality::ParameterChecking
- Defined in:
- lib/libclimate/climate.rb
Overview
Class used to gather together the CLI specification, and execute it
The standard usage pattern is as follows:
PROGRAM_VERSION = [ 0, 1, 2 ]
= {}
climate = LibCLImate::Climate.new do |cl|
cl.add_flag('--verbose', alias: '-v', help: 'Makes program output verbose') { [:verbose] = true }
cl.add_option('--flavour', alias: '-f', help: 'Specifies the flavour') do |o, sp|
[:flavour] = check_flavour(o.value) or cl.abort "Invalid flavour '#{o.value}'; use --help for usage"
end
cl.usage_values = '<value-1> [ ... <value-N> ]'
cl.constrain_values = 1..100000
cl.info_lines = [
'ACME CLI program (using libCLImate)',
:version,
'An example program',
]
end
Defined Under Namespace
Modules: Climate_Constants_ Classes: ParseResults
Instance Attribute Summary collapse
-
#constrain_values ⇒ Object
(Integer, Range) Optional constraint on the values that must be provided to the program.
-
#exit_on_missing ⇒ Object
(boolean) Indicates whether exit will be called (with non-zero exit code) when a required command-line option is missing.
-
#exit_on_unknown ⇒ Object
(boolean) Indicates whether exit will be called (with non-zero exit code) when an unknown command-line flag or option is encountered.
-
#exit_on_usage ⇒ Object
(boolean) Indicates whether exit will be called (with zero exit code) when usage/version is requested on the command-line.
-
#flags_and_options ⇒ Object
(String) Optional string to describe the flags and options section.
-
#ignore_unknown ⇒ Object
(boolean) Indicates whether unknown flags or options will be ignored.
-
#info_lines ⇒ Object
([String]) Optional array of string of program-information that will be written before the rest of the usage block when usage is requested on the command-line.
-
#program_name ⇒ Object
(String) A program name; defaults to the name of the executing script.
-
#specifications ⇒ Object
readonly
([CLASP::Specification]) An array of specifications attached to the climate instance, whose contents should be modified by adding (or removing) CLASP specifications.
-
#stderr ⇒ ::IO
The output stream for contingent output; defaults to $stderr.
-
#stdout ⇒ ::IO
The output stream for normative output; defaults to $stdout.
-
#usage_help_suffix ⇒ Object
(String) The string that is appended to #abort calls made during #run.
-
#usage_values ⇒ ::String
Optional string to describe the program values, eg <xyz “[ { <<directory> | <file> } ]”.
-
#value_names ⇒ Object
([String]) Zero-based array of names for values to be used when that value is not present (according to the
:constrain_values
attribute). -
#version ⇒ Object
(String, [String], [Integer]) A version string or an array of integers/strings representing the version component(s).
Class Method Summary collapse
-
.load(source, options = (options_defaulted_ = {}), &blk) ⇒ Object
Loads an instance of the class, as specified by
source
, according to the given parameters.
Instance Method Summary collapse
-
#abort(message, options = {}) ⇒ Object
Calls abort() with the given message prefixed by the program_name.
-
#add_alias(name_or_specification, *aliases) ⇒ Object
Adds an alias to
specifications
. -
#add_flag(name_or_flag, options = {}, &blk) ⇒ Object
Adds a flag to
specifications
. -
#add_option(name_or_option, options = {}, &blk) ⇒ Object
Adds an option to
specifications
. -
#aliases ⇒ Object
- DEPRECATED
-
Instead, use
specifications
.
- #check_required_options_(specifications, options, missing, raise_on_required) ⇒ Object
- #check_value_constraints_(values) ⇒ Object
-
#initialize(options = {}) {|_self| ... } ⇒ Climate
constructor
Creates an instance of the Climate class.
-
#on_flag(name_or_flag, options = {}, &blk) ⇒ Object
Attaches a block to an already-registered flag.
-
#on_option(name_or_option, options = {}, &blk) ⇒ Object
Attaches a block to an already-registered option.
-
#parse(argv = ARGV) ⇒ Object
Parse the given command-line (passed as
argv
) by the given instance. -
#parse_and_verify(argv = ARGV, **options) ⇒ Object
Parse the given command-line (passed as
argv
) by the given instance, and verifies it. -
#run(argv = ARGV) ⇒ Object
- DEPRECATED
-
Use Climate#parse_and_verify() (but be aware that the returned result is of a different type.
-
#set_program_name(name) ⇒ Object
- DEPRECATED
-
This method is now deprecated.
Constructor Details
#initialize(options = {}) {|_self| ... } ⇒ Climate
Creates an instance of the Climate class.
Signature
-
Parameters:
-
options:
(Hash) An options hash, containing any of the following options.
-
-
Options:
-
:no_help_flag
(boolean) Prevents the use of theCLASP::Flag.Help
flag-specification -
:no_version_flag
(boolean) Prevents the use of theCLASP::Flag.Version
flag-specification -
:program_name
(::String) An explicit program-name, which is inferred from $0 if this isnil
-
:version
(String, [Integer], [String]) A version specification. If not specified, this is inferred -
:version_context
Object or class that defines a context for searching the version. Ignored if:version
is specified
-
-
Block An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 |
# File 'lib/libclimate/climate.rb', line 796 def initialize(={}, &blk) # :yields: climate check_parameter , 'options', allow_nil: true, type: ::Hash ||= {} check_option , :no_help_flag, type: :boolean, allow_nil: true check_option , :no_version_flag, type: :boolean, allow_nil: true check_option , :program_name, type: ::String, allow_nil: true pr_name = [:program_name] unless pr_name pr_name = File.basename($0) pr_name = (pr_name =~ /\.(?:bat|cmd|rb|sh)$/) ? "#$`(#$&)" : pr_name end given_specs = [Climate_Constants_::GIVEN_SPECS_] @specifications = [] @ignore_unknown = false @exit_on_unknown = true @exit_on_missing = true @exit_on_usage = true @info_lines = nil set_program_name pr_name @stdout = $stdout @stderr = $stderr @constrain_values = nil @flags_and_options = @usage_help_suffix = 'use --help for usage' @usage_values = usage_values @value_names = [] version_context = [:version_context] @version = [:version] || infer_version_(version_context) unless [:no_help_flag] f = CLASP::Flag.Help() unless f.respond_to?(:action) class << f attr_accessor :action end end f.action = Proc.new { show_usage_ } @specifications << f end unless [:no_version_flag] f = CLASP::Flag.Version() unless f.respond_to?(:action) class << f attr_accessor :action end end f.action = Proc.new { show_version_ } @specifications << f end @specifications = @specifications + given_specs if given_specs yield self if block_given? end |
Instance Attribute Details
#constrain_values ⇒ Object
(Integer, Range) Optional constraint on the values that must be provided to the program
911 912 913 |
# File 'lib/libclimate/climate.rb', line 911 def constrain_values @constrain_values end |
#exit_on_missing ⇒ Object
(boolean) Indicates whether exit will be called (with non-zero exit code) when a required command-line option is missing. Defaults to true
883 884 885 |
# File 'lib/libclimate/climate.rb', line 883 def exit_on_missing @exit_on_missing end |
#exit_on_unknown ⇒ Object
(boolean) Indicates whether exit will be called (with non-zero exit code) when an unknown command-line flag or option is encountered. Defaults to true
887 888 889 |
# File 'lib/libclimate/climate.rb', line 887 def exit_on_unknown @exit_on_unknown end |
#exit_on_usage ⇒ Object
(boolean) Indicates whether exit will be called (with zero exit code) when usage/version is requested on the command-line. Defaults to true
889 890 891 |
# File 'lib/libclimate/climate.rb', line 889 def exit_on_usage @exit_on_usage end |
#flags_and_options ⇒ Object
(String) Optional string to describe the flags and options section. Defaults to “[ ...
flags
and
options
...
]”
913 914 915 |
# File 'lib/libclimate/climate.rb', line 913 def @flags_and_options end |
#ignore_unknown ⇒ Object
(boolean) Indicates whether unknown flags or options will be ignored. This overrides :exit_on_unknown
. Defaults to false
885 886 887 |
# File 'lib/libclimate/climate.rb', line 885 def ignore_unknown @ignore_unknown end |
#info_lines ⇒ Object
([String]) Optional array of string of program-information that will be written before the rest of the usage block when usage is requested on the command-line
891 892 893 |
# File 'lib/libclimate/climate.rb', line 891 def info_lines @info_lines end |
#program_name ⇒ Object
(String) A program name; defaults to the name of the executing script
893 894 895 896 897 898 899 900 901 902 903 |
# File 'lib/libclimate/climate.rb', line 893 def program_name name = @program_name if defined?(Colcon) && @stdout.tty? name = "#{::Colcon::Decorations::Bold}#{name}#{::Colcon::Decorations::Unbold}" end name end |
#specifications ⇒ Object (readonly)
([CLASP::Specification]) An array of specifications attached to the climate instance, whose contents should be modified by adding (or removing) CLASP specifications
879 880 881 |
# File 'lib/libclimate/climate.rb', line 879 def specifications @specifications end |
#stderr ⇒ ::IO
Returns The output stream for contingent output; defaults to $stderr.
909 910 911 |
# File 'lib/libclimate/climate.rb', line 909 def stderr @stderr end |
#stdout ⇒ ::IO
Returns The output stream for normative output; defaults to $stdout.
907 908 909 |
# File 'lib/libclimate/climate.rb', line 907 def stdout @stdout end |
#usage_help_suffix ⇒ Object
(String) The string that is appended to #abort calls made during #run. Defaults to “use –help for usage”
915 916 917 |
# File 'lib/libclimate/climate.rb', line 915 def usage_help_suffix @usage_help_suffix end |
#usage_values ⇒ ::String
Returns Optional string to describe the program values, eg <xyz “[ { <<directory> | <file> } ]”.
917 918 919 |
# File 'lib/libclimate/climate.rb', line 917 def usage_values @usage_values end |
#value_names ⇒ Object
([String]) Zero-based array of names for values to be used when that value is not present (according to the :constrain_values
attribute)
919 920 921 |
# File 'lib/libclimate/climate.rb', line 919 def value_names @value_names end |
#version ⇒ Object
(String, [String], [Integer]) A version string or an array of integers/strings representing the version component(s)
921 922 923 |
# File 'lib/libclimate/climate.rb', line 921 def version @version end |
Class Method Details
.load(source, options = (options_defaulted_ = {}), &blk) ⇒ Object
Loads an instance of the class, as specified by source
, according to the given parameters
Signature
-
Parameters:
source
-
(
Hash
,IO
) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
options
-
An options hash, containing any of the following options
-
Options:
-
:no_help_flag
(boolean) Prevents the use of theCLASP::Flag.Help
flag-specification -
:no_version_flag
(boolean) Prevents the use of theCLASP::Flag.Version
flag-specification -
:program_name
(::String) An explicit program-name, which is inferred from $0 if this isnil
-
:version
(String, [Integer], [String]) A version specification. If not specified, this is inferred -
:version_context
Object or class that defines a context for searching the version. Ignored if:version
is specified
-
-
Block An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 |
# File 'lib/libclimate/climate.rb', line 723 def self.load(source, = ( = {}), &blk) # :yields: climate check_parameter , 'options', allow_nil: true, type: ::Hash ||= {} h = nil case source when ::IO h = YAML.load source.read when ::Hash h = source else if source.respond_to?(:to_hash) h = source.to_hash else raise TypeError, "#{self}.#{__method__}() 'source' argument must be a #{::Hash}, or an object implementing #{::IO}, or a type implementing 'to_hash'" end end _libclimate = require_element_(h, Hash, 'libclimate', nil) _exit_on_missing = lookup_element_(_libclimate, :boolean, 'exit_on_missing', 'libclimate') _ignore_unknown = lookup_element_(_libclimate, :boolean, 'ignore_unknown', 'libclimate') _exit_on_unknown = lookup_element_(_libclimate, :boolean, 'exit_on_unknown', 'libclimate') _exit_on_usage = lookup_element_(_libclimate, :boolean, 'exit_on_usage', 'libclimate') _info_lines = lookup_element_(_libclimate, Array, 'info_lines', 'libclimate') _program_name = lookup_element_(_libclimate, String, 'program_name', 'libclimate') _constrain_values = lookup_element_(_libclimate, [ Integer, Range ], 'constrain_values', 'libclimate') = lookup_element_(_libclimate, String, 'flags_and_options', 'libclimate') _usage_values = lookup_element_(_libclimate, String, 'usage_values', 'libclimate') _value_names = lookup_element_(_libclimate, Array, 'value_names', 'libclimate') _version = lookup_element_(_libclimate, [ String, [] ], 'version', 'libclimate') specs = CLASP::Arguments.load_specifications _libclimate, cl = Climate.new(.merge(Climate_Constants_::GIVEN_SPECS_ => specs), &blk) cl.exit_on_missing = _exit_on_missing unless _exit_on_missing.nil? cl.ignore_unknown = _ignore_unknown unless _ignore_unknown.nil? cl.exit_on_unknown = _exit_on_unknown unless _exit_on_unknown.nil? cl.exit_on_usage = _exit_on_usage unless _exit_on_usage.nil? cl.info_lines = _info_lines unless _info_lines.nil? cl.program_name = _program_name unless _program_name.nil? cl.constrain_values = _constrain_values unless _constrain_values.nil? cl. = unless .nil? cl.usage_values = _usage_values unless _usage_values.nil? cl.value_names = _value_names unless _value_names.nil? cl.version = _version unless _version.nil? cl end |
Instance Method Details
#abort(message, options = {}) ⇒ Object
Calls abort() with the given message prefixed by the program_name
Signature
-
Parameters:
-
message
(String) The message string -
options
(Hash) An option hash, containing any of the following options
-
-
Options:
-
:stream
optional The output stream to use. Defaults to the value of the attributestderr
-
:program_name
(String) optional Uses the given value rather than theprogram_name
attribute; does not prefix if the empty string -
:exit
optional The exit code. Defaults to 1. Does not exit ifnil
specified explicitly
-
Returns
The combined message string, if exit()
not called.
1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 |
# File 'lib/libclimate/climate.rb', line 1176 def abort(, ={}) prog_name = [:program_name] prog_name ||= program_name prog_name ||= '' stream = [:stream] stream ||= stderr stream ||= $stderr exit_code = .has_key?(:exit) ? [:exit] : 1 if prog_name.empty? msg = else msg = "#{prog_name}: #{}" end stream.puts msg exit(exit_code) if exit_code msg end |
#add_alias(name_or_specification, *aliases) ⇒ Object
Adds an alias to specifications
Signature
-
Parameters:
-
name_or_specification
(String) The flag/option name or the valued option -
aliases
(*[String]) One or more aliases
-
Examples
Specification(s) of a flag (single statement)
climate.add_flag('--mark-missing', alias: '-x')
climate.add_flag('--absolute-path', aliases: [ '-abs', '-p' ])
Specification(s) of a flag (multiple statements)
climate.add_flag('--mark-missing')
climate.add_alias('--mark-missing', '-x')
climate.add_flag('--absolute-path')
climate.add_alias('--absolute-path', '-abs', '-p')
Specification(s) of an option (single statement)
climate.add_option('--add-patterns', alias: '-p')
Specification(s) of an option (multiple statements)
climate.add_option('--add-patterns')
climate.add_alias('--add-patterns', '-p')
Specification of a valued option (which has to be multiple statements)
climate.add_option('--verbosity', values: [ 'succinct', 'verbose' ])
climate.add_alias('--verbosity=succinct', '-s')
climate.add_alias('--verbosity=verbose', '-v')
1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 |
# File 'lib/libclimate/climate.rb', line 1305 def add_alias(name_or_specification, *aliases) check_parameter name_or_specification, 'name_or_specification', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification, ::CLASP::OptionSpecification ] raise ArgumentError, "must supply at least one alias" if aliases.empty? case name_or_specification when ::CLASP::FlagSpecification self.specifications << name_or_specification when ::CLASP::OptionSpecification self.specifications << name_or_specification else self.specifications << CLASP.Alias(name_or_specification, aliases: aliases) end end |
#add_flag(name_or_flag, options = {}, &blk) ⇒ Object
Adds a flag to specifications
Signature
-
Parameters:
-
name_or_flag
(String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification -
options
(Hash) An options hash, containing any of the following options
-
-
Options:
-
:alias
(String) A single alias -
:aliases
([String]) An array of aliases -
:help
(String) Description string used when writing response to “--help
” flag -
:required
(boolean) Indicates whether the flag is required, causing #run to fail with appropriate message if the flag is not specified in the command-line arguments
-
-
Block An optional block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
Examples
Specification(s) of a flag (single statement)
1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 |
# File 'lib/libclimate/climate.rb', line 1224 def add_flag(name_or_flag, ={}, &blk) check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ] if ::CLASP::FlagSpecification === name_or_flag specifications << name_or_flag else specifications << CLASP.Flag(name_or_flag, **, &blk) end end |
#add_option(name_or_option, options = {}, &blk) ⇒ Object
Adds an option to specifications
Signature
-
Parameters:
-
name_or_option
(String, CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification -
options
(Hash) An options hash, containing any of the following options
-
-
Options:
-
:alias
(String) A single alias -
:aliases
([String]) An array of aliases -
:help
(String) Description string used when writing response to “--help
” flag -
:values_range
([String]) An array of strings representing the valid/expected values used when writing response to “--help
” flag. NOTE: the current version does not validate against these values, but a future version may do so -
:default_value
(String) The default version used when, say, for the option--my-opt
the command-line contain the argument “--my-opt=
”
-
-
Block An optional block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 |
# File 'lib/libclimate/climate.rb', line 1254 def add_option(name_or_option, ={}, &blk) check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ] if ::CLASP::OptionSpecification === name_or_option specifications << name_or_option else specifications << CLASP.Option(name_or_option, **, &blk) end end |
#aliases ⇒ Object
- DEPRECATED
-
Instead, use
specifications
881 |
# File 'lib/libclimate/climate.rb', line 881 def aliases; specifications; end |
#check_required_options_(specifications, options, missing, raise_on_required) ⇒ Object
567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 |
# File 'lib/libclimate/climate.rb', line 567 def (specifications, , missing, raise_on_required) required_specifications = specifications.select do |sp| sp.kind_of?(::CLASP::OptionSpecification) && sp.required? end required_specifications = Hash[required_specifications.map { |sp| [ sp.name, sp ] }] = Hash[.map { |o| [ o.name, o ]}] required_specifications.each do |k, sp| unless .has_key? k = sp. if false ; elsif raise_on_required if raise_on_required.is_a?(Class) raise raise_on_required, else raise RuntimeError, end elsif exit_on_missing self.abort else if program_name && !program_name.empty? = "#{program_name}: #{}" end stderr.puts end missing << sp #results[:missing_option_aliases] << sp end end end |
#check_value_constraints_(values) ⇒ Object
615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 |
# File 'lib/libclimate/climate.rb', line 615 def check_value_constraints_(values) # now police the values values_constraint = constrain_values values_constraint = values_constraint.begin if ::Range === values_constraint && values_constraint.end == values_constraint.begin val_names = ::Array === value_names ? value_names : [] case values_constraint when nil ; when ::Array warn "value of 'constrain_values' attribute, if an #{::Array}, must not be empty and all elements must be of type #{::Integer}" if values_constraint.empty? || !values_constraint.all? { |v| ::Integer === v } unless values_constraint.include? values.size = ("wrong number of values: #{values.size} given, #{values_constraint} required") if exit_on_missing self.abort else if program_name && !program_name.empty? = "#{program_name}: #{}" end stderr.puts end end when ::Integer unless values.size == values_constraint if name = val_names[values.size] = (name + ' not specified') else = ("wrong number of values: #{values.size} given, #{values_constraint} required") end if exit_on_missing self.abort else if program_name && !program_name.empty? = "#{program_name}: #{}" end stderr.puts end end when ::Range unless values_constraint.include? values.size if name = val_names[values.size] = (name + ' not specified') else = ("wrong number of values: #{values.size} givens, #{values_constraint.begin} - #{values_constraint.end - (values_constraint.exclude_end? ? 1 : 0)} required") end if exit_on_missing self.abort else if program_name && !program_name.empty? = "#{program_name}: #{}" end stderr.puts end end else warn "value of 'constrain_values' attribute - '#{constrain_values}' (#{constrain_values.class}) - of wrong type : must be #{::Array}, #{::Integer}, #{::Range}, or nil" end end |
#on_flag(name_or_flag, options = {}, &blk) ⇒ Object
Attaches a block to an already-registered flag
Signature
-
Parameters:
-
name_or_flag
(String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification -
options
(Hash) An options hash, containing any of the following options. No options are recognised currently
-
-
Options:
-
Block A required block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 |
# File 'lib/libclimate/climate.rb', line 1335 def on_flag(name_or_flag, ={}, &blk) check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ] raise ArgumentError, "on_flag() requires a block to be given" unless block_given? specifications.each do |spec| case spec when CLASP::FlagSpecification if spec == name_or_flag spec.action = blk return true end end end warn "The Climate instance does not contain a FlagSpecification matching '#{name_or_flag}' (#{name_or_flag.class})" false end |
#on_option(name_or_option, options = {}, &blk) ⇒ Object
Attaches a block to an already-registered option
Signature
-
Parameters:
-
name_or_option
(String, ::CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification -
options
(Hash) An options hash, containing any of the following options. No options are recognised currently
-
-
Options:
-
Block A required block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 |
# File 'lib/libclimate/climate.rb', line 1372 def on_option(name_or_option, ={}, &blk) check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ] raise ArgumentError, "on_option() requires a block to be given" unless block_given? specifications.each do |spec| case spec when CLASP::OptionSpecification if spec == name_or_option spec.action = blk return true end end end warn "The Climate instance does not contain an OptionSpecification matching '#{name_or_option}' (#{name_or_option.class})" false end |
#parse(argv = ARGV) ⇒ Object
Parse the given command-line (passed as argv
) by the given instance
Signature
-
Parameters:
-
argv
([String]) The array of arguments; defaults toARGV
-
Returns
(ParseResults) Results
932 933 934 935 936 937 938 939 |
# File 'lib/libclimate/climate.rb', line 932 def parse(argv = ARGV) # :yields: ParseResults raise ArgumentError, "argv may not be nil" if argv.nil? arguments = CLASP::Arguments.new argv, specifications ParseResults.new(self, arguments, argv) end |
#parse_and_verify(argv = ARGV, **options) ⇒ Object
Parse the given command-line (passed as argv
) by the given instance, and verifies it
Signature
-
Parameters:
-
argv
([String]) The array of arguments; defaults toARGV
-
options
(Hash) Options
-
-
Options:
-
:raise_on_required
(boolean, Exception) Causes an/the given exception to be raised if any required options are not specified in the command-line -
:raise_on_unrecognised
(boolean, Exception) Causes an/the given exception to be raised if any unrecognised flags/options are specified in the command-line -
:raise_on_unused
(boolean, Exception) Causes an/the given exception to be raised if any given flags/options are not used -
:raise
(boolean, Exception) Causes an/the given exception to be raised in all conditions
-
Returns
(ParseResults) Results
958 959 960 961 962 963 964 965 |
# File 'lib/libclimate/climate.rb', line 958 def parse_and_verify(argv = ARGV, **) # :yields: ParseResults r = parse argv r.verify(**) r end |
#run(argv = ARGV) ⇒ Object
- DEPRECATED
-
Use Climate#parse_and_verify() (but be aware that the
returned result is of a different type
Signature
-
Parameters:
-
argv
([String]) The array of arguments; defaults toARGV
-
Returns
an instance of a type derived from ::Hash
with the additional attributes flags
, options
, values
, double_slash_index
and argv
.
979 980 981 982 983 984 985 986 |
# File 'lib/libclimate/climate.rb', line 979 def run(argv = ARGV) # :yields: customised +::Hash+ raise ArgumentError, "argv may not be nil" if argv.nil? arguments = CLASP::Arguments.new argv, specifications run_ argv, arguments end |
#set_program_name(name) ⇒ Object
- DEPRECATED
-
This method is now deprecated. Instead use
program_name=
873 874 875 876 |
# File 'lib/libclimate/climate.rb', line 873 def set_program_name(name) @program_name = name end |