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.



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

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.



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

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



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

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 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.



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

def 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:



114
115
116
117
118
119
120
 
# File 'lib/brut/cli/commands/base_command.rb', line 114

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_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. This only applies to the command where the method is defined and its subclasses. It **does not** apply to subcommands of this command.

The default value is ‘development’, mostly because a default of ‘nil` produces a strange error message if your intention was to load Brut configuration.

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.



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

def default_rack_env = "development"

#delegate_to_command(command, execution_context = :use_ivar) ⇒ Object

Delegates control to another command. This is most useful for aliasing one command to another. If you want to run another command as part of yoru command, you can use this, however you must use ‘Brut::CLI::ExecuteResult` to examine the return value, so you know if the command succeeded or not.



26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/brut/cli/commands/base_command.rb', line 26

def delegate_to_command(command,execution_context=:use_ivar)
  execution_context = if execution_context == :use_ivar
                        @execution_context
                      else
                        execution_context
                      end
  if execution_context.nil?
    raise ArgumentError, "No execution context provided and none set on this command"
  end
  command.execute(execution_context)
end

#description ⇒ String

Returns description of this command for use in help output.

Returns:

  • (String) —

    description of this command for use in help output



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

def description = ""

#detailed_description ⇒ Object

Returns a more detaile description of the command. This can includes paragraphs (which will be maintained in the output), however any additional formatting is not rendered or used.



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

def detailed_description = nil

#env ⇒ Object

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



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

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.



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

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`.



207
208
209
 
# File 'lib/brut/cli/commands/base_command.rb', line 207

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.



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

def opts = []

#print(*args) ⇒ Object

Convienience method to defer to ‘Brut::CLI::Commands::ExecutionContext#stdout`’s ‘print`.



186
187
188
189
190
 
# File 'lib/brut/cli/commands/base_command.rb', line 186

def print(*args)
  if !options.quiet?
    self.execution_context.stdout.print(*args)
  end
end

#puts(*args) ⇒ Object

Convienience method to defer to ‘Brut::CLI::Commands::ExecutionContext#stdout`’s ‘puts`.



178
179
180
181
182
 
# File 'lib/brut/cli/commands/base_command.rb', line 178

def puts(*args)
  if !options.quiet?
    self.execution_context.stdout.puts(*args)
  end
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. In other words, **do not call this method in a test, call `execute` instead**.

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.



227
228
229
230
231
232
233
234
235
 
# File 'lib/brut/cli/commands/base_command.rb', line 227

def run
  if argv[0]
    puts theme.error.render("No such command '#{argv[0]}'")
    return 1
  end

  puts theme.error.render("Command is required")
  1
end

#stdin ⇒ Object

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



204
205
206
 
# File 'lib/brut/cli/commands/base_command.rb', line 204

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

#system!(*args, output: :log) ⇒ Object

Convienience methods to defer to ‘Brut::CLI::Commands::ExecutionContext`’s ‘Brut::CLI::Executor#system!`.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/brut/cli/commands/base_command.rb', line 153

def system!(*args,output: :log)
  command_output = ""
  block = if output == :log
            block ||= ->(output_chunk) {
              command_output << output_chunk
            }
          elsif output.kind_of?(Proc)
            block = output
          else
            nil
          end
  begin
    self.execution_context.executor.system!(*args,&block)
  ensure
    if command_output.length > 0
      progname = args.detect { it.kind_of?(String) }.split(" ")
      command_output.lines.each do |line|
        self.execution_context.logger.add(Logger::INFO, line.chomp, progname)
      end
    end
  end
end

#theme ⇒ Object 



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

def theme
  @theme = Brut::CLI::TerminalTheme.new(terminal:)
end