Ruby stdlib 学习 —— OptionParser

http://ruby-doc.org/stdlib-2.3.3/libdoc/optparse/rdoc/OptionParser.html#method-c-new

 

　　阅读lib的文档，做个笔记。OptionParser 这个类用于，在写一些command line工具的时候，设置命令行参数选项。GetoptLong有类似的功能，不过文中建议使用OptionParser.

一、例：简单示例 （主要是入个门，顺便演示了下不带参数的选项该怎么处理，像-v, -f 那种））

#直接存成test.rb， 运行 ruby test.rb -v somethingnouse 能正常运行
#运行 ruby test.rb -v somethingnouse -s，因为没有设置-s的选项处理，
#会报错"invalid option: -s (OptionParser::InvalidOption)"
require 'optparse'
 
p ARGV # => ["-v", "somethingnouse"]
options = {} #自己设置用来接收输入参数的hash,用数组应该也可以，随便，
             #也可以说和OptionParser没什么关系
OptionParser.new do |opts|
  opts.banner = "Usage: example.rb [options]"
 
  opts.on("-v", "--[no-]verbose", "Run verbosely") do |v| #选项-v后面没有值，看来有的话会赋值成true
    puts "value of v"#不写-v选项的话程序根本不到这一行，可以理解成if has "-v" 这种感觉吧
    puts v #=> true
    options[:verbose] = v #这里写一些功能上的code
  end
end.parse! #shift一个参数, Code：a = [1,2,3]; a.shift ##output=> a=[2,3] 应该是类似这种机制吧，细节没看
 
p options #{:verbose=>true}
p ARGV #["somethingnouse"]

 

二、例：生成help

基本就是边调试边注释来学习的。在文档里例子的基础上改了一些小地方用作调试。

require 'optparse'
 
Options = Struct.new(:name)
 
class Parser
  def self.parse(options)
    args = Options.new("world") #Struct类args的参数name默认值为"world"
 
    opt_parser = OptionParser.new do |opts| #开始使用OptionParser类处理参数
      opts.banner = "Usage:example.rb [option]" #输出help时最上面那一行
 
      opts.on("-n NAME", "--name=NAME", "Name to say hello to") do |n|
      #输入参数选项为-n时，需要带参数NAME， 用法：ruby test.rb --name="A puppy"
      #例子里-nNAME之间没有空格，测了一下参数写成"-nDog"是好用的。
      #同样，长参数--name写成--name NAME，而在调用的时候 ruby test.rb --name="A puppy"也成立，非常灵活
        args.name = n #这里其实就是把参数值传到别的地方去，加工，打印，随你怎么处理
        puts n       
        puts "#{ARGV}" #可以用例查看一下ARGV的变化，命令为 ruby test.rb -n Dog -h 运行时，这里输出["-h"]
                       #和预想的有点出入，有时间可以看看OptionParser的Code深入理解一下
      end
 
      opts.on("-h", "--help", "Prints this help") do
        puts opts #打印所有的opts内容，其实就是我们设置的每项opt.on的加上banner
        #exit #打印完help就退出了，不处理其他参数。注意exit是退出程序
        #比如我在line17 打印了name的值。如果我运行 ruby test.rb -n Dog -h
        #output:
        #Dog
        #Usage:example.rb [option]
        #-n, --name=NAME                  Name to say hello to
        #-h, --help                       Prints this help
        #显然先处理了 -n 选项，又处理了-h再退出的
 
      end
    end
 
    opt_parser.parse!(options) #！=>shift 继续处理下一个参数
    return args  #看到这里就明白，在实际应用中，可以用这个Struct来收集所有传入的参数值
  end
end
 
#options = Parser.parse %w[-h] #%w 用于表示其中元素被引号括起的数组，元素用空格分离。如 %w[a b] => ["a", "b"]
options = Parser.parse ARGV #直接处理运行命令行传入的参数
puts options

 

　　顺便搜了一下ruby的选项源码：就是ruby --help列举的那些：https://github.com/ruby/ruby/blob/ruby_2_3/ruby.c 好像也没用什么库之类的（主要搂了一眼没看着include<getopt.h>），应该是直接宏+printf（这几行code位置line168-237）:

static void
usage(const char *name, int help)
{
    /* This message really ought to be max 23 lines.
     * Removed -h because the user already knows that option. Others? */

    struct message {
    const char *str;
    unsigned short namelen, secondlen;
    };
#define M(shortopt, longopt, desc) { \
    shortopt " " longopt " " desc, \
    (unsigned short)sizeof(shortopt), \
    (unsigned short)sizeof(longopt), \
}
    static const struct message usage_msg[] = {
    M("-0[octal]",       "",               "specify record separator (\\0, if no argument)"),
    M("-a",           "",               "autosplit mode with -n or -p (splits $_ into $F)"),
    M("-c",           "",               "check syntax only"),
    M("-Cdirectory",   "",               "cd to directory before executing your script"),
    M("-d",           ", --debug",           "set debugging flags (set $DEBUG to true)"),
    M("-e 'command'",  "",               "one line of script. Several -e's allowed. Omit [programfile]"),
    M("-Eex[:in]",     ", --encoding=ex[:in]", "specify the default external and internal character encodings"),
    M("-Fpattern",       "",               "split() pattern for autosplit (-a)"),
    M("-i[extension]", "",               "edit ARGV files in place (make backup if extension supplied)"),
    M("-Idirectory",   "",               "specify $LOAD_PATH directory (may be used more than once)"),
    M("-l",           "",               "enable line ending processing"),
    M("-n",           "",               "assume 'while gets(); ... end' loop around your script"),
    M("-p",           "",               "assume loop like -n but print line also like sed"),
    M("-rlibrary",       "",               "require the library before executing your script"),
    M("-s",           "",               "enable some switch parsing for switches after script name"),
    M("-S",           "",               "look for the script using PATH environment variable"),
    M("-T[level=1]",   "",               "turn on tainting checks"),
    M("-v",           ", --verbose",       "print version number, then turn on verbose mode"),
    M("-w",           "",               "turn warnings on for your script"),
    M("-W[level=2]",   "",               "set warning level; 0=silence, 1=medium, 2=verbose"),
    M("-x[directory]", "",               "strip off text before #!ruby line and perhaps cd to directory"),
    M("-h",           "",               "show this message, --help for more info"),
    };
    static const struct message help_msg[] = {
    M("--copyright",                   "", "print the copyright"),
    M("--enable=feature[,...]",       ", --disable=feature[,...]",
      "enable or disable features"),
    M("--external-encoding=encoding",  ", --internal-encoding=encoding",
      "specify the default external or internal character encoding"),
    M("--version",                     "", "print the version"),
    M("--help",               "", "show this message, -h for short message"),
    };
    static const struct message features[] = {
    M("gems",    "",        "rubygems (default: "DEFAULT_RUBYGEMS_ENABLED")"),
    M("did_you_mean", "",   "did_you_mean (default: "DEFAULT_RUBYGEMS_ENABLED")"),
    M("rubyopt", "",        "RUBYOPT environment variable (default: enabled)"),
    M("frozen-string-literal", "", "freeze all string literals (default: disabled)"),
    };
    int i;
    const int num = numberof(usage_msg) - (help ? 1 : 0);
#define SHOW(m) show_usage_line((m).str, (m).namelen, (m).secondlen, help)

    printf("Usage: %s [switches] [--] [programfile] [arguments]\n", name);
    for (i = 0; i < num; ++i)
    SHOW(usage_msg[i]);

    if (!help) return;

    for (i = 0; i < numberof(help_msg); ++i)
    SHOW(help_msg[i]);
    puts("Features:");
    for (i = 0; i < numberof(features); ++i)
    SHOW(features[i]);
}

　　用宏定义函数这方面的知识我基本为0。有兴趣可以观摩一下。

 

三、参数有一些内置类型可以直接拿来用

Date – Anything accepted by Date.parse

DateTime – Anything accepted by DateTime.parse

Time – Anything accepted by Time.httpdate or Time.parse

URI – Anything accepted by URI.parse

Shellwords – Anything accepted by Shellwords.shellwords

String – Any non-empty string

Integer – Any integer. Will convert octal. (e.g. 124, -3, 040)

Float – Any float. (e.g. 10, 3.14, -100E+13)

Numeric – Any integer, float, or rational (1, 3.4, 1/3)

DecimalInteger -- Like Integer, but no octal format.

OctalInteger -- Like Integer, but no decimal format.

DecimalNumeric -- Decimal integer or float.

TrueClass – Accepts ‘+, yes, true, -, no, false’ and defaults as true

FalseClass – Same as TrueClass, but defaults to false

Array – Strings separated by ‘,’ (e.g. 1,2,3)

Regexp – Regular expressions. Also includes options.

 

一个使用time的例子：

require 'optparse'
require 'optparse/time'
 
OptionParser.new do |parser|
  #例子比较简单，重点应该就在第三个参数，输入之后相关类会自动解析？
  parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
    p time
  end
end.parse!
# 比如运行：ruby test.rb  -t 2000-1-1
# output: 2000-01-01 00:00:00 +0800
# time 被自动处理了

 

四 op.accept用法。

理解上可以用accept关联任何自定义类型的实例，再通过OptionParser和外界交互。文档里举得这个例子，可以联想到gem install 的用法。比如：gem install libA。gem 要去查询libA的安装路径时，每个lib和安装路径就是key和value的关系。如果找不到这个libA，当然也就报错了。先这么理解着。

require 'optparse'

User = Struct.new(:id, :name) #自定义对象User

def find_user id
  not_found = ->{ raise "No User Found for id #{id}" }
  [ User.new(1, "Sam"),
    User.new(2, "Gandalf") ].find(not_found) do |u|
    u.id == id  #在判断是否存在某个的id时候顺便初始化了两个User实例
  end
end

op = OptionParser.new
  op.accept(User) do |user_id|  #运行ruby test.rb --user 1
    puts find_user user_id.to_i #output:#<struct User id=1, name="Sam">
    #User.new(3, "SomeOne")     #如果注释掉前一行，输入参数为 --user 1也会返回
  end                           ##<struct User id=3, name="SomeOne">

  op.on("--user ID", User) do |user|
    puts user                   ##<struct User id=1, name="Sam">
  end                           #看来这里最终打印的user就是op.accept的返回值
op.parse!

#简化了一下find_user中[].find这段代码。
[1, 2].find(->{ raise "throw Exception"}) do |a|
    a == 1 #如果在这行之前加puts，输出 false true；
end        #但这样的话find会接收不到返回值：true or false。
           #会导致 ->{}中的代码必然运行
#可见这段代码的作用是：
#遍历数组元素，如果包含目标元素（所有返回值中只要有一个true），正常运行
#如果不包含目标元素，运行代码块->{}中的内容

五 一个完整的例子

例子的题目是Complete example，应该比较长也比较完整

英文注释是原文里的，起手可以运行 test.rb --help 看看效果

 

require 'optparse'
require 'optparse/time'
require 'ostruct'
require 'pp'

class OptparseExample
  Version = '1.0.0'

  CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
  CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }

  class ScriptOptions
    attr_accessor :library, :inplace, :encoding, :transfer_type,
                  :verbose, :extension, :delay, :time, :record_separator,
                  :list

    def initialize
      self.library = []
      self.inplace = false
      self.encoding = "utf8"
      self.transfer_type = :auto
      self.verbose = false
    end

    def define_options(parser)
      parser.banner = "Usage: example.rb [options]"
      parser.separator "" #看上去跟在banner后面纯换行用的
      parser.separator "Specific options:" #打印字面内容

      # add additional options
      perform_inplace_option(parser) #每个选项的具体内容，由各个具体的函数分担
      delay_execution_option(parser)
      execute_at_time_option(parser)
      specify_record_separator_option(parser)
      list_example_option(parser)
      specify_encoding_option(parser)
      optional_option_argument_with_keyword_completion_option(parser)
      boolean_verbose_option(parser)

      parser.separator "" #空行
      parser.separator "Common options:" #打印字面内容
      # No argument, shows at tail.  This will print an options summary.
      # Try it and see!
      parser.on_tail("-h", "--help", "Show this message") do
        puts parser
        exit
      end
      # Another typical switch to print the version.
      parser.on_tail("--version", "Show version") do
        puts Version
        exit
      end
    end
    #从这里开始是处理每个选项的函数
    def perform_inplace_option(parser)
      # Specifies an optional option argument
      parser.on("-i", "--inplace [EXTENSION]",
                "Edit ARGV files in place",
                "(make backup if EXTENSION supplied)") do |ext|
        self.inplace = true        #test.rb -i txt 这个工具是用来创建文件的？@inplace=true
        self.extension = ext || '' #扩展名？这里显示@extension=".txt"
        self.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
      end
    end

    def delay_execution_option(parser) #deley多长时间后运行？
      # Cast 'delay' argument to a Float.
      parser.on("--delay N", Float, "Delay N seconds before executing") do |n|
        self.delay = n
      end
    end

    def execute_at_time_option(parser) #开始运行的时间，是个内置time类型
      # Cast 'time' argument to a Time object.
      parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
        self.time = time
      end
    end

    def specify_record_separator_option(parser)
      # Cast to octal integer. 转换成8进制的数？
      parser.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
                "Specify record separator (default \\0)") do |rs|
        self.record_separator = rs
      end
    end

    def list_example_option(parser) #参数Array类型
      # List of arguments.
      parser.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
        self.list = list
      end
    end

    def specify_encoding_option(parser) #可以写code 或者code_aliases. test.rb --code jis => @encoding="iso-2022-jp"
      # Keyword completion.  We are specifying a specific set of arguments (CODES
      # and CODE_ALIASES - notice the latter is a Hash), and the user may provide
      # the shortest unambiguous text.
      code_list = (CODE_ALIASES.keys + CODES).join(', ')
      parser.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
                "(#{code_list})") do |encoding|
        self.encoding = encoding
      end
    end

    def optional_option_argument_with_keyword_completion_option(parser)
      # Optional '--type' option argument with keyword completion.
      parser.on("--type [TYPE]", [:text, :binary, :auto], #设置转换类型？参数必须是[]里这几个
                "Select transfer type (text, binary, auto)") do |t| #比较神奇的是 --type t或 a 或 b（key首字母）
        self.transfer_type = text                                   #也成功了，ruby 的特色吧应该^_^ 
      end
    end

    def boolean_verbose_option(parser) #bool类型选项
      # Boolean switch.
      parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
        self.verbose = v
      end
    end
  end

  #
  # Return a structure describing the options.
  #
  def parse(args) #参数处理函数，可以注意一下这里的实例变量是怎么用的
    # The options specified on the command line will be collected in
    # *options*.

    @options = ScriptOptions.new
    @args = OptionParser.new do |parser| #这部分是前面几个例子里用到OptionParser参数处理主体
      @options.define_options(parser)    #无非是调用define_options去一个一个处理了
      parser.parse!(args)
    end
    @options
  end

  attr_reader :parser, :options
end  # class OptparseExample

example = OptparseExample.new
options = example.parse(ARGV)
pp options # example.options
pp ARGV