module ActionCommand
To use action command, create subclasses of ActionCommand::Executable
and run them using the ActionCommand.execute_… variants.
Unnecessary comment for rubocop
Constants
- CONTEXT_API
Used as a root element when the command is executed from an API context
- CONTEXT_RAILS
Used as root parent of command if we are executing it from rails (a controller, etc)
- CONTEXT_RAKE
Used as root parent of command if we are in a rake task
- CONTEXT_TEST
Used as root parent of command if we are in a testing context.
- LOG_KIND_COMMAND_INPUT
log entry for the input to a commmand
- LOG_KIND_COMMAND_OUTPUT
log entry for the output from a command
- LOG_KIND_DEBUG
debug message from within a command
- LOG_KIND_ERROR
error message from within a command
- LOG_KIND_INFO
info message from within a command
- OPTIONAL
Used to create an optional parameter in
describe_io
- RESULT_CODE_FAILED
Used as a generic result code for failure, if you do not provide a more specific one through {ActionCommand::Result#failed_with_code}
- RESULT_CODE_OK
Used if a result has had no failures
- VERSION
Version of this Gem
Public Class Methods
# File lib/action_command.rb, line 173 def self.check_params(cls, params) raise ArgumentError, 'Expected params to be a Hash' unless params.is_a? Hash unless cls.is_a?(Class) && cls.ancestors.include?(ActionCommand::Executable) raise ArgumentError, 'Expected an ActionCommand::Executable as class' end end
Used internally, not for general purpose use.
# File lib/action_command.rb, line 156 def self.create_and_execute(cls, params, parent, result) check_params(cls, params) params[:parent] = parent logger = params[:logger] logger = @@logger unless logger log_format = :json log_format = params[:log_format] if params.key?(:log_format) result.configure_logger(logger, log_format) result.root_command(cls) if parent.is_a? Symbol action = cls.new(params) result.log_input(params) action.execute(result) result.log_output return result end
@return a new, valid, empty result.
# File lib/action_command.rb, line 63 def self.create_result return ActionCommand::Result.new end
Create a global description of the inputs and outputs of a command. Should usually be called within an ActionCommand::Executable
subclass in its self.describe_io method
# File lib/action_command.rb, line 143 def self.describe_io(cmd_cls, desc) name = cmd_cls.name params = @@params[name] unless params params = InputOutput.new(cmd_cls, desc) @@params[name] = params yield params params.input(:help, 'Help for this command', OPTIONAL) if params.input_count == 0 end return params end
Execute a command at the root level of an api context @param cls [ActionCommand::Executable] The class of an Executable
subclass @param params [Hash] parameters used by the command. @return [ActionCommand::Result]
# File lib/action_command.rb, line 120 def self.execute_api(cls, params = {}) result = create_result return ActionCommand.create_and_execute(cls, params, CONTEXT_API, result) end
Execute a child command, placing its results under the specified subkey @param parent [ActionCommand::Executable] An instance of the parent command @param cls [ActionCommand::Executable] The class of an Executable
subclass @param result [ActionCommand::Result] The result to populate @param result_key [Symbo] a key to place the results under, or nil if you want
the result stored directly on the current results object.
@param params [Hash] parameters used by the command. @return [ActionCommand::Result]
# File lib/action_command.rb, line 133 def self.execute_child(parent, cls, result, result_key, params = {}) result.push(result_key, cls) ActionCommand.create_and_execute(cls, params, parent, result) result.pop(result_key) return result end
Execute a command at the root level of a rails context @param cls [ActionCommand::Executable] The class of an Executable
subclass @param params [Hash] parameters used by the command. @return [ActionCommand::Result]
# File lib/action_command.rb, line 111 def self.execute_rails(cls, params = {}) result = create_result return ActionCommand.create_and_execute(cls, params, CONTEXT_RAILS, result) end
Execute a command at the root level of a rake task context. @param cls [ActionCommand::Executable] The class of an Executable
subclass @param args parameters used by the command. @return [ActionCommand::Result]
# File lib/action_command.rb, line 85 def self.execute_rake(cls, args) io = cls.describe_io if io.help? args io.show_help return end result = create_result ActionCommand.create_and_execute(cls, io.rake_input(args), CONTEXT_RAKE, result) io.print_output(result) return result end
Execute a command at the root level of a testing context
@param rspec pass in ‘self’ in an rspec example if you want to
perform internal validations. See {Executable#testing} to embed test code within commands.
@param cls [ActionCommand::Executable] the class of an Executable
subclass @param params [Hash] parameters used by the command. @return [ActionCommand::Result]
# File lib/action_command.rb, line 75 def self.execute_test(rspec, cls, params = {}) params[:test] = rspec result = create_result return ActionCommand.create_and_execute(cls, params, CONTEXT_TEST, result) end
Install a command as a rake task in a
# File lib/action_command.rb, line 100 def self.install_rake(rake, sym, cls, deps) rake.send(:desc, cls.describe_io.desc) rake.send(:task, sym, cls.describe_io.keys => deps) do |_t, args| ActionCommand.execute_rake(cls, args) end end
Set a logger to be used when creating commands.
@param logger Any object that implements .error and .info
# File lib/action_command.rb, line 58 def self.logger=(logger) @@logger = logger # rubocop:disable Style/ClassVars end