Class: Brut::CLI::Commands::BaseCommand

Inherits:
Object
  • Object
show all
Defined in:
lib/brut/cli/commands/base_command.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#parent_command ⇒ Object

Returns the value of attribute parent_command.



4
5
6
 
# File 'lib/brut/cli/commands/base_command.rb', line 4

def parent_command
  @parent_command
end

Instance Method Details

#accepts ⇒ Array<Array>|Array<Class>

Specify type conversions for options. This is a loose wrapper around OptionParser#accept with a convienience feature to allow simpler conversions without a proc.

Examples:

class Type
  def initialize(value)
    value = value.to_s
    if ["new", "old", "promoted" ].include?(value)
      @value = value
    else
      raise ArgumentError, "'#{value}' is not a valid Type"
    end
  end
end
def opts = [
  [ "--type=TYPE", "The type of thing", Type ]
]
def accepts = [
  Type,
]
# or
def accepts = [
  [ Type, ->(val) { Type.new(val) },
]

Returns:

  • (Array<Array>|Array<Class>) —

    Must be an array. Any element that is a class will be used to convert any options of that type when the type is used in opts. If the element is a class, it is assumed that values can be converted via .new. If the class does not support .new as a conversion method, the element should be a two-element array where index 0 is the class and index 1 is a proc to convert the command line argument to the class's type.



86
 
# File 'lib/brut/cli/commands/base_command.rb', line 86

def accepts = []

#args_description ⇒ String

Returns description of the arguments this command accepts. Used for documentation only.

Returns:

  • (String) —

    description of the arguments this command accepts. Used for documentation only.



44
 
# File 'lib/brut/cli/commands/base_command.rb', line 44

def args_description = nil

#argv ⇒ Array<String>

Access the command line arguments leftover after all options have been parsed, when .execute was called

Returns:

  • (Array<String>) —

    leftover command line arguments



119
 
# File 'lib/brut/cli/commands/base_command.rb', line 119

def argv = self.execution_context.argv

#bootstrap? ⇒ true|false

True if the command requires Brut to fully bootstrap and start itself up. Bootstrapping isn't running a web server but it will do everything else, including connecting too all databases. Your command should return true for this if it needs to access a database or make API calls outside Brut::CLI. If this returns false, Brut's configuration options will still be available.

By default, this returns the value for bootstrap? of the default_command. If there is no default_command, this returns false.

Returns:

  • (true|false) —

    True if Brut should be fully bootstrap and connect to all database servers (e.g.). False if Brut should only set up its configuration options.



30
 
# File 'lib/brut/cli/commands/base_command.rb', line 30

def bootstrap? = default_command&.bootstrap? || false

#commands ⇒ Array<Brut::CLI::Commands::BaseCommand>

Returns a list of commands that represent the subcommands available to this command. By default, this will return all commands that are inner classes of this command.

Returns:



99
100
101
102
103
104
105
 
# File 'lib/brut/cli/commands/base_command.rb', line 99

def commands
  self.class.constants.map { |name|
    self.class.const_get(name)
  }.select { |constant|
    constant.kind_of?(Class) && constant.ancestors.include?(Brut::CLI::Commands::BaseCommand)
  }.map(&:new)
end

#default_command ⇒ Brut::CLI::Commands::BaseCommand|nil

Command to run if none provided on the command line.

Returns:

  • (Brut::CLI::Commands::BaseCommand|nil) —

    if nil, it is an error to run this command without a subcommand. If not-nil, the returned command will be executed.



91
 
# File 'lib/brut/cli/commands/base_command.rb', line 91

def default_command = self.commands.detect { it.class == default_command_class }

#default_command_class ⇒ Object 



93
 
# File 'lib/brut/cli/commands/base_command.rb', line 93

def default_command_class = nil

#default_rack_env ⇒ String|nil

The default RACK_ENV to use for this command. This value is used when no RACK_ENV is present in the UNIX environment and when --env has not been used on the command line. Do note that setting this in an app or parent command does not translate to the subcommands.

Returns:

  • (String|nil) —

    If nil, Brut configuration will not be loaded and the command will run more or less as if it were a plain Ruby script. If a String, this value will be set as the RACK_ENV if it's not been otherwise specified.



38
 
# File 'lib/brut/cli/commands/base_command.rb', line 38

def default_rack_env = default_command&.default_rack_env

#description ⇒ String

Returns description of this command for use in help output.

Returns:

  • (String) —

    description of this command for use in help output



41
 
# File 'lib/brut/cli/commands/base_command.rb', line 41

def description = ""

#env ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext#env. You should use this over ENV.



148
 
# File 'lib/brut/cli/commands/base_command.rb', line 148

def env     = self.execution_context.env

#env_vars ⇒ Array<Array<String>>

Returns Array of arrays documenting which environment variables affect this command's behavior. The array should have two elements: the env var name as a string, and a string documenting its purpose. This is used for documentation only.

Returns:

  • (Array<Array<String>>) —

    Array of arrays documenting which environment variables affect this command's behavior. The array should have two elements: the env var name as a string, and a string documenting its purpose. This is used for documentation only.



49
 
# File 'lib/brut/cli/commands/base_command.rb', line 49

def env_vars = []

#execute(execution_context) ⇒ Object

Execute the command in the given context. This is the method to call to execute a command programmatically, however you should not override this method. Instead, override .run to provide your command's logic.

to standard streams, the parsed options, and unparsed arguments.

Parameters:

  • execution_context (Brut::CLI::ExecutionContext) —

    the context in which the command will run, providing access



17
18
19
20
 
# File 'lib/brut/cli/commands/base_command.rb', line 17

def execute(execution_context)
  @execution_context = execution_context
  self.run
end

#name ⇒ String

The name of the command that the developer should use on the command line. By default, this is the underscorized version of the class' simple name.

Returns:

  • (String) —

    String the developer should use on the command line. If it has spaces or characters special to the shell, you will have a great sadness and possibly other mayhem.



10
 
# File 'lib/brut/cli/commands/base_command.rb', line 10

def name = RichString.new(self.class.name.split(/::/).last).underscorized

#options ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext#options.



145
146
147
 
# File 'lib/brut/cli/commands/base_command.rb', line 145

def options = self.execution_context.options
# Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#env`. You should use this over `ENV`.
# @!visibility public

#opts ⇒ Array<Array<Object>>

Used to specify the command line options for the command.

Returns:

  • (Array<Array<Object>>) —

    an array of arrays representing this command's reecognized command line options. Each member of the array is treated as arguments to OptionParser#on. Please consult the Rubydoc for that method to know what you can use here. It is quite flexible, including type conversions, documentation, and multiple forms of options.



55
 
# File 'lib/brut/cli/commands/base_command.rb', line 55

def opts = []

#puts(*args) ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext#stdout's puts.



129
130
131
 
# File 'lib/brut/cli/commands/base_command.rb', line 129

def puts(*args)
  self.execution_context.stdout.puts(*args)
end

#run ⇒ Integer|Object|StandardError

Runs whatever logic this command exists to execute. This is the method you must implement, however #execute is the public API and what you should call if you want to programmatically execute a command.

The default implementation will generate an error, which is suitable for an app or namespace command that require a subcommand.

Returns:

  • (Integer|Object|StandardError) —

    When an integer is returned, that is considered the exit status of the CLI invocation that ultimately called this command. If an Object (including nil and non-Integer numbers) is returned, the command is assumed to have succeeded and the return value is ignored. If an exception is returned, it's treated the same as if it were raised (don't return an exception).

Raises:

  • (Brut::CLI::Error|StandardError) —

    If a Brut::CLI::Error, the command is considered failed and the exception's message is printed to stderr and the exit status is nonzero. If another type of exception, it is bubbled up and shown to the user. Generally do not return any sort of exception - allow it to raise.



164
165
166
167
168
169
170
171
172
173
 
# File 'lib/brut/cli/commands/base_command.rb', line 164

def run
  if argv[0]
    stderr.puts "No such command '#{argv[0]}'"
    return 1
  end


  stderr.puts "Command is required"
  1
end

#stderr ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext#stderr. You should use this over STDERR or $stderr.



135
136
137
 
# File 'lib/brut/cli/commands/base_command.rb', line 135

def stderr  = self.execution_context.stderr
# Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stdin`. You should use this over `STDIN` of `$stdin`.
# @!visibility public

#stdin ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext#stdin. You should use this over STDIN of $stdin.



138
139
140
141
 
# File 'lib/brut/cli/commands/base_command.rb', line 138

def stdin   = self.execution_context.stdin
# Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#stdout`. You should use this over `STDOUT` of `$stdout`. Note
# that if you just want to output a string, use `puts`.
# @!visibility public

#stdout ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext#stdout. You should use this over STDOUT of $stdout. Note that if you just want to output a string, use puts.



142
143
144
 
# File 'lib/brut/cli/commands/base_command.rb', line 142

def stdout  = self.execution_context.stdout
# Convienience methods to defer to `Brut::CLI::Commands::ExecutionContext#options`.
# @!visibility public

#system!(*args, &block) ⇒ Object

Convienience methods to defer to Brut::CLI::Commands::ExecutionContext's Brut::CLI::Executor#system!.



123
124
125
 
# File 'lib/brut/cli/commands/base_command.rb', line 123

def system!(*args,&block)
  self.execution_context.executor.system!(*args,&block)
end