class A4Tools::BuiltinCommand
Attributes
Public Class Methods
Command
category. Used to sort items in help.
# File lib/net_shell/builtin_command.rb, line 23 def category(category) @category_text = category end
Summary of command One-line description of command for use in help
# File lib/net_shell/builtin_command.rb, line 29 def description(description) @description_text = description end
Help text Supplemental help added to end of –help.
# File lib/net_shell/builtin_command.rb, line 41 def help(help) @help_text = help end
Load from a file (don't call this directly)
# File lib/net_shell/builtin_command.rb, line 77 def load_command(file, userdefined=false) cmdname = File.basename(file.to_s, ".rb") subclass = Class.new(A4Tools::BuiltinCommand) {} contents = IO.read(file) subclass.setup subclass.command = cmdname subclass.filepath = file subclass.sha1 = Digest::SHA1.hexdigest contents subclass.user_defined if userdefined subclass.class_eval( contents, file ) subclass end
don't override these unless you really know what you're doing and have a good reason
# File lib/net_shell/builtin_command.rb, line 143 def initialize(shell, input=nil, output=nil, error=nil) @shell = shell @parser = parser @input = input || StandardInput.new @output = output || StandardOutput.new @error = error || StandardOutput.new end
Defines a command line argument. Identical syntax to Trollop.
opt :name, "Supplies a name", :type => :string
# File lib/net_shell/builtin_command.rb, line 66 def opt(key, description, params={}) @opts.push({ key:key, description:description, params:params }) end
Actual code block to execute when the command is run
# File lib/net_shell/builtin_command.rb, line 71 def run(&block) @run_block = block end
# File lib/net_shell/builtin_command.rb, line 10 def setup @description_text = "" @usage_text = "" @help_text = "" @category_text = "General" @validator = proc { true } @tab_completors = { default: proc { [] } } @run_block = proc { "" } @opts = [] end
Tab completion Return an array of possible values. You are not responsible for filtering these values for those matching the current argument. If an index is supplied, the block will only be invoked for that argument.
# File lib/net_shell/builtin_command.rb, line 56 def tab(index=nil, &tab_completor) if index.nil? then @tab_completors[:default] = tab_completor else @tab_completors[index] = tab_completor end end
Command
line usage Added to end of usage argment. e.g. return “arg1 arg2” to get a string like “usage: my_command arg1 arg2”
# File lib/net_shell/builtin_command.rb, line 35 def usage(usage) @usage_text = usage end
Identify a command as user-defined (called automatically)
# File lib/net_shell/builtin_command.rb, line 92 def user_defined @is_user_defined = true end
Command
line validation Return true to indicate command line is valid. Return false to generate error and return usage help. Return a string to generate error and display the returned string.
# File lib/net_shell/builtin_command.rb, line 49 def validate(&validator) @validator = validator end
Public Instance Methods
# File lib/net_shell/builtin_command.rb, line 248 def all_opts global_opts + self.class.opts end
# File lib/net_shell/builtin_command.rb, line 180 def block_call(&block) self.class.send(:define_method, :__block_call, &block) self.class.send(:instance_method, :__block_call).bind(self).call end
# File lib/net_shell/builtin_command.rb, line 152 def category self.class.category_text end
# File lib/net_shell/builtin_command.rb, line 112 def client @shell.active_client end
# File lib/net_shell/builtin_command.rb, line 156 def command self.class.command end
# File lib/net_shell/builtin_command.rb, line 308 def console_print(s) $stdout.print s.gsub("\n","\r\n") end
# File lib/net_shell/builtin_command.rb, line 304 def console_puts(s) $stdout.puts s.gsub("\n","\r\n") end
# File lib/net_shell/builtin_command.rb, line 116 def deployment @shell.client(:deployment) end
# File lib/net_shell/builtin_command.rb, line 160 def description self.class.description_text end
# File lib/net_shell/builtin_command.rb, line 285 def educate buffer = PipeBuffer.new @parser.educate buffer intro_line = "#{command.style(:command)}: #{description}" userdef_line = user_defined? ? "User defined".style(:userdefined) : nil top_section = [intro_line, category.style(:category), userdef_line ].compact.join("\n") [top_section+"\n", usage_msg+"\n", buffer.buffer, help].compact.join("\n") end
# File lib/net_shell/builtin_command.rb, line 224 def execute(input, output, error, args) @input = input @output = output @error = error parse(args) r = perform r = [r, 0] unless r.is_a? Array @result = r[0] || "" @status = r[1] txt = @result.to_s unless txt.empty? then txt += "\n" unless txt.end_with? "\n" @output.write txt end @status end
# File lib/net_shell/builtin_command.rb, line 244 def global_opts [ { key: :help, description:"Show help", params:{} } ] end
# File lib/net_shell/builtin_command.rb, line 168 def help self.class.help_text end
# File lib/net_shell/builtin_command.rb, line 124 def kaiconfig @shell.client(:kaiconfig) end
# File lib/net_shell/builtin_command.rb, line 260 def parse(args) @realargs = Array.new(args) begin @params = @parser.parse(args) rescue Trollop::HelpNeeded @params = {help:true} rescue Trollop::VersionNeeded @params = {help:true} rescue Trollop::CommandlineError @params = {help:true} end @args = @parser.leftovers @args = args if @args.nil? or @args.empty? end
# File lib/net_shell/builtin_command.rb, line 252 def parser Trollop::Parser.new(all_opts) do |opts| opts.each do |option| opt option[:key], option[:description], option[:params] end end end
# File lib/net_shell/builtin_command.rb, line 205 def perform return [educate, 1] if params[:help] errmsg = validate return show_error(errmsg) if errmsg.is_a? String return show_error(usage_msg) if errmsg.nil? or errmsg == false begin block_call(&self.class.run_block) rescue Interrupt @error.write "Killed\n" return ["", 1] rescue SystemExit # allow commands to call exit raise rescue Exception => exception return show_exception(exception) end end
# File lib/net_shell/builtin_command.rb, line 296 def print(s="") @output.print s end
# File lib/net_shell/builtin_command.rb, line 300 def puts(s="") @output.puts s end
# File lib/net_shell/builtin_command.rb, line 120 def qa @shell.client(:qa) end
# File lib/net_shell/builtin_command.rb, line 128 def show_error(msg) @error.write "!!".style(:error) + " #{args[0].style(:command)}: #{msg}\n" return "", 1 end
# File lib/net_shell/builtin_command.rb, line 133 def show_exception(exception) @error.write "\n" @error.write "!!".style(:error) + "#{command} crashed: #{exception.class.to_s} #{exception.message}\n" @error.write "Stack trace: #{exception.backtrace.map {|l| " #{l}\n"}.join}" "" end
# File lib/net_shell/builtin_command.rb, line 185 def sym_for_param(param) param[2..-1].to_sym rescue "" end
# File lib/net_shell/builtin_command.rb, line 189 def tab # only include --command-arguments if we already have a dash param_mix = [] param_mix = all_opts.map { |opt| "--" + opt[:key].to_s.gsub("_","-") } if @realargs.last[0] == '-' key = if @realargs.length >= 2 and self.class.tab_completors.has_key? sym_for_param(@realargs[-2]) sym_for_param(@realargs[-2]) elsif self.class.tab_completors.has_key?(args.length-2) args.length - 2 else :default end param_mix + block_call(&(self.class.tab_completors[key])) end
# File lib/net_shell/builtin_command.rb, line 164 def usage self.class.usage_text end
# File lib/net_shell/builtin_command.rb, line 276 def usage_msg u = usage if usage.is_a? Array then "usage:\n" + (u.map { |line| "\t#{command} [flags] #{line}" }).join("\n") else "usage: #{command} [flags] #{usage}" end end
# File lib/net_shell/builtin_command.rb, line 176 def user_defined? self.class.is_user_defined end
convenience methods you might want to be aware of
# File lib/net_shell/builtin_command.rb, line 101 def usher if @shell.shared[:usher].nil? then @shell.shared[:usher] = A4Tools::UsherClient.new() end @shell.shared[:usher] end
# File lib/net_shell/builtin_command.rb, line 108 def usherm @shell.client(:usherm) end
# File lib/net_shell/builtin_command.rb, line 172 def validate block_call(&self.class.validator) end