Module: Acclaim::Command::DSL

Includes:
Root
Defined in:
lib/acclaim/command/dsl.rb,
lib/acclaim/command/dsl/root.rb

Overview

Module containing the methods that make up the domain-specific language used to create commands.

Author:

  • Matheus Afonso Martins Moreira

Since:

  • 0.4.0

Defined Under Namespace

Modules: Root

Instance Method Summary collapse

Methods included from Root

#help, #version

Instance Method Details

#action {|options, arguments| ... } ⇒ Proc? Also known as: when_called

The block which is executed when this command is called.

Yield Parameters:

  • options (Ribbon) —

    a Ribbon instance which associates options with their corresponding values

  • arguments (Array) —

    the arguments that remained in the command line

Returns:

  • (Proc, nil) —

    the given block

Since:

  • 0.4.0



60
61
62
63
 
# File 'lib/acclaim/command/dsl.rb', line 60

def action(&block)
  @action = block if block.respond_to? :call
  @action
end

#command_ancestors ⇒ Object

Returns all command ancestors of this command.

Since:

  • 0.4.0



118
119
120
 
# File 'lib/acclaim/command/dsl.rb', line 118

def command_ancestors
  ancestors - Acclaim::Command.ancestors
end

#command_path ⇒ Object

Returns the sequence of commands from #root that leads to this command.

Since:

  • 0.4.0



128
129
130
 
# File 'lib/acclaim/command/dsl.rb', line 128

def command_path
  command_ancestors.reverse
end

#execute(options, arguments) ⇒ Object Also known as: call

Calls this command’s action block with the given option values and arguments.

Since:

  • 0.4.0



106
107
108
 
# File 'lib/acclaim/command/dsl.rb', line 106

def execute(options, arguments)
  @action.call options, arguments if @action.respond_to? :call
end

#full_line(*arguments) ⇒ Object

Computes the full command line of this command, which takes parent commands into account.

class Command < Acclaim::Command
  class Do < Command
    class Something < Do
    end
  end
end

Command::Do::Something.full_line
 => "do something"

Command::Do::Something.full_line include_root: true
 => "command do something"

Since:

  • 0.4.0



147
148
149
150
151
152
 
# File 'lib/acclaim/command/dsl.rb', line 147

def full_line(*arguments)
  options = arguments.extract_ribbon!
  command_path.tap do |path|
    path.shift unless options.include_root?
  end.map(&:line).join ' '
end

#invoke(arguments = [], options = []) ⇒ Object

Parses the argument array. The argument array will be searched for subcommands; if one is found, it will be invoked, if not, this command will be executed. A subcommand may be anywhere in the array as long as it is before an argument separator, which is tipically a double dash (--) and may be omitted.

All argument separators will be deleted from the argument array before a command is executed.

Since:

  • 0.4.0



92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/acclaim/command/dsl.rb', line 92

def invoke(arguments = [], options = [])
  options = options + self.options
  subcommand = parse_subcommands_in! arguments
  if subcommand.nil?
    parsed_options = Option::Parser.new(arguments, options).parse!
    delete_argument_separators_in! arguments
    execute parsed_options, arguments
  else
    subcommand.invoke arguments, options
  end
end

#line ⇒ String #line(string) ⇒ String

The string used to invoke this command from the command line.

Overloads:

  • #line ⇒ String

    If not set, will try to figure out the name from the command’s class.

    Returns:

    • (String) —

      the name used to invoke this command

  • #line(string) ⇒ String

    Uses the given string to invoke this command.

    Parameters:

    • string (String, nil) —

      the new command name

    Returns:

    • (String) —

      the name used to invoke this command

Since:

  • 0.4.0



25
26
27
28
 
# File 'lib/acclaim/command/dsl.rb', line 25

def line(*arguments)
  @line = arguments.first unless arguments.empty?
  @line ||= (name.gsub(/^.*::/, '').downcase if respond_to? :name)
end

#option(*arguments, &block) ⇒ Object Also known as: opt

Adds an option to this command.

See Also:

Since:

  • 0.4.0



47
48
49
 
# File 'lib/acclaim/command/dsl.rb', line 47

def option(*arguments, &block)
  options << Option.new(*arguments, &block)
end

#options ⇒ Array

The options this command can take.

Returns:

  • (Array) —

    the options this command takes

Since:

  • 0.4.0



40
41
42
 
# File 'lib/acclaim/command/dsl.rb', line 40

def options
  @options ||= []
end

#parse_options_in!(arguments) ⇒ Object

Parses the argument array using this command’s set of options.

Since:

  • 0.4.0



68
69
70
 
# File 'lib/acclaim/command/dsl.rb', line 68

def parse_options_in!(arguments)
  Option::Parser.new(arguments, options).parse!
end

#parse_subcommands_in!(arguments) ⇒ Object

Looks for this command’s subcommands in the argument array.

Since:

  • 0.4.0



73
74
75
 
# File 'lib/acclaim/command/dsl.rb', line 73

def parse_subcommands_in!(arguments)
  Command::Parser.new(arguments, subcommands).parse!
end

#root ⇒ Object

Returns the root of the command hierarchy.

Since:

  • 0.4.0



123
124
125
 
# File 'lib/acclaim/command/dsl.rb', line 123

def root
  command_ancestors.last
end

#root? ⇒ Boolean

True if this is a top-level command.

Returns:

  • (Boolean)

Since:

  • 0.4.0



113
114
115
 
# File 'lib/acclaim/command/dsl.rb', line 113

def root?
  superclass == Acclaim::Command
end

#run(*arguments) ⇒ Object

Invokes this command with a fresh set of option values.

Since:

  • 0.4.0



78
79
80
81
82
 
# File 'lib/acclaim/command/dsl.rb', line 78

def run(*arguments)
  invoke arguments
rescue Option::Parser::Error => error
  $stderr.puts error.message
end

#subcommands ⇒ Array

Commands which may be given to this command.

Returns:

  • (Array) —

    this command’s subcommands

Since:

  • 0.4.0



33
34
35
 
# File 'lib/acclaim/command/dsl.rb', line 33

def subcommands
  @subcommands ||= []
end