Module: Rap::Declarations

Includes:
Utils
Included in:
Rap, DeclarationTask
Defined in:
lib/rap/declarations.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. It’s VERY important to realize this is the case both to aid in thing like testing and to prevent namespace conflicts. 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 DeclarationTask, but subclasses of DeclarationTask can declare tasks as well.

class Alt < DeclarationTask
end

include Rap::Declarations

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

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

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

See the Syntax Reference for more information.

Constant Summary collapse

@@current_namespace = 
''
@@current_desc = 
nil

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utils

#sh

Class Method Details

.app ⇒ Object

The declaration App (default Tap::App.instance)



64
 
# File 'lib/rap/declarations.rb', line 64

def Declarations.app() @@app ||= Tap::App.instance; end

.app=(app) ⇒ Object

Sets the declaration App.



67
 
# File 'lib/rap/declarations.rb', line 67

def Declarations.app=(app) @@app=app; end

.current_desc ⇒ Object

Tracks the current description, which will be used to document the next task declaration.



75
 
# File 'lib/rap/declarations.rb', line 75

def Declarations.current_desc() @@current_desc; end

.current_namespace ⇒ Object

The base constant for all task declarations, prepended to the task name.



70
 
# File 'lib/rap/declarations.rb', line 70

def Declarations.current_namespace() @@current_namespace; end

.env ⇒ Object

The environment in which declared task classes are registered. By default a Tap::Env for Dir.pwd.



58
 
# File 'lib/rap/declarations.rb', line 58

def Declarations.env() @@env ||= Tap::Env.new; end

.env=(env) ⇒ Object

Sets the declaration environment.



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

def Declarations.env=(env) @@env=env; end

.instance(tasc) ⇒ Object

Returns the instance of the task class in app.



79
80
81
 
# File 'lib/rap/declarations.rb', line 79

def Declarations.instance(tasc)
  tasc.instance(Declarations.app)
end

Instance Method Details

#desc(str) ⇒ Object

Sets the description for use by the next task declaration.



126
127
128
 
# File 'lib/rap/declarations.rb', line 126

def desc(str)
  @@current_desc = str
end

#namespace(name) ⇒ Object

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



118
119
120
121
122
123
 
# File 'lib/rap/declarations.rb', line 118

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

#task(*args, &action) ⇒ Object

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



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/rap/declarations.rb', line 85

def task(*args, &action)
  # resolve arguments and declare unknown dependencies
  name, configs, dependencies, arg_names = resolve_args(args) do |dependency| 
    register DeclarationTask.subclass(dependency)
  end
  
  # generate the task class
  const_name = File.join(@@current_namespace, name.to_s).camelize
  tasc = declaration_class.subclass(const_name, configs, dependencies)
  
  # register documentation        
  desc = Lazydoc.register_caller(Description)
  desc.desc = @@current_desc
  @@current_desc = nil
  
  tasc.arg_names = arg_names
  tasc.desc = desc
  tasc.source_file = desc.document.source_file
  
  # add the action
  tasc.actions << action if action
  
  # register
  register tasc
  
  # return the instance
  instance = Declarations.instance(tasc)
  instance.config.bind(instance, true)
  instance
end