Class: YARD::CodeObjects::MacroObject

Inherits:
Base
  • Object
show all
Defined in:
lib/yard/code_objects/macro_object.rb

Overview

A MacroObject represents a docstring defined through @macro NAME and can be reused by specifying the tag @macro NAME. You can also provide the attached type flag to the macro definition to have it attached to the specific DSL method so it will be implicitly reused.

Macros are fully described in the Tags Overview document.

Examples:

Creating a basic named macro

# @macro prop
# @method $1(${3-})
# @return [$2] the value of the $0
property :foo, String, :a, :b

# @macro prop
property :bar, Numeric, :value

Creating a macro that is attached to the method call

# @macro [attach] prop2
# @method $1(value)
property :foo

# Extra data added to docstring
property :bar

Constant Summary

MACRO_MATCH =
/(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/

Instance Attribute Summary (collapse)

Attributes inherited from Base

#docstring, #dynamic, #files, #group, #namespace, #signature, #source, #source_type, #visibility

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from Base

===, #[], #[]=, #add_file, #dynamic?, #equal?, #file, #format, #format_source, #has_tag?, #hash, #initialize, #inspect, #line, #method_missing, #name, new, #relative_path, #root?, #tag, #tags, #type

Constructor Details

This class inherits a constructor from YARD::CodeObjects::Base

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class YARD::CodeObjects::Base

Instance Attribute Details

- (String) macro_data



189
190
191
# File 'lib/yard/code_objects/macro_object.rb', line 189

def macro_data
  @macro_data
end

- (CodeObjects::Base) method_object



193
194
195
# File 'lib/yard/code_objects/macro_object.rb', line 193

def method_object
  @method_object
end

Class Method Details

+ (String) apply(docstring, call_params = [], full_source = '', block_source = '', method_object = nil)

Applies a macro on a docstring by creating any macro data inside of the docstring first. Equivalent to calling find_or_create and apply_macro on the new macro object.

See Also:



120
121
122
123
# File 'lib/yard/code_objects/macro_object.rb', line 120

def apply(docstring, call_params = [], full_source = '', block_source = '', method_object = nil)
  macro = find_or_create(docstring, method_object)
  apply_macro(macro, docstring, call_params, full_source, block_source)
end

+ (String) apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '')

Applies a macro to a docstring, interpolating the macro's data on the docstring and appending any extra local docstring data that was in the original docstring object.



131
132
133
134
135
136
137
138
139
140
# File 'lib/yard/code_objects/macro_object.rb', line 131

def apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '')
  docstring = Docstring.new(docstring) unless Docstring === docstring
  data = []
  data << macro.expand(call_params, full_source, block_source) if macro
  if !macro && new_macro?(docstring)
    data << expand(macro_data(docstring), call_params, full_source, block_source)
  end
  data << nonmacro_data(docstring)
  data.join("\n").strip
end

+ (MacroObject) create(macro_name, data, method_object = nil)

Creates a new macro and fills in the relevant properties.



37
38
39
40
41
42
# File 'lib/yard/code_objects/macro_object.rb', line 37

def create(macro_name, data, method_object = nil)
  obj = new(:root, macro_name)
  obj.macro_data = data
  obj.method_object = method_object
  obj
end

+ (Object) expand(macro_data, call_params = [], full_source = '', block_source = '')

Expands macro_data using the interpolation parameters.

Interpolation rules:

  • $0, $1, $2, … = the Nth parameter in call_params

  • $* = the full statement source (excluding block)

  • Also supports ${N-M} ranges, as well as negative indexes on N or M

  • Use $ to escape the variable name in a macro.



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# File 'lib/yard/code_objects/macro_object.rb', line 96

def expand(macro_data, call_params = [], full_source = '', block_source = '')
  macro_data = macro_data.all if macro_data.is_a?(Docstring)
  macro_data.gsub(MACRO_MATCH) do
    escape, first, last, rng = $1, $2 || $5, $4, $3 ? true : false
    next $&[1..-1] if escape
    if first == '*'
      last ? $& : full_source
    else
      first_i = first.to_i
      last_i = (last ? last.to_i : call_params.size)
      last_i = first_i unless rng
      params = call_params[first_i..last_i]
      params ? params.join(", ") : ''
    end
  end
end

+ (MacroObject?) find(macro_name)

Finds a macro using macro_name



47
48
49
# File 'lib/yard/code_objects/macro_object.rb', line 47

def find(macro_name)
  Registry.at('.macro.' + macro_name.to_s)
end

+ (MacroObject?) find_or_create(data, method_object = nil) Also known as: create_docstring

Parses a given docstring and determines if the macro is “new” or not. If the macro has $variable names or if it has a @macro tag with the [new] or [attached] flag, it is considered new.

If a new macro is found, the macro is created and registered. Otherwise the macro name is searched and returned. If a macro is not found, nil is returned.



66
67
68
69
70
71
72
73
74
75
76
# File 'lib/yard/code_objects/macro_object.rb', line 66

def find_or_create(data, method_object = nil)
  docstring = Docstring === data ? data : Docstring.new(data)
  return unless docstring.tag(:macro)
  return unless name = macro_name(docstring)
  if new_macro?(docstring)
    method_object = nil unless attached_macro?(docstring, method_object)
    create(name, macro_data(docstring), method_object)
  else
    find(name)
  end
end

Instance Method Details

- (Boolean) attached?



196
# File 'lib/yard/code_objects/macro_object.rb', line 196

def attached?; method_object ? true : false end

- (Object) expand(call_params = [], full_source = '', block_source = '')

Expands the macro using

Examples:

Expanding a Macro

macro.expand(%w(property foo bar), 'property :foo, :bar', '') #=>
  "...macro data interpolating this line of code..."

See Also:



210
211
212
# File 'lib/yard/code_objects/macro_object.rb', line 210

def expand(call_params = [], full_source = '', block_source = '')
  self.class.expand(macro_data, call_params, full_source, block_source)
end

- (Object) path



197
# File 'lib/yard/code_objects/macro_object.rb', line 197

def path; '.macro.' + name.to_s end

- (Object) sep



198
# File 'lib/yard/code_objects/macro_object.rb', line 198

def sep; '.' end