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)

Class Method Summary (collapse)

Instance Method Summary (collapse)

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

- (Docstring) base_docstring (readonly) Originally defined in class Base

The non-localized documentation string associated with the object

Since:

  • 0.8.4

- (Boolean) dynamic Originally defined in class Base

Marks whether or not the method is conditionally defined at runtime

- (Array<String>) files (readonly) Originally defined in class Base

The files the object was defined in. To add a file, use #add_file.

See Also:

- (String) group Originally defined in class Base

Returns the group this object is associated with

Since:

  • 0.6.0

- (String) macro_data



142
143
144
# File 'lib/yard/code_objects/macro_object.rb', line 142

def macro_data
  @macro_data
end

- (CodeObjects::Base) method_object



146
147
148
# File 'lib/yard/code_objects/macro_object.rb', line 146

def method_object
  @method_object
end

- (NamespaceObject) namespace Also known as: parent Originally defined in class Base

The namespace the object is defined in. If the object is in the top level namespace, this is Registry.root

- (String) signature Originally defined in class Base

The one line signature representing an object. For a method, this will be of the form “def meth(arguments…)”. This is usually the first source line.

- (String?) source Originally defined in class Base

The source code associated with the object

- (Symbol) source_type Originally defined in class Base

Language of the source code associated with the object. Defaults to :ruby.

- (Symbol) visibility Originally defined in class Base

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
124
125
126
127
128
# File 'lib/yard/code_objects/macro_object.rb', line 120

def apply(docstring, call_params = [], full_source = '', block_source = '', method_object = nil)
  docstring = docstring.all if Docstring === docstring
  parser = Docstring.parser
  handler = OpenStruct.new
  handler.call_params = call_params[1..-1]
  handler.caller_method = call_params.first
  handler.statement = OpenStruct.new(:source => full_source)
  parser.parse(docstring, nil, handler).to_docstring.to_raw
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.



136
137
138
# File 'lib/yard/code_objects/macro_object.rb', line 136

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

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

Creates a new macro and fills in the relevant properties.



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

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



50
51
52
# File 'lib/yard/code_objects/macro_object.rb', line 50

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

+ (MacroObject?) find_or_create(macro_name, 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.



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

def find_or_create(macro_name, data, method_object = nil)
  if macro = find(name)
    macro
  else
    create(macro_name, data, method_object)
  end
end

Instance Method Details

- (Boolean) attached?



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

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:



167
168
169
# File 'lib/yard/code_objects/macro_object.rb', line 167

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

- (Object) path

Overrides Base#path so the macro path is “.macro.MACRONAME”



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

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

- (Object) sep

Overrides the separator to be '.'



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

def sep; '.' end