class YARD::CodeObjects::MacroObject

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 {file:docs/Tags.md#macro Tags Overview} document.

@example 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

@example 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

Constants

MACRO_MATCH

Attributes

macro_data[RW]

@return [String] the macro data stored on the object

method_object[RW]

@return [CodeObjects::Base] the method object that this macro is

attached to.

Public Class Methods

apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) click to toggle source

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.

@param [Docstring] docstring the docstring to create a macro out of @!macro macro.expand @see find_or_create

# File lib/yard/code_objects/macro_object.rb, line 120
def apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) # rubocop:disable Lint/UnusedMethodArgument
  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
apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') click to toggle 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.

@param [MacroObject] macro the macro object @!macro macro.expand

# File lib/yard/code_objects/macro_object.rb, line 136
def apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') # rubocop:disable Lint/UnusedMethodArgument
  apply(docstring, call_params, full_source, block_source)
end
create(macro_name, data, method_object = nil) click to toggle source

Creates a new macro and fills in the relevant properties. @param [String] macro_name the name of the macro, must be unique. @param [String] data the data the macro should expand when re-used @param [CodeObjects::Base] method_object an object to attach this

macro to. If supplied, {#attached?} will be true

@return [MacroObject] the newly created object

# File lib/yard/code_objects/macro_object.rb, line 40
def create(macro_name, data, method_object = nil)
  obj = new(:root, macro_name)
  obj.macro_data = data
  obj.method_object = method_object
  obj
end
create_docstring(macro_name, data, method_object = nil)
Alias for: find_or_create
expand(macro_data, call_params = [], full_source = '', block_source = '') click to toggle 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.

@!macro [new] macro.expand

@param [Array<String>] call_params the method name and parameters
  to the method call. These arguments will fill \$0-N
@param [String] full_source the full source line (excluding block)
  interpolated as \$*
@param [String] block_source Currently unused. Will support
  interpolating the block data as a variable.
@return [String] the expanded macro data

@param [String] macro_data the macro data to expand (taken from {#macro_data})

# File lib/yard/code_objects/macro_object.rb, line 93
def expand(macro_data, call_params = [], full_source = '', block_source = '') # rubocop:disable Lint/UnusedMethodArgument
  macro_data = macro_data.all if macro_data.is_a?(Docstring)
  macro_data.gsub(MACRO_MATCH) do
    escape = $1
    first = $2 || $5
    last = $4
    rng = $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
find(macro_name) click to toggle source

Finds a macro using macro_name @param [#to_s] macro_name the name of the macro @return [MacroObject] if a macro is found @return [nil] if there is no registered macro by that name

# File lib/yard/code_objects/macro_object.rb, line 51
def find(macro_name)
  Registry.at('.macro.' + macro_name.to_s)
end
find_or_create(macro_name, data, method_object = nil) click to toggle source

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.

@param [#to_s] macro_name the name of the macro @param [CodeObjects::Base] method_object an optional method to attach

the macro to. Only used if the macro is being created, otherwise
this argument is ignored.

@return [MacroObject] the newly created or existing macro, depending

on whether the @!macro tag was a new tag or not.

@return [nil] if the data has no macro tag or if the macro is

not new and no macro by the macro name is found.
# File lib/yard/code_objects/macro_object.rb, line 71
def find_or_create(macro_name, data, method_object = nil)
  find(name) || create(macro_name, data, method_object)
end
Also aliased as: create_docstring

Public Instance Methods

attached?() click to toggle source

@return [Boolean] whether this macro is attached to a method

# File lib/yard/code_objects/macro_object.rb, line 149
def attached?; method_object ? true : false end
expand(call_params = [], full_source = '', block_source = '') click to toggle source

Expands the macro using @param [Array<String>] call_params a list of tokens that are passed

to the method call

@param [String] full_source the full method call (not including the block) @param [String] block_source the source passed in the block of the method

call, if there is a block.

@example Expanding a Macro

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

@see expand

# 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
path() click to toggle source

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

# File lib/yard/code_objects/macro_object.rb, line 152
def path; '.macro.' + name.to_s end
sep() click to toggle source

Overrides the separator to be ‘.’

# File lib/yard/code_objects/macro_object.rb, line 155
def sep; '.' end