Class YARD::CodeObjects::MacroObject
In: lib/yard/code_objects/macro_object.rb
Parent: Base

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

Methods

apply   apply_macro   attached?   create   expand   expand   find   find_or_create   path   sep  

Constants

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

External Aliases

find_or_create -> create_docstring

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

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

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

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

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})

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

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.

Public Instance methods

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

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

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

Overrides the separator to be ’.’

[Validate]