Class: Diecut::PluginDescription

Inherits:
Object
  • Object
show all
Includes:
CallerLocationsPolyfill
Defined in:
lib/diecut/plugin-description.rb,
lib/diecut/plugin-description/option.rb,
lib/diecut/plugin-description/context-default.rb

Defined Under Namespace

Classes: ContextDefault, KindStem, Option

Constant Summary collapse

NO_VALUE = 
Object.new.freeze

Constants included from CallerLocationsPolyfill

CallerLocationsPolyfill::LINE_RE

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from CallerLocationsPolyfill

#caller_locations

Constructor Details

#initialize(name, source_path) ⇒ PluginDescription

Returns a new instance of PluginDescription.



13
14
15
16
17
18
19
20
21
 
# File 'lib/diecut/plugin-description.rb', line 13

def initialize(name, source_path)
  @name = name
  @source_path = source_path
  @default_activated = true
  @context_defaults = []
  @options = []
  @resolve_block = nil
  @kind_stems = {}
end

Instance Attribute Details

#context_defaults ⇒ Object (readonly)

Returns the value of attribute context_defaults.



22
23
24
 
# File 'lib/diecut/plugin-description.rb', line 22

def context_defaults
  @context_defaults
end

#default_activated ⇒ Object (readonly)

Returns the value of attribute default_activated.



22
23
24
 
# File 'lib/diecut/plugin-description.rb', line 22

def default_activated
  @default_activated
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



22
23
24
 
# File 'lib/diecut/plugin-description.rb', line 22

def name
  @name
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



22
23
24
 
# File 'lib/diecut/plugin-description.rb', line 22

def options
  @options
end

#resolve_block ⇒ Object (readonly)

Returns the value of attribute resolve_block.



22
23
24
 
# File 'lib/diecut/plugin-description.rb', line 22

def resolve_block
  @resolve_block
end

#source_path ⇒ Object (readonly)

Returns the value of attribute source_path.



22
23
24
 
# File 'lib/diecut/plugin-description.rb', line 22

def source_path
  @source_path
end

Instance Method Details

#apply_resolve(ui, context) ⇒ Object 



41
42
43
 
# File 'lib/diecut/plugin-description.rb', line 41

def apply_resolve(ui, context)
  @resolve_block.call(ui, context)
end

#default(context_path, value = NO_VALUE, &block) ⇒ Object

Set a default value for a field in the templating context.

Examples:

plugin.default("built_at"){ Time.now }
plugin.default("author", "Judson")

Parameters:

  • context_path (String, Array) —

    Either an array of strings or a dotted string (e.g. “deeply.nested.value”) that describes a path into the templating context to give a default value to.

  • value (defaults to: NO_VALUE) —

    A simple default value, which will be used verbatim (n.b. it will be cloned if appropriate, so you can use [] for an array).

Yield Returns:

  • A computed default value. The block will be called when the context is set up. You cannot use both a simple value and a computed value.



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/diecut/plugin-description.rb', line 104

def default(context_path, value = NO_VALUE, &block)
  context_path =
    case context_path
    when Array
      context_path
    when /.+\..+/ # has an embedded .
      context_path.split('.')
    else
      [context_path]
    end
  if value != NO_VALUE and not block.nil?
    raise InvalidPlugin, "Default on #{name.inspect} both has a simple default value (#{value}) and a dynamic block value, which isn't allowed."
  end
  @context_defaults << ContextDefault.new(context_path, value, block)
end

#default_active? ⇒ Boolean

Returns:

  • (Boolean) 


37
38
39
 
# File 'lib/diecut/plugin-description.rb', line 37

def default_active?
  @default_activated
end

#default_off ⇒ Object

Force this plugin to be enabled to be used. Good for optional features.



76
77
78
 
# File 'lib/diecut/plugin-description.rb', line 76

def default_off
  @default_activated = false
end

#default_on ⇒ Object

Make this plugin part of the generation process by default. The is the default behavior anyway, provided for consistency.



82
83
84
 
# File 'lib/diecut/plugin-description.rb', line 82

def default_on
  @default_activated = true
end

#for_kind(kind, templates = nil, stem = nil) ⇒ Object

Attaches this plugin to a particular kind of diecut generator. Can be called multiple times in order to reuse the plugin.

For instance, you might set up a plugin for Rails that also works in Xing projects that use Rails for a backend

Examples:

Install for Rails and Xing

plugin.for_kind(:rails)
plugin.for_kind(:xing, nil, "xing/backend")

Parameters:

  • kind (String, Symbol) —

    The kind of generator to register the plugin to

  • templates (String) (defaults to: nil) —

    The directory of templates that the plugin adds to the generation process. Relative paths are resolved from the directory the plugin is being defined in. If omitted (or nil) defaults to “templates”

  • stem (Array(String), String) (defaults to: nil) —

    A prefix for the templates directory when it’s used for this kind of generator. By default, this will be [kind], which is what you’ll probably want in a gem plugin. For local plugins, you probably want to have directories per kind, and set this to []



68
69
70
71
72
73
 
# File 'lib/diecut/plugin-description.rb', line 68

def for_kind(kind, templates = nil, stem = nil)
  stem ||= [kind]
  templates ||= "templates"
  templates = File.expand_path(templates, File.dirname(caller_locations(1..1).first.absolute_path))
  @kind_stems[kind] = KindStem.new(kind, stem, templates)
end

#has_kind?(kind) ⇒ Boolean

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/diecut/plugin-description.rb', line 33

def has_kind?(kind)
  @kind_stems.key?(kind)
end

#kinds ⇒ Object 



25
26
27
 
# File 'lib/diecut/plugin-description.rb', line 25

def kinds
  @kind_stems.keys
end

#option(name) {|option| ... } ⇒ Object

Define an option to provide to the user interface.

Parameters:

  • name (String, Symbol) —

    The name for the option, as it’ll be provided to the user.

Yield Parameters:

  • option (Option) —

    The option description object



125
126
127
128
129
130
131
 
# File 'lib/diecut/plugin-description.rb', line 125

def option(name)
  name = name.to_sym
  option = Option.new(name)
  yield option
  @options << option
  return option
end

#resolve(&block) ⇒ Object

The resolve block provides the loophole to allow complete configuration of the rendering context. The last thing that happens before files are generated is that all the plugin resolves are run, so that e.g. values can be calculated from other values. It’s very difficult to analyze resolve blocks, however: use them as sparingly as possible.



143
144
145
 
# File 'lib/diecut/plugin-description.rb', line 143

def resolve(&block)
  @resolve_block = block
end

#stem_for(kind) ⇒ Object 



29
30
31
 
# File 'lib/diecut/plugin-description.rb', line 29

def stem_for(kind)
  @kind_stems.fetch(kind)
end