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.



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

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.



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

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



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

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:



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

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



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

def default_rack_env = nil

#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



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

def description = ""

#detailed_description ⇒ Object

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



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

def detailed_description = nil

#env ⇒ Object

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



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

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.



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

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



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

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.



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

def opts = []

#puts(*args) ⇒ Object

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



160
161
162
163
164
 
# File 'lib/brut/cli/commands/base_command.rb', line 160

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.

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.



205
206
207
208
209
210
211
212
213
 
# File 'lib/brut/cli/commands/base_command.rb', line 205

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



183
184
185
 
# File 'lib/brut/cli/commands/base_command.rb', line 183

def stdin   = self.execution_context.stdin
# 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!`.



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/brut/cli/commands/base_command.rb', line 141

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

#theme ⇒ Object 



120
121
122
 
# File 'lib/brut/cli/commands/base_command.rb', line 120

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