Module: Capistrano::Configuration::Namespaces

Module | Capistrano::Configuration::Namespaces
In: | lib/capistrano/configuration/namespaces.rb lib/capistrano/configuration/namespaces.rb

### Methods

default_task default_task desc desc find_task find_task fully_qualified_name fully_qualified_name namespace namespace next_description next_description search_task search_task task task task_list task_list top top

### Classes and Modules

Class Capistrano::Configuration::Namespaces::Namespace

### Constants

DEFAULT_TASK | = | :default
DEFAULT_TASK | = | :default

### Attributes

name | [R] | The name of this namespace. Defaults to `nil` for the top-level namespace.
name | [R] | The name of this namespace. Defaults to `nil` for the top-level namespace.
namespaces | [R] | The hash of namespaces defined for this namespace.
namespaces | [R] | The hash of namespaces defined for this namespace.
parent | [R] | The parent namespace of this namespace. Returns `nil` for the top-level namespace.
parent | [R] | The parent namespace of this namespace. Returns `nil` for the top-level namespace.
tasks | [R] | The hash of tasks defined for this namespace.
tasks | [R] | The hash of tasks defined for this namespace.

### Public Instance methods

default_task()

Returns the default task for this namespace. This will be `nil` if the namespace is at the top-level, and will otherwise return the task named "default". If no such task exists, `nil` will be returned.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 150
    150:       def default_task
    151:         return nil if parent.nil?
    152:         return tasks[DEFAULT_TASK]
    153:       end

default_task()

Returns the default task for this namespace. This will be `nil` if the namespace is at the top-level, and will otherwise return the task named "default". If no such task exists, `nil` will be returned.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 150
    150:       def default_task
    151:         return nil if parent.nil?
    152:         return tasks[DEFAULT_TASK]
    153:       end

desc(text)

Describe the next task to be defined. The given text will be attached to the next task that is defined and used as its description.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 50
    50:       def desc(text)
    51:         @next_description = text
    52:       end

desc(text)

Describe the next task to be defined. The given text will be attached to the next task that is defined and used as its description.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 50
    50:       def desc(text)
    51:         @next_description = text
    52:       end

find_task(name)

Find the task with the given name, where name is the fully-qualified name of the task. This will search into the namespaces and return the referenced task, or nil if no such task can be found. If the name refers to a namespace, the task in that namespace named "default" will be returned instead, if one exists.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 113
    113:       def find_task(name)
    114:         parts = name.to_s.split(/:/)
    115:         tail = parts.pop.to_sym
    116:
    117:         ns = self
    118:         until parts.empty?
    119:           next_part = parts.shift
    120:           ns = next_part.empty? ? nil : ns.namespaces[next_part.to_sym]
    121:           return nil if ns.nil?
    122:         end
    123:
    124:         if ns.namespaces.key?(tail)
    125:           ns = ns.namespaces[tail]
    126:           tail = DEFAULT_TASK
    127:         end
    128:
    129:         ns.tasks[tail]
    130:       end

find_task(name)

Find the task with the given name, where name is the fully-qualified name of the task. This will search into the namespaces and return the referenced task, or nil if no such task can be found. If the name refers to a namespace, the task in that namespace named "default" will be returned instead, if one exists.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 113
    113:       def find_task(name)
    114:         parts = name.to_s.split(/:/)
    115:         tail = parts.pop.to_sym
    116:
    117:         ns = self
    118:         until parts.empty?
    119:           next_part = parts.shift
    120:           ns = next_part.empty? ? nil : ns.namespaces[next_part.to_sym]
    121:           return nil if ns.nil?
    122:         end
    123:
    124:         if ns.namespaces.key?(tail)
    125:           ns = ns.namespaces[tail]
    126:           tail = DEFAULT_TASK
    127:         end
    128:
    129:         ns.tasks[tail]
    130:       end

fully_qualified_name()

Returns the fully-qualified name of this namespace, or nil if the namespace is at the top-level.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 43
    43:       def fully_qualified_name
    44:         return nil if name.nil?
    45:         [parent.fully_qualified_name, name].compact.join(":")
    46:       end

fully_qualified_name()

Returns the fully-qualified name of this namespace, or nil if the namespace is at the top-level.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 43
    43:       def fully_qualified_name
    44:         return nil if name.nil?
    45:         [parent.fully_qualified_name, name].compact.join(":")
    46:       end

namespace(name, &block)

Open a namespace in which to define new tasks. If the namespace was defined previously, it will be reopened, otherwise a new namespace will be created for the given name.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 65
    65:       def namespace(name, &block)
    66:         name = name.to_sym
    67:         raise ArgumentError, "expected a block" unless block_given?
    68:
    69:         namespace_already_defined = namespaces.key?(name)
    70:         if all_methods.any? { |m| m.to_sym == name } && !namespace_already_defined
    71:           thing = tasks.key?(name) ? "task" : "method"
    72:           raise ArgumentError, "defining a namespace named `#{name}' would shadow an existing #{thing} with that name"
    73:         end
    74:
    75:         namespaces[name] ||= Namespace.new(name, self)
    76:         namespaces[name].instance_eval(&block)
    77:
    78:         # make sure any open description gets terminated
    79:         namespaces[name].desc(nil)
    80:
    81:         if !namespace_already_defined
    82:           metaclass = class << self; self; end
    83:           metaclass.send(:define_method, name) { namespaces[name] }
    84:         end
    85:       end

namespace(name, &block)

Open a namespace in which to define new tasks. If the namespace was defined previously, it will be reopened, otherwise a new namespace will be created for the given name.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 65
    65:       def namespace(name, &block)
    66:         name = name.to_sym
    67:         raise ArgumentError, "expected a block" unless block_given?
    68:
    69:         namespace_already_defined = namespaces.key?(name)
    70:         if all_methods.any? { |m| m.to_sym == name } && !namespace_already_defined
    71:           thing = tasks.key?(name) ? "task" : "method"
    72:           raise ArgumentError, "defining a namespace named `#{name}' would shadow an existing #{thing} with that name"
    73:         end
    74:
    75:         namespaces[name] ||= Namespace.new(name, self)
    76:         namespaces[name].instance_eval(&block)
    77:
    78:         # make sure any open description gets terminated
    79:         namespaces[name].desc(nil)
    80:
    81:         if !namespace_already_defined
    82:           metaclass = class << self; self; end
    83:           metaclass.send(:define_method, name) { namespaces[name] }
    84:         end
    85:       end

next_description(reset=false)

Returns the value set by the last, pending "desc" call. If `reset` is not false, the value will be reset immediately afterwards.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 56
    56:       def next_description(reset=false)
    57:         @next_description
    58:       ensure
    59:         @next_description = nil if reset
    60:       end

next_description(reset=false)

Returns the value set by the last, pending "desc" call. If `reset` is not false, the value will be reset immediately afterwards.

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 56
    56:       def next_description(reset=false)
    57:         @next_description
    58:       ensure
    59:         @next_description = nil if reset
    60:       end

search_task(name)

Given a task name, this will search the current namespace, and all parent namespaces, looking for a task that matches the name, exactly. It returns the task, if found, or nil, if not.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 135
    135:       def search_task(name)
    136:         name = name.to_sym
    137:         ns = self
    138:
    139:         until ns.nil?
    140:           return ns.tasks[name] if ns.tasks.key?(name)
    141:           ns = ns.parent
    142:         end
    143:
    144:         return nil
    145:       end

search_task(name)

Given a task name, this will search the current namespace, and all parent namespaces, looking for a task that matches the name, exactly. It returns the task, if found, or nil, if not.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 135
    135:       def search_task(name)
    136:         name = name.to_sym
    137:         ns = self
    138:
    139:         until ns.nil?
    140:           return ns.tasks[name] if ns.tasks.key?(name)
    141:           ns = ns.parent
    142:         end
    143:
    144:         return nil
    145:       end

task(name, options={}, &block)

Describe a new task. If a description is active (see desc), it is added to the options under the `:desc` key. The new task is added to the namespace.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 90
     90:       def task(name, options={}, &block)
     91:         name = name.to_sym
     92:         raise ArgumentError, "expected a block" unless block_given?
     93:
     94:         task_already_defined = tasks.key?(name)
     95:         if all_methods.any? { |m| m.to_sym == name } && !task_already_defined
     96:           thing = namespaces.key?(name) ? "namespace" : "method"
     97:           raise ArgumentError, "defining a task named `#{name}' would shadow an existing #{thing} with that name"
     98:         end
     99:
    100:         tasks[name] = TaskDefinition.new(name, self, {:desc => next_description(:reset)}.merge(options), &block)
    101:
    102:         if !task_already_defined
    103:           metaclass = class << self; self; end
    104:           metaclass.send(:define_method, name) { execute_task(tasks[name]) }
    105:         end
    106:       end

task(name, options={}, &block)

Describe a new task. If a description is active (see desc), it is added to the options under the `:desc` key. The new task is added to the namespace.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 90
     90:       def task(name, options={}, &block)
     91:         name = name.to_sym
     92:         raise ArgumentError, "expected a block" unless block_given?
     93:
     94:         task_already_defined = tasks.key?(name)
     95:         if all_methods.any? { |m| m.to_sym == name } && !task_already_defined
     96:           thing = namespaces.key?(name) ? "namespace" : "method"
     97:           raise ArgumentError, "defining a task named `#{name}' would shadow an existing #{thing} with that name"
     98:         end
     99:
    100:         tasks[name] = TaskDefinition.new(name, self, {:desc => next_description(:reset)}.merge(options), &block)
    101:
    102:         if !task_already_defined
    103:           metaclass = class << self; self; end
    104:           metaclass.send(:define_method, name) { execute_task(tasks[name]) }
    105:         end
    106:       end

task_list(all=false)

Returns the tasks in this namespace as an array of TaskDefinition objects. If a non-false parameter is given, all tasks in all namespaces under this namespace will be returned as well.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 158
    158:       def task_list(all=false)
    159:         list = tasks.values
    160:         namespaces.each { |name,space| list.concat(space.task_list(:all)) } if all
    161:         list
    162:       end

task_list(all=false)

Returns the tasks in this namespace as an array of TaskDefinition objects. If a non-false parameter is given, all tasks in all namespaces under this namespace will be returned as well.

[Source]

         # File lib/capistrano/configuration/namespaces.rb, line 158
    158:       def task_list(all=false)
    159:         list = tasks.values
    160:         namespaces.each { |name,space| list.concat(space.task_list(:all)) } if all
    161:         list
    162:       end

top()

Returns the top-level namespace (the one with no parent).

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 36
    36:       def top
    37:         return parent.top if parent
    38:         return self
    39:       end

top()

Returns the top-level namespace (the one with no parent).

[Source]

        # File lib/capistrano/configuration/namespaces.rb, line 36
    36:       def top
    37:         return parent.top if parent
    38:         return self
    39:       end

[Validate]