Module: Rap::Declarations

Included in:
Rap, Task
Defined in:
lib/rap/declarations.rb,
lib/rap/declarations/context.rb

Overview

Defines the Rap task declaration methods. They may be included at the top level (like Rake) or used through Rap.

Usage

Unlike in rake, task will define actual task classes according to the task names. Task classes may be nested within modules using namespace. For example:

t = Rap.task(:sample)                  
t.class                            # => Sample

Rap.namespace(:nested) do
  t = Rap.task(:sample)                
  t.class                          # => Nested::Sample
end

Normally all declared tasks are subclasses of Rap::Task, but subclasses of Rap::Task can declare tasks as well.

class Subclass < Rap::Task
end

include Rap::Declarations

desc "task one, a subclass of Rap::Task"
o = Rap.task(:one)
o.class                            # => One
o.class.superclass                 # => Rap::Task
o.class.desc.to_s                  # => "task one, a subclass of Rap::Task"

namespace(:nest) do
  desc "task two, a nested subclass of Subclass"
  t = Subclass.task(:two)
  t.class                          # => Nest::Two
  t.class.superclass               # => Subclass
  t.class.desc.to_s                # => "task two, a nested subclass of Subclass"
end

This feature is only available to subclasses of Rap::Task and can be very useful for creating inheritance hierarchies. Note that other declaration methods like ‘desc’ and ‘namespace’ are not available on Rap::Task or subclasses, just ‘task’.

See the Syntax Reference for more information.

Defined Under Namespace

Classes: Context

Instance Method Summary collapse

Instance Method Details

#app ⇒ Object

Returns the context app.



54
55
56
 
# File 'lib/rap/declarations.rb', line 54

def app
  context.app
end

#desc(str) ⇒ Object

Sets the description for use by the next task declaration.



103
104
105
 
# File 'lib/rap/declarations.rb', line 103

def desc(str)
  context.desc = str
end

#instance(klass) ⇒ Object

Returns the instance for the class, registered to app.



59
60
61
 
# File 'lib/rap/declarations.rb', line 59

def instance(klass)
  klass.instance(app)
end

#namespace(name) ⇒ Object

Nests tasks within the named module for the duration of the block. Namespaces may be nested.



95
96
97
98
99
100
 
# File 'lib/rap/declarations.rb', line 95

def namespace(name)
  previous_namespace = context.namespace
  context.namespace = File.join(previous_namespace, name.to_s.underscore)
  yield
  context.namespace = previous_namespace
end

#task(*args, &action) ⇒ Object

Declares a task with a rake-like syntax. Task generates a subclass of Rap::Task, nested within the current namespace.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/rap/declarations.rb', line 65

def task(*args, &action)
  # resolve arguments and declare unknown dependencies
  name, configs, dependencies, arg_names = resolve_args(args) do |dependency| 
    register Rap::Task.subclass(dependency)
  end
  
  # generate the task class
  const_name = File.join(context.namespace, name.to_s).camelize
  tasc = declaration_class.subclass(const_name, configs, dependencies)
  register tasc
  
  # register documentation
  desc = Lazydoc.register_caller(Description)
  desc.desc = context.desc
  context.desc = nil
  
  tasc.arg_names = arg_names
  tasc.desc = desc
  
  # add the action
  tasc.actions << action if action
  
  # return the instance
  instance = tasc.instance(app)
  instance.config.import(configs)
  instance
end