Class: CLIApp::Application

Inherits:
Object
  • Object
show all
Defined in:
lib/cliapp.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config, &gopts_handler) ⇒ Application

Returns a new instance of Application.



88
89
90
91
92
93
 
# File 'lib/cliapp.rb', line 88

def initialize(config, &gopts_handler)
  @config        = config
  @gopts_handler = gopts_handler
  @gopts_schema  = {}  # ex: {:help => ["-h", "--hel", "help message"}
  @actions       = {}  # ex: {"clean" => Action.new(:clean, "delete files", {:all=>["-a", "all"]})}
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



95
96
97
 
# File 'lib/cliapp.rb', line 95

def config
  @config
end

Instance Method Details

#action(name, desc, schema_dict = {}, &block) ⇒ Object 



103
104
105
106
107
108
109
110
111
 
# File 'lib/cliapp.rb', line 103

def action(name, desc, schema_dict={}, &block)
  #; [!i1jjg] converts action name into string.
  name = name.to_s
  #; [!kculn] registers an action.
  action = Action.new(name, desc, schema_dict, &block)
  @actions[name] = action
  #; [!82n8q] returns an action object.
  return action
end

#action_help_message(action, width: nil, indent: nil) ⇒ Object 



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/cliapp.rb', line 238

def action_help_message(action, width: nil, indent: nil)
  #; [!ny72g] build action help message.
  #; [!pr2vy] includes 'Options:' section if any options exist.
  #; [!1xggx] help message will be affcted by config.
  options_str = option_help_message(action.option_schema, width: width, indent: indent)
  optstr = options_str.empty? ? "" : " [<options>]"
  argstr = Util.argstr_of_proc(action.block)
  c = @config; cl = Util::Color
  sb = []
  sb << <<"END"
#{cl.strong(c.command + ' ' + action.name)} --- #{action.desc}

#{cl.header('Usage:')}
#{c.help_indent}$ #{c.command} #{action.name}#{optstr}#{argstr}
END
  sb << (options_str.empty? ? "" : <<"END")

#{cl.header('Options:')}
#{options_str.chomp()}
END
  return sb.join()
end

#application_help_message(width: nil, indent: nil) ⇒ Object 



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/cliapp.rb', line 201

def application_help_message(width: nil, indent: nil)
  #; [!p02s2] builds application help message.
  #; [!41l2g] includes version number if it is specified.
  #; [!2eycw] includes 'Options:' section if any global options exist.
  #; [!x3dim] includes 'Actions:' section if any actions defined.
  #; [!vxcin] help message will be affcted by config.
  c = @config
  indent ||= c.help_indent
  options_str = option_help_message(@gopts_schema, width: width, indent: indent)
  format = "#{indent}%-#{width || c.help_action_width}s %s\n"
  actions_str = each_action(sort: true).collect {|action|
    format % [action.name, action.desc]
  }.join()
  optstr = options_str.empty? ? "" : " [<options>]"
  actstr = actions_str.empty? ? "" : " <action> [<arguments>...]"
  cl = Util::Color
  ver = c.version ? " " + cl.weak("(#{c.version})") : nil
  sb = []
  sb << <<"END"
#{cl.strong(c.name)}#{ver} --- #{c.desc}

#{cl.header('Usage:')}
#{indent}$ #{cl.strong(c.command)}#{optstr}#{actstr}
END
  sb << (options_str.empty? ? "" : <<"END")

#{cl.header('Options:')}
#{options_str.chomp()}
END
  sb << (actions_str.empty? ? "" : <<"END")

#{cl.header('Actions:')}
#{actions_str.chomp()}
END
  return sb.join()
end

#each_action(sort: false, &b) ⇒ Object 



118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/cliapp.rb', line 118

def each_action(sort: false, &b)
  #; [!u46wo] returns Enumerator object if block not given.
  return to_enum(:each_action, sort: sort) unless block_given?()
  #; [!yorp6] if `sort: true` passed, sort actions by name.
  names = @actions.keys
  names = names.sort if sort
  #; [!ealgm] yields each action object.
  names.each do |name|
    yield @actions[name]
  end
  nil
end

#get_action(name) ⇒ Object 



113
114
115
116
 
# File 'lib/cliapp.rb', line 113

def get_action(name)
  #; [!hop4z] returns action object if found, nil if else.
  return @actions[name.to_s]
end

#global_options(option_schema = {}) ⇒ Object 



97
98
99
100
101
 
# File 'lib/cliapp.rb', line 97

def global_options(option_schema={})
  #; [!2kq26] accepts global option schema.
  @gopts_schema = option_schema
  nil
end

#handle_global_options(global_opts) ⇒ Object 



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/cliapp.rb', line 176

def handle_global_options(global_opts)
  #; [!6n0w0] when '-h' or '--help' specified, prints help message and returns true.
  if global_opts[:help]
    #; [!fadq1] decolorizes app help message when stdout is not a tty.
    print decolorize(application_help_message())
    return true
  end
  #; [!zii8c] when '-V' or '--version' specified, prints version number and returns true.
  if global_opts[:version]
    puts @config.version
    return true
  end
  #; [!csw5l] when '-l' or '--list' specified, prints action list and returns true.
  if global_opts[:list]
    print list_actions()
    return true
  end
  #; [!5y8ph] if global option handler block specified, call it.
  if (handler = @gopts_handler)
    return !! handler.call(global_opts)
  end
  #; [!s816x] returns nil if global options are not handled.
  return nil
end

#main(argv = ARGV, &error_handler) ⇒ Object 



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/cliapp.rb', line 131

def main(argv=ARGV, &error_handler)
  #; [!hopc3] returns 0 if finished successfully.
  run(*argv)
  return 0
rescue OptionParser::ParseError, CLIApp::ActionError => exc
  #; [!uwcq7] yields block with error object if error raised.
  if block_given?()
    yield exc
  #; [!e0t6k] reports error into stderr if block not given.
  else
    s = "[ERROR]"
    s = Util::Color.error(s) if $stderr.tty?
    $stderr.puts "#{s} #{exc.message}"
  end
  #; [!d0g0w] returns 1 if error raised.
  return 1
end

#parse_action_options(action, args) ⇒ Object 



269
270
271
272
273
274
275
276
277
 
# File 'lib/cliapp.rb', line 269

def parse_action_options(action, args)
  #; [!5m767] parses action options and returns it.
  parser = new_parser()
  action_opts = prepare_parser(parser, action.option_schema)
  #; [!k2cto] adds '-h, --help' option automatically.
  parser.on("-h", "--help", "print help message") {|v| action_opts[:help] = v }
  parser.permute!(args)  # parse all options even after arguments
  return action_opts
end

#parse_global_options(args) ⇒ Object 



261
262
263
264
265
266
267
 
# File 'lib/cliapp.rb', line 261

def parse_global_options(args)
  #; [!o83ty] parses global options and returns it.
  parser = new_parser()
  global_opts = prepare_parser(parser, @gopts_schema)
  parser.order!(args)    # not parse options after arguments
  return global_opts
end

#run(*args) ⇒ Object 



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/cliapp.rb', line 149

def run(*args)
  #; [!qv5fz] parses global options (not parses action options).
  global_opts = parse_global_options(args)
  #; [!kveua] handles global options such as '--help'.
  done = handle_global_options(global_opts)
  return if done
  #; [!j029i] prints help message if no action name specified.
  if args.empty?
    done = do_when_action_not_specified(global_opts)
    return if done
  end
  #; [!43u4y] raises error if action name is unknown.
  action_name = args.shift()
  action = get_action(action_name)  or
    raise ActionNotFoundError, "#{action_name}: Action not found."
  #; [!lm0ir] parses all action options even after action args.
  action_opts = parse_action_options(action, args)
  #; [!ehshp] prints action help if action option contains help option.
  if action_opts[:help]
    #; [!6vet4] decolorizes action help message when stdout is not a tty.
    print decolorize(action_help_message(action))
    return
  end
  #; [!0nwwe] invokes an action with action args and options.
  action.call(*args, **action_opts)
end