Class: YARD::CodeObjects::MacroObject

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Base`
Instance Chain: self, `Base`
Inherits:	YARD::CodeObjects::Base Object YARD::CodeObjects::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 {YARD::Tags Overview} document.

Examples:

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

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

Constant Summary

MACRO_MATCH =
# File 'lib/yard/code_objects/macro_object.rb', line 31
```
/(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/
```

Class Method Summary

.apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) ⇒ String

Applies a macro on a docstring by creating any macro data inside of the docstring first.
.apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') ⇒ String

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.
.create(macro_name, data, method_object = nil) ⇒ MacroObject

Creates a new macro and fills in the relevant properties.
.create_docstring(macro_name, data, method_object = nil)

Alias for .find_or_create.
.expand(macro_data, call_params = [], full_source = '', block_source = '')

Expands #macro_data using the interpolation parameters.
.find(macro_name) ⇒ MacroObject^?

Finds a macro using macro_name.
.find_or_create(macro_name, data, method_object = nil) ⇒ MacroObject^? (also: .create_docstring)

Parses a given docstring and determines if the macro is "new" or not.

`Base` - Inherited

.===	Compares the class with subclasses.
.new	Allocates a new code object.

Instance Attribute Summary

#attached? ⇒ Boolean readonly
#macro_data ⇒ String rw
#method_object ⇒ CodeObjects::Base rw

`Base` - Inherited

#base_docstring	The non-localized documentation string associated with the object.
#dynamic	Marks whether or not the method is conditionally defined at runtime.
#dynamic?	Is the object defined conditionally at runtime?
#files	The files the object was defined in.
#group,
#namespace	The namespace the object is defined in.
#namespace=	Sets the namespace the object is defined in.
#parent	Alias for Base#namespace.
#root?,
#signature	The one line signature representing an object.
#source	The source code associated with the object.
#source=	Attaches source code to a code object with an optional file location.
#source_type	Language of the source code associated with the object.
#visibility, #visibility=

Instance Method Summary

#expand(call_params = [], full_source = '', block_source = '')

Expands the macro using.
#path

Overrides Base#path so the macro path is ".macro.MACRONAME".
#sep

Overrides the separator to be '.'.

`Base` - Inherited

#==	Alias for Base#equal?.
#[]	Accesses a custom attribute on the object.
#[]=	Sets a custom attribute on the object.
#add_file	Associates a file with a code object, optionally adding the line where it was defined.
#add_tag	Add tags to the `#docstring`
#copy_to	Copies all data in this object to another code object, except for uniquely identifying information (path, namespace, name, scope).
#docstring	The documentation string associated with the object.
#docstring=	Attaches a docstring to a code object by parsing the comments attached to the statement and filling the `#tags` and `#docstring` methods with the parsed information.
#eql?	Alias for Base#equal?.
#equal?	Tests if another object is equal to this, including a proxy.
#file	Returns the filename the object was first parsed at, taking definitions with docstrings first.
#format	Renders the object using the templating system.
#has_tag?	Tests if the `#docstring` has a tag.
#hash,
#initialize	Creates a new code object.
#inspect	Inspects the object, returning the type and path.
#line	Returns the line the object was first parsed at (or nil).
#method_missing,
#name	The name of the object.
#path	Represents the unique path of the object.
#relative_path,
#sep	Override this method with a custom component separator.
#tag	Gets a tag from the `#docstring`
#tags	Gets a list of tags from the `#docstring`
#title, #to_ary,
#to_s	Alias for Base#path.
#type	Default type is the lowercase class name without the "Object" suffix.
#format_source	Formats source code by removing leading indentation.
#translate_docstring

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

Class Method Details

.apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) ⇒ String

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.

Parameters:

docstring (Docstring) —
the docstring to create a macro out of
call_params (Array<String>) (defaults to: []) —
the method name and parameters to the method call. These arguments will fill $0-N
full_source (String) (defaults to: '') —
the full source line (excluding block) interpolated as $*
block_source (String) (defaults to: '') —
Currently unused. Will support interpolating the block data as a variable.

Returns:

(String) —
the expanded macro data

.apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') ⇒ String

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.

Parameters:

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

Returns:

(String) —
the expanded macro data

[ GitHub ]

# 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) ⇒ `MacroObject`

Creates a new macro and fills in the relevant properties.

Parameters:

macro_name (String) —
the name of the macro, must be unique.
data (String) —
the data the macro should expand when re-used
method_object (CodeObjects::Base) (defaults to: nil) —
an object to attach this macro to. If supplied, #attached? will be true

Returns:

(MacroObject) —
the newly created object

[ GitHub ]

# 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.

[ GitHub ]

# File 'lib/yard/code_objects/macro_object.rb', line 74


alias create_docstring find_or_create

.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.

Parameters:

macro_data (String) —
the macro data to expand (taken from #macro_data)

[ GitHub ]

# 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) ⇒ `MacroObject`^?

Finds a macro using macro_name

Parameters:

macro_name (#to_s) —
the name of the macro

Returns:

(MacroObject) —
if a macro is found
(nil) —
if there is no registered macro by that name

[ GitHub ]

# 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) ⇒ `MacroObject`^? 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.

Parameters:

macro_name (#to_s) —
the name of the macro
method_object (CodeObjects::Base) (defaults to: nil) —
an optional method to attach the macro to. Only used if the macro is being created, otherwise this argument is ignored.

Returns:

(MacroObject) —
the newly created or existing macro, depending on whether the @!macro tag was a new tag or not.
(nil) —
if the data has no macro tag or if the macro is not new and no macro by the macro name is found.

[ GitHub ]

# 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

Instance Attribute Details

#attached? ⇒ `Boolean` (readonly)

Returns:

(Boolean) —
whether this macro is attached to a method

[ GitHub ]

# File 'lib/yard/code_objects/macro_object.rb', line 149


def attached?; method_object ? true : false end

#macro_data ⇒ String (rw)

Returns:

(String) —
the macro data stored on the object

[ GitHub ]

# File 'lib/yard/code_objects/macro_object.rb', line 142


attr_accessor :macro_data

#method_object ⇒ CodeObjects::Base (rw)

Returns:

(CodeObjects::Base) —
the method object that this macro is attached to.

[ GitHub ]

# File 'lib/yard/code_objects/macro_object.rb', line 146


attr_accessor :method_object

Instance Method Details

#expand(call_params = [], full_source = '', block_source = '')

Expands the macro using

Examples:

Expanding a Macro

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

Parameters:

call_params (Array<String>) (defaults to: []) —
a list of tokens that are passed to the method call
full_source (String) (defaults to: '') —
the full method call (not including the block)
block_source (String) (defaults to: '') —
the source passed in the block of the method call, if there is a block.

#path

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

[ GitHub ]

# File 'lib/yard/code_objects/macro_object.rb', line 152


def path; '.macro.' + name.to_s end

#sep

Overrides the separator to be '.'

[ GitHub ]

# File 'lib/yard/code_objects/macro_object.rb', line 155


def sep; '.' end

Class: YARD::CodeObjects::MacroObject

Overview

Constant Summary

Class Method Summary

Base - Inherited

Instance Attribute Summary

Base - Inherited

Instance Method Summary

Base - Inherited

Constructor Details

Dynamic Method Handling

Class Method Details

.apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) ⇒ String

.apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') ⇒ String

.create(macro_name, data, method_object = nil) ⇒ MacroObject

.create_docstring(macro_name, data, method_object = nil)

.expand(macro_data, call_params = [], full_source = '', block_source = '')

.find(macro_name) ⇒ MacroObject?

.find_or_create(macro_name, data, method_object = nil) ⇒ MacroObject? Also known as: .create_docstring

Instance Attribute Details

#attached? ⇒ Boolean (readonly)

#macro_data ⇒ String (rw)

#method_object ⇒ CodeObjects::Base (rw)

Instance Method Details

#expand(call_params = [], full_source = '', block_source = '')

#path

#sep

`Base` - Inherited

`Base` - Inherited

`Base` - Inherited

.create(macro_name, data, method_object = nil) ⇒ `MacroObject`

.find(macro_name) ⇒ `MacroObject`^?

.find_or_create(macro_name, data, method_object = nil) ⇒ `MacroObject`^? Also known as: .create_docstring

#attached? ⇒ `Boolean` (readonly)