Module: Command::DSL::CommandDefinition

Included in:

Command

Defined in:

lib/command-set/dsl.rb

Overview

These are the methods made available by Command::setup, and thus by DSL::CommandSetDefinition#command

Instance Method Summary

• #action(&block) ⇒ Object

  The core of the Command.

• #document(text) ⇒ Object

  Every command should provide a little text to describe what it does.

• #doesnt_undo ⇒ Object

  Lets the interpreter know that this command intentionally doesn’t provide an undo block - that there’s nothing to undo.

• #format_advice(&block) ⇒ Object

  Used to explain to the formatter subsystem how best to format your output.

• #subject_methods(*methods) ⇒ Object

  See Command::Subject.

• #undo(&block) ⇒ Object

  Commands should either define an undo block (that will reverse whatever their action did) or else call doesnt_undo - for things that don’t change any state.

Instance Method Details

#action(&block) ⇒ Object

The core of the Command. Define a block that performs the command. Within it, you can treat your arguments as readable private attributes and call methods from DSL::Action

# File 'lib/command-set/dsl.rb', line 159

def action(&block)
  define_method(:execute, &block)
end

#document(text) ⇒ Object

Every command should provide a little text to describe what it does. This will be nicely formatted on output, so feel free to use heredocs and indent so that it looks nice in the code.

# File 'lib/command-set/dsl.rb', line 200

def document(text)
  @doc_text = text.gsub(%r{\s+}, " ").strip
end

#doesnt_undo ⇒ Object

Lets the interpreter know that this command intentionally doesn’t provide an undo block - that there’s nothing to undo. Use it for informational commands, primarily. Commands that neither declare that they ‘doesnt_undo’ nor provide an undo block will raise a warning to the user whenever they’re called.

# File 'lib/command-set/dsl.rb', line 183

def doesnt_undo
  define_method(:undoable?) { return true }
  define_method(:join_undo) {}
end

#format_advice(&block) ⇒ Object

Used to explain to the formatter subsystem how best to format your output. It can sometimes be useful to output lots of data, and then use format_advice to eliminate and shuffle it around.

For more information see Command::Formatter::FormatAdvisor

# File 'lib/command-set/dsl.rb', line 193

def format_advice(&block)
  @advice_block = proc &block
end

#subject_methods(*methods) ⇒ Object

See Command::Subject. If this command will make use of fields of the subject, it must declare them using subject_methods. You’re then guaranteed that the subject will either have those fields defined, or an error will be thrown at runtime. Pass a list of symbols, as you would to Class#attribute

# File 'lib/command-set/dsl.rb', line 152

def subject_methods(*methods)
  @subject_requirements += [*methods]
end

#undo(&block) ⇒ Object

Commands should either define an undo block (that will reverse whatever their action did) or else call doesnt_undo - for things that don’t change any state.

One particularly useful feature is that each invocation is it’s own object, so you can set instance variables to save the old state if you want.

# File 'lib/command-set/dsl.rb', line 170

def undo(&block)
  define_method(:undo, &block)
  define_method(:undoable?) do
    return true
  end
  subject_requirements << :undo_stack
end