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



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

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.



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

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.



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

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



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

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.

Raises:



378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/command-set/dsl.rb', line 378

def parent_argument(name)
  name = name.to_s
  search_in = parent
  until (search_in = search_in.parent()).nil? do
    found = parent.argument_list.find do |argument|
      argument.names.include? name
    end
    unless found.nil?
      arg = found
      @parent_arguments << found
      return
    end
  end
  raise CommandError, "No parent has an argument named \"#{name}\""
end

#parent_arguments(*names) ⇒ Object 



394
395
396
397
398
 
# File 'lib/command-set/dsl.rb', line 394

def parent_arguments(*names)
  names.each do |name|
    parent_argument(name)
  end
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



366
367
368
 
# File 'lib/command-set/dsl.rb', line 366

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.



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

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