Class: YARD::CodeObjects::MacroObject
- Inherits:
-
Base
- Object
- Base
- YARD::CodeObjects::MacroObject
- 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.
Constant Summary
- MACRO_MATCH =
/(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/
Instance Attribute Summary (collapse)
-
- (Docstring) base_docstring
inherited
from Base
readonly
The non-localized documentation string associated with the object.
-
- (Boolean) dynamic
inherited
from Base
Marks whether or not the method is conditionally defined at runtime.
-
- (Array<String>) files
inherited
from Base
readonly
The files the object was defined in.
-
- (String) group
inherited
from Base
The group this object is associated with.
-
- (String) macro_data
The macro data stored on the object.
-
- (CodeObjects::Base) method_object
The method object that this macro is attached to.
-
- (NamespaceObject) namespace
(also: #parent)
inherited
from Base
The namespace the object is defined in.
-
- (String) signature
inherited
from Base
The one line signature representing an object.
-
- (String?) source
inherited
from Base
The source code associated with the object.
-
- (Symbol) source_type
inherited
from Base
Language of the source code associated with the object.
-
- (Symbol) visibility
inherited
from Base
The visibility of an object (:public, :private, :protected).
Class Method Summary (collapse)
-
+ (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.
-
+ (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.
-
+ (MacroObject) create(macro_name, data, method_object = nil)
Creates a new macro and fills in the relevant properties.
-
+ (Object) expand(macro_data, call_params = [], full_source = '', block_source = '')
Expands macro_data using the interpolation parameters.
-
+ (MacroObject?) find(macro_name)
Finds a macro using macro_name.
-
+ (MacroObject?) find_or_create(macro_name, data, method_object = nil)
(also: create_docstring)
Parses a given docstring and determines if the macro is "new" or not.
Instance Method Summary (collapse)
-
- (Boolean) attached?
Whether this macro is attached to a method.
-
- (Object) expand(call_params = [], full_source = '', block_source = '')
Expands the macro using.
-
- (Object) path
Overrides Base#path so the macro path is ".macro.MACRONAME".
-
- (Object) sep
Overrides the separator to be '.'.
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
- (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.
- (String) macro_data
Returns the macro data stored on the object
142 143 144 |
# File 'lib/yard/code_objects/macro_object.rb', line 142 def macro_data @macro_data end |
- (CodeObjects::Base) method_object
Returns the method object that this macro is attached to.
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.
- (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
Returns the visibility of an object (:public, :private, :protected)
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.
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 (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?
Returns whether this macro is attached to a method
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
167 168 169 |
# File 'lib/yard/code_objects/macro_object.rb', line 167 def (call_params = [], full_source = '', block_source = '') self.class.(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 |