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



415
416
417
 
# File 'lib/command-set/dsl.rb', line 415

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.



456
457
458
 
# File 'lib/command-set/dsl.rb', line 456

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.



439
440
441
442
 
# File 'lib/command-set/dsl.rb', line 439

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



449
450
451
 
# File 'lib/command-set/dsl.rb', line 449

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.



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

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

#parent_arguments(*names) ⇒ Object 



406
407
408
409
410
 
# File 'lib/command-set/dsl.rb', line 406

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



389
390
391
 
# File 'lib/command-set/dsl.rb', line 389

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.



426
427
428
429
430
431
432
 
# File 'lib/command-set/dsl.rb', line 426

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