Module: Command::DSL::CommandDefinition

Includes:
Argument
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 collapse

Methods included from Argument

#alternating_argument, #argument, argument_typemap, #create, #create_decorator, document, #named_optionals, register_argument, register_decorator, #special_argument, #subject

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



411
412
413
 
# File 'lib/command-set/dsl.rb', line 411

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.



452
453
454
 
# File 'lib/command-set/dsl.rb', line 452

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.



435
436
437
438
 
# File 'lib/command-set/dsl.rb', line 435

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



445
446
447
 
# File 'lib/command-set/dsl.rb', line 445

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

#parent_argument(name) ⇒ Object

Creates a parent argument reference: an argument that references an argument from a subcommand. This lets a subcommand collect the arguments common to its commands and do two things: make command line calls more natural (box grape_box add grapes instead of box add grape_box grapes) and also make modes more useful, since they can collect the arguments that would otherwise be repeated when the mode is started.



397
398
399
400
 
# File 'lib/command-set/dsl.rb', line 397

def parent_argument(name)
  name = name.to_s
  @parent_arguments << name.to_s
end

#parent_arguments(*names) ⇒ Object 



402
403
404
405
406
 
# File 'lib/command-set/dsl.rb', line 402

def parent_arguments(*names)
  names.each do |name|
    parent_argument(name)
  end
end

#subject_methods(*methods) ⇒ Object Also known as: subject_method

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



385
386
387
 
# File 'lib/command-set/dsl.rb', line 385

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.



422
423
424
425
426
427
428
 
# File 'lib/command-set/dsl.rb', line 422

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