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
MACRO_MATCH | = | /(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/ |
find_or_create | -> | create_docstring |
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. |
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:
@!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.
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