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)
-
- (String) macro_data
The macro data stored on the object.
-
- (CodeObjects::Base) method_object
The method object that this macro is attached to.
Attributes inherited from Base
docstring, dynamic, files, group, namespace, signature, source, source_type, visibility
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.
-
+ (String) 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(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
- - (Object) sep
Methods inherited from Base
===, #[], #[]=, #add_file, #dynamic?, #equal?, #file, #format, #format_source, #has_tag?, #hash, #initialize, #inspect, #line, #method_missing, #name, new, #relative_path, #root?, #tag, #tags, #to_ary, #type
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
- (String) macro_data
The macro data stored on the object
189 190 191 |
# File 'lib/yard/code_objects/macro_object.rb', line 189 def macro_data @macro_data end |
- (CodeObjects::Base) method_object
The method object that this macro is attached to.
193 194 195 |
# File 'lib/yard/code_objects/macro_object.rb', line 193 def method_object @method_object end |
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 |
# File 'lib/yard/code_objects/macro_object.rb', line 120 def apply(docstring, call_params = [], full_source = '', block_source = '', method_object = nil) macro = find_or_create(docstring, method_object) apply_macro(macro, docstring, call_params, full_source, block_source) 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.
131 132 133 134 135 136 137 138 139 140 |
# File 'lib/yard/code_objects/macro_object.rb', line 131 def apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') docstring = Docstring.new(docstring) unless Docstring === docstring data = [] data << macro.(call_params, full_source, block_source) if macro if !macro && new_macro?(docstring) data << (macro_data(docstring), call_params, full_source, block_source) end data << nonmacro_data(docstring) data.join("\n").strip end |
+ (MacroObject) create(macro_name, data, method_object = nil)
Creates a new macro and fills in the relevant properties.
37 38 39 40 41 42 |
# File 'lib/yard/code_objects/macro_object.rb', line 37 def create(macro_name, data, method_object = nil) obj = new(:root, macro_name) obj.macro_data = data obj.method_object = method_object obj end |
+ (String) 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
47 48 49 |
# File 'lib/yard/code_objects/macro_object.rb', line 47 def find(macro_name) Registry.at('.macro.' + macro_name.to_s) end |
+ (MacroObject?) find_or_create(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.
66 67 68 69 70 71 72 73 74 75 76 |
# File 'lib/yard/code_objects/macro_object.rb', line 66 def find_or_create(data, method_object = nil) docstring = Docstring === data ? data : Docstring.new(data) return unless docstring.tag(:macro) return unless name = macro_name(docstring) if new_macro?(docstring) method_object = nil unless attached_macro?(docstring, method_object) create(name, macro_data(docstring), method_object) else find(name) end end |
Instance Method Details
- (Boolean) attached?
Whether this macro is attached to a method
196 |
# File 'lib/yard/code_objects/macro_object.rb', line 196 def attached?; method_object ? true : false end |
- (Object) expand(call_params = [], full_source = '', block_source = '')
Expands the macro using
210 211 212 |
# File 'lib/yard/code_objects/macro_object.rb', line 210 def (call_params = [], full_source = '', block_source = '') self.class.(macro_data, call_params, full_source, block_source) end |
- (Object) path
197 |
# File 'lib/yard/code_objects/macro_object.rb', line 197 def path; '.macro.' + name.to_s end |
- (Object) sep
198 |
# File 'lib/yard/code_objects/macro_object.rb', line 198 def sep; '.' end |