2.3 Margs - Argument operation class

This class handles arguments at command line. The features are as follows.

Handle 2 types of argument format namely keyword=value and -keyword.
Convert Bool type (true/false) data using -keyword option.
Defined format of value could be in Ruby original String array, Fixnum array, Float array.
Provide file type and field name type for other special format.
Specify default value and value range.
Display error message if the specified argument is not correct.
When --help is specified, help() is called. User can also specify the function name of help. Note that --help is different than regular help option, and the prefix includes two minus sign.

2.3.1 Method

* MCMD::Margs.new(ARGV[,allKeyWords][,mandatoryKeyWords][,helpFunction)

Create Margs object. The arguments at the command line expressed in “keyword=value” or “-keyword” are set to Array or Hash variable within the class.



: ARGV - ARGV variable of Ruby.
: allKeyWords - Define argument keyword list by key=value or -key. Check the arguments other than the ones defined here is not defined at ARGV, if the argument is specified, the program will terminate with an error. Checking will not be carried out when allKeyWords is not defined.
: mandatoryKeyWords - Define argument keyword list by key=value. If the specified arguments is not specified at the command line, the program terminates with an error. Checking will not be carried out when mandatoryKeyWords is not defined.
: helpFunction - Function name to call when --help is specified.

# Command line
$ ruby test.rb i=dat.csv -abc

# Contents of test.rb
args=Margs.new(ARGV, "i=,v=,-abc") # OK
args=Margs.new(ARGV, "i=,v=") # -abc cannot be specified and it is terminated with error
args=Margs.new(ARGV, "i=,v=,-abc","i=,v=") # v= is required but is not specified, 
thus it is terminated with error

* MCMD::Margs.file(keyWord,mode): Obtain file name



: keyWord - Keyword in key=format (String)
: mode - Specify "r"(check readable) or "w"(check writable)(String)

The value specified at keyWord is the input filename, when mode is set as "r", the method returns the file name if the file is readable. Otherwise, if the file cannot be read, it terminates with an error. When mode is set as "w", check whether the directory is writable, and return filename if it is writable, otherwise, terminate with error if not writable.

# Command line
$ ruby test.rb i=dat.csv

# Contents of test.rb
args=Margs.new(ARGV)
puts args.file("i=","r") # dat.csv becomes "dat.csv" if it is readable
puts args.file("i=","w") # current directory is "dat.csv" if it is writable

* MCMD::Margs.field(keyWord,fileName)

Return various information in the file (specified at fileName) related to the field names specified at keyWord.



: keyWord - Keyword in "key=" format (String).
: fileName - File name.

The specified field name at the command line must follow the format below.

$\begin{equation} \verb/key=/name_1\verb/[:/newName_1\verb/%/option_1\verb/],/name_2\verb/[:/newName_2\verb/%/option_2\verb/],/\ldots \end{equation}$

(2.3)

Specify multiple field names delimited by comma. $name_ i$ represents the field names in the CSV file which is specified at fileName. Otherwise, terminate with the error "field name not found".

The two attributes $newName_ i$ and $option_ i$ can be specified (optional) at field name $name_ i$ . The attributes have various uses, and must be separated by : and %.

Typically, the calculation results from fields $name_ i$ will be added as a new field name in the output $newName_ i$ . In addition, $option_ i$ is an option used to control the content of processing.

This method returns a variety of information shown below in Hash. Font in Bold represents Hash key.



: names - names is the field name of the array (String Array).
: newNames - newNames is the new field name of the array (String Array). nil if this is not specified.
: options - options is the option of the array (String Array). nil if this is not specified.
: fld2csv - Item number (start from 0) in the CSV file (fileName) which corresponds to the fields specified at "key=" (String Array).
: csv2fld - Field number in CSV file is numbered according to the fields specified at "key=" in sequential order (starting from 0) (String Array). Fields that are not specified is nil.

# Contents of test.csv
fld1,fld2,fld3
1,2,3
4,5,6

# Command line 
$ ruby test.rb f=fld1,fld3

# Contents of test.rb
args=Margs.new(ARGV)
fld=args.field("f=","test.csv")
p fld["names"]   # -> ["fld1","fld3"]
p fld["fld2csv"] # -> [0,2] fld1,fld3 corresponds to 0th item and 2nd item in test.csv
p fld["csv2fld"] # -> [0,nil,1] the 0th item in test.csv is specified as 0th item at f=

# Command line
$ ruby test.rb f=fld3:newFld3%n,fld2%nr

# Contents of test.rb
args=Margs.new(ARGV)
fld=args.field("f=","test.csv")
p fld["names"]    # -> ["fld3", "fld2"]
p fld["newNames"] # -> ["newFld3", nil]
p fld["options"]  # -> ["n", "nr"]
p fld["fld2csv"]  # -> [2, 1]
p fld["csv2fld"]  # -> [nil, 1, 0]

* MCMD::Margs.str(keyWord[,default][,token1][,token2])

Obtain character string arguments



: keyWord - Keyword in "key=" format (String)
: default - Default value when the value is not specified. The value is nil if not specified.
: token1 Delimiter when multiple character strings are specified. When the argument is not specified, no delimiter will be used.
: token2 The character string divided by token1 is further delimited by token2. There will not be delimiter if the argument is not specified.

Among the arguments specified at the command line, return the character string that matches keyWord.

Return the default character string specified at the command line. Returns nil if default contains nil.

Return array when token1 is specified as the delimiter of the character string. If token2 is specified, return array within array.

# Command line
$ ruby test.rb v=abc

# Contents of test.rb
args=Margs.new(ARGV)
puts args.str("v=") # ->"abc"
puts args.str("w=") # -> nil
puts args.str("w=","xyz") # -> "xyz"

# Command line
$ ruby test.rb v=abc,efg:xyz,hij

# Contents of test.rb
args=Margs.new(ARGV)
puts args.str("v=") # ->"abc,efg:xyz,hij"
puts args.str("v=",nil,",") # ->["abc", "efg:xyz", "hij"]
puts args.str("v=",nil,",",":") # ->[["abc"], ["efg","xyz"], ["hij"]]

* MCMD::Margs.float(keyWord[,default][,from][,to]): Obtain float 
type numerical  arguments

: keyWord - Keyword in "key=” format (String).
: default - Specify the default value (Float). The value is nil if not specified.
: from Lower limit (Float) of range check. Lower limit is not checked if the argument is not specified.
: to Upper limit (Float) of range check. Upper limit is not checked if the argument is not specified.

For all arguments specified at command line, convert values that matches keyWord to Float. Return the default value specified at the command line. Program will terminate with an error if the range check fails.

# Command line
$ ruby test.rb v=0.12

# Contents of test.rb
args=Margs.new(ARGV)
puts args.float("v=") # -> 0.12
puts args.float("v=",nil,0.2,0.3) # -> Range error
puts args.float("w=") # -> nil
puts args.float("w=",0.1) # -> 0.1

* MCMD::Margs.int(keyWord[,default][,from][,to]) Obtain fixnum 
type numerical arguments

: keyWord - Keyword in key= format (String).
: default - Specify the default value (Float). The value is nil if not specified.
: from - Lower limit (Float) range check. Lower limit is not checked if the argument is not specified.
: to - Upper limit (Float) range check. Upper limit is not checked if the argument is not specified.

Among all arguments specified at command line, for values that matches keyWord, convert to Float. Return the default value specified at the command line. Program terminates with an error if range check fails.

# Command line
$ ruby test.rb v=10

# Contents of test.rb
args=Margs.new(ARGV)
puts args.int("v=") # -> 10
puts args.int("v=",,20,30) # -> Range error 
puts args.int("w=") # -> nil
puts args.int("w=",15) # -> 15

* MCMD::Margs.bool(keyWord) Obtain bool type arguments

: keyWord Keyword that corresponds to "-key" (String)

Among the arguments specified at the command line, return true if keyWord matches with the argument, otherwise return false.

# Command line 
$ ruby test.rb -flag

# Contents of test.rb
args=Margs.new(ARGV)
puts args.bool("-flag") # -> true
puts args.bool("-x") # -> false

2.3.2 Example

Example 1

# Command line 
$ ruby test.rb i=dat.csv v=value -abc

# Contents of test.rb
args=Margs.new(ARGV, "i=,o=,w=,-flag,-x", "i=,w=")
iFileName = args.file("i=") # -> "dat.csv"
oFileName = args.str("o=","result.csv") # -> "result.csv"
weight    = args.float("w=",0.1,0.0,1.0) # -> 0.1
flag      = args.bool("-abc") # -> true
wFlag     = args.bool("-w") # -> false

2.3 Margs - Argument operation class

2.3.1 Method

2.3.2 Example

Example 1

2.3.3 Related Command