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<String>) —

    the arguments that remained in the command line

Returns:

  • (Proc, nil) —

    the given block

Since:

  • 0.4.0



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

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

#command_ancestors ⇒ Array<Acclaim::Command::DSL] this command's parent commands

Returns all command ancestors of this command.

Returns:

  • (Array<Acclaim::Command::DSL] this command's parent commands) —

    Array<Acclaim::Command::DSL] this command’s parent commands

Since:

  • 0.4.0



144
145
146
 
# File 'lib/acclaim/command/dsl.rb', line 144

def command_ancestors
  ancestors - Acclaim::Command.ancestors
end

#command_path ⇒ Array<Acclaim::Command::DSL>

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

Returns:

Since:

  • 0.4.0



166
167
168
 
# File 'lib/acclaim/command/dsl.rb', line 166

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.

Parameters:

  • options (Ribbon::Wrapper) —

    ribbon containing options and values

  • arguments (Array<String>) (defaults to: []) —

    additional arguments to the program

Since:

  • 0.4.0



133
134
135
136
137
 
# File 'lib/acclaim/command/dsl.rb', line 133

def execute(options, arguments = [])
  action.instance_eval do
    call options, arguments if respond_to? :call
  end
end

#full_line(options = {}) ⇒ Object

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

Examples:

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"

Parameters:

  • options (Hash, Ribbon, Ribbon::Wrapper) (defaults to: {}) —

    method options

Options Hash (options):

  • :include_root (true, false) — default: false —

    whether to include the root command in the full command line

Since:

  • 0.4.0



190
191
192
193
194
195
 
# File 'lib/acclaim/command/dsl.rb', line 190

def full_line(options = {})
  options = Ribbon.wrap options
  command_path.tap do |path|
    path.shift unless options.include_root?
  end.map(&:line).join ' '
end

#invoke(arguments = []) ⇒ Object

Note:

Argument separators will be deleted prior to command execution.

Searches the given arguments for subcommands and invokes it. If none were found, executes this command instead.

The arguments will be parsed using all options from this command and its parents.

Parameters:

  • arguments (Array<String>) (defaults to: []) —

    the argument array

Since:

  • 0.4.0



116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/acclaim/command/dsl.rb', line 116

def invoke(arguments = [])
  subcommand = parse_subcommands_in! arguments
  if subcommand.nil?
    all_options = command_ancestors.collect(&:options).flatten
    parsed_options = Option::Parser.new(arguments, all_options).parse!
    delete_argument_separators_in! arguments
    execute parsed_options, arguments
  else
    subcommand.invoke arguments
  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



36
37
38
39
 
# File 'lib/acclaim/command/dsl.rb', line 36

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



58
59
60
 
# File 'lib/acclaim/command/dsl.rb', line 58

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

#options ⇒ Array<Acclaim::Option>

The options this command can take.

Returns:

Since:

  • 0.4.0



51
52
53
 
# File 'lib/acclaim/command/dsl.rb', line 51

def options
  @options ||= []
end

#parse_options_in!(arguments) ⇒ Ribbon::Wrapper

Parses the given arguments using this command’s set of options.

Parameters:

  • arguments (Array<String>) —

    the argument array

Returns:

  • (Ribbon::Wrapper) —

    ribbon containing the values

Since:

  • 0.4.0



82
83
84
 
# File 'lib/acclaim/command/dsl.rb', line 82

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

#parse_subcommands_in!(arguments) ⇒ Acclaim::Command::DSL?

Searches the given arguments for one of this command’s subcommands.

Parameters:

  • arguments (Array<String>) —

    the argument array

Returns:

Since:

  • 0.4.0



91
92
93
 
# File 'lib/acclaim/command/dsl.rb', line 91

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

#root ⇒ Acclaim::Command::DSL

Returns the root of the command hierarchy.

Returns:

Since:

  • 0.4.0



151
152
153
 
# File 'lib/acclaim/command/dsl.rb', line 151

def root
  command_ancestors.last
end

#root? ⇒ true, false

Whether this is a top-level command.

Returns:

  • (true, false) —

    whether this command is at the root of the hierarchy

Since:

  • 0.4.0



159
160
161
 
# File 'lib/acclaim/command/dsl.rb', line 159

def root?
  self == root
end

#run(*arguments) ⇒ Object

Invokes this command with the given arguments. Outputs parser error messages to the standard error stream.

Parameters:

  • arguments (Array<String>) —

    the argument array

See Also:

Since:

  • 0.4.0



101
102
103
104
105
 
# File 'lib/acclaim/command/dsl.rb', line 101

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

#subcommands ⇒ Array<Acclaim::Command::DSL>

Commands which may be given to this command.

Returns:

Since:

  • 0.4.0



44
45
46
 
# File 'lib/acclaim/command/dsl.rb', line 44

def subcommands
  @subcommands ||= []
end