Module: YARD::Templates::Template
- Extended by:
- ClassMethods
- Includes:
- ErbCache, Helpers::BaseHelper, Helpers::MethodHelper
- Defined in:
- lib/yard/templates/template.rb
Defined Under Namespace
Modules: ClassMethods
Class Attribute Summary collapse
-
.extra_includes ⇒ Array<Module, Proc>
Extra includes are mixins that are included after a template is created.
Instance Attribute Summary collapse
-
#class ⇒ Object
Returns the value of attribute class.
-
#full_path ⇒ Object
included
from ClassMethods
Returns the value of attribute full_path.
-
#options ⇒ Object
Returns the value of attribute options.
-
#path ⇒ Object
included
from ClassMethods
Returns the value of attribute path.
-
#section ⇒ Object
Returns the value of attribute section.
Attributes included from Helpers::BaseHelper
Class Method Summary collapse
-
.find_file(basename) ⇒ String
extended
from ClassMethods
Searches for a file identified by
basename
in the template’s path as well as any mixed in template paths. -
.find_nth_file(basename, index = 1) ⇒ String
extended
from ClassMethods
Searches for the nth file (where n =
index
) identified by basename in the template’s path and any mixed in template paths. -
.full_paths ⇒ Array<String>
extended
from ClassMethods
A list of full paths.
-
.include_extra(template, options) ⇒ void
Includes the Template.extra_includes modules into the template object.
- .initialize(path, full_paths) ⇒ Object extended from ClassMethods
- .is_a?(klass) ⇒ Boolean extended from ClassMethods
-
.new(*args) ⇒ Object
extended
from ClassMethods
Creates a new template object to be rendered with #run.
-
.reset_full_paths ⇒ Object
extended
from ClassMethods
Resets cache for ClassMethods#full_paths.
- .run(*args) ⇒ Object extended from ClassMethods
-
.S(*args) ⇒ Object
extended
from ClassMethods
Alias for creating a Section with arguments.
-
.T(*path) ⇒ Object
extended
from ClassMethods
Alias for creating Engine.template.
Instance Method Summary collapse
-
#erb(section) { ... } ⇒ String
The contents of the ERB rendered section.
- #erb_file_for(section) ⇒ Object protected
- #erb_with(content, filename = nil) ⇒ Object protected
-
#file(basename, allow_inherited = false) ⇒ String
Returns the contents of a file.
-
#init ⇒ Object
Initialization called on the template.
- #initialize(opts = TemplateOptions.new) ⇒ Object
- #inspect ⇒ Object
-
#run(opts = nil, sects = sections, start_at = 0, break_first = false) {|opts| ... } ⇒ String
Runs a template on
sects
using extra options. -
#sections(*args) ⇒ Object
Sets the sections (and subsections) to be rendered for the template.
-
#superb(sect = section, &block) ⇒ String
Calls the ERB file from the last inherited template with #section.erb.
-
#T(*path) ⇒ Template
Loads a template specified by path.
-
#yieldall(opts = nil, &block) ⇒ Object
Yields all subsections with any extra options.
Methods included from Helpers::MethodHelper
#format_args, #format_block, #format_code, #format_constant, #format_lines, #format_return_types
Methods included from Helpers::BaseHelper
#format_object_title, #format_object_type, #format_source, #format_types, #globals, #h, #link_file, #link_include_file, #link_include_object, #link_object, #link_url, #linkify, #run_verifier
Methods included from ErbCache
Class Attribute Details
.extra_includes ⇒ Array<Module, Proc>
Extra includes are mixins that are included after a template is created. These mixins can be registered by plugins to operate on templates and override behaviour.
Note that this array can be filled with modules or proc objects. If a proc object is given, the proc will be called with the #options hash containing relevant template information like the object, format, and more. The proc should return a module or nil if there is none.
25 26 27 |
# File 'lib/yard/templates/template.rb', line 25 def extra_includes @extra_includes end |
Instance Attribute Details
#class ⇒ Object
Returns the value of attribute class.
7 8 9 |
# File 'lib/yard/templates/template.rb', line 7 def class @class end |
#full_path ⇒ Object Originally defined in module ClassMethods
Returns the value of attribute full_path.
#options ⇒ Object
Returns the value of attribute options.
8 9 10 |
# File 'lib/yard/templates/template.rb', line 8 def @options end |
#path ⇒ Object Originally defined in module ClassMethods
Returns the value of attribute path.
#section ⇒ Object
Returns the value of attribute section.
7 8 9 |
# File 'lib/yard/templates/template.rb', line 7 def section @section end |
Class Method Details
.find_file(basename) ⇒ String Originally defined in module ClassMethods
Searches for a file identified by basename
in the template’s path as well as any mixed in template paths. Equivalent to calling #find_nth_file with index of 1.
.find_nth_file(basename, index = 1) ⇒ String Originally defined in module ClassMethods
Searches for the nth file (where n = index
) identified by basename in the template’s path and any mixed in template paths.
.full_paths ⇒ Array<String> Originally defined in module ClassMethods
This method caches path results. Paths should not be modified after this method is called; call #reset_full_paths to reset cache.
Returns a list of full paths.
.include_extra(template, options) ⇒ void
This method returns an undefined value.
Includes the extra_includes modules into the template object.
38 39 40 41 42 43 44 |
# File 'lib/yard/templates/template.rb', line 38 def include_extra(template, ) extra_includes.each do |mod| mod = mod.call() if mod.is_a?(Proc) next unless mod.is_a?(Module) template.extend(mod) end end |
.initialize(path, full_paths) ⇒ Object Originally defined in module ClassMethods
.is_a?(klass) ⇒ Boolean Originally defined in module ClassMethods
.new(*args) ⇒ Object Originally defined in module ClassMethods
Creates a new template object to be rendered with YARD::Templates::Template#run
.reset_full_paths ⇒ Object Originally defined in module ClassMethods
Resets cache for #full_paths
.run(*args) ⇒ Object Originally defined in module ClassMethods
.S(*args) ⇒ Object Originally defined in module ClassMethods
Alias for creating a Section with arguments
.T(*path) ⇒ Object Originally defined in module ClassMethods
Alias for creating Engine.template.
Instance Method Details
#erb(section) { ... } ⇒ String
Returns the contents of the ERB rendered section.
283 284 285 286 287 288 |
# File 'lib/yard/templates/template.rb', line 283 def erb(section, &block) method_name = ErbCache.method_for(cache_filename(section)) do erb_with(cache(section), cache_filename(section)) end send(method_name, &block) end |
#erb_file_for(section) ⇒ Object (protected)
346 347 348 |
# File 'lib/yard/templates/template.rb', line 346 def erb_file_for(section) "#{section}.erb" end |
#erb_with(content, filename = nil) ⇒ Object (protected)
350 351 352 353 354 355 356 357 358 |
# File 'lib/yard/templates/template.rb', line 350 def erb_with(content, filename = nil) erb = if ERB.instance_method(:initialize).parameters.assoc(:key) # Ruby 2.6+ ERB.new(content, :trim_mode => .format == :text ? '<>' : nil) else ERB.new(content, nil, .format == :text ? '<>' : nil) end erb.filename = filename if filename erb end |
#file(basename, allow_inherited = false) ⇒ String
Returns the contents of a file. If allow_inherited
is set to true
, use {{{__super__}}} inside the file contents to insert the contents of the file from an inherited template. For instance, if templates/b
inherits from templates/a
and file “test.css” exists in both directories, both file contents can be retrieved by having templates/b/test.css
look like:
{{{__super__}}}
...
body { css styles here }
p.class { other styles }
310 311 312 313 314 315 316 317 318 319 320 321 |
# File 'lib/yard/templates/template.rb', line 310 def file(basename, allow_inherited = false) file = self.class.find_file(basename) raise ArgumentError, "no file for '#{basename}' in #{self.class.path}" unless file data = IO.read(file) if allow_inherited superfile = self.class.find_nth_file(basename, 2) data.gsub!('{{{__super__}}}', superfile ? IO.read(superfile) : "") end data end |
#init ⇒ Object
Initialization called on the template. Override this in a ‘setup.rb’ file in the template’s path to implement a template
237 238 |
# File 'lib/yard/templates/template.rb', line 237 def init end |
#initialize(opts = TemplateOptions.new) ⇒ Object
184 185 186 187 188 189 190 191 192 193 194 |
# File 'lib/yard/templates/template.rb', line 184 def initialize(opts = TemplateOptions.new) opts_class = opts.class opts_class = TemplateOptions if opts_class == Hash @cache = {} @cache_filename = {} @sections = [] @options = opts_class.new (opts) Template.include_extra(self, ) init end |
#inspect ⇒ Object
340 341 342 |
# File 'lib/yard/templates/template.rb', line 340 def inspect "Template(#{self.class.path}) [section=#{section.name}]" end |
#run(opts = nil, sects = sections, start_at = 0, break_first = false) {|opts| ... } ⇒ String
Runs a template on sects
using extra options. This method should not be called directly. Instead, call the class method YARD::Templates::Template::ClassMethods#run
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 |
# File 'lib/yard/templates/template.rb', line 250 def run(opts = nil, sects = sections, start_at = 0, break_first = false, &block) out = String.new("") return out if sects.nil? sects = sects[start_at..-1] if start_at > 0 sects = Section.new(nil, sects) unless sects.is_a?(Section) (opts) do sects.each do |s| self.section = s subsection_index = 0 value = render_section(section) do |*args| value = with_section do run(args.first, section, subsection_index, true, &block) end subsection_index += 1 value end out << (value || "") break if break_first end end out end |
#sections(*args) ⇒ Object
Sets the sections (and subsections) to be rendered for the template
224 225 226 227 |
# File 'lib/yard/templates/template.rb', line 224 def sections(*args) @sections = Section.new(nil, *args) unless args.empty? @sections end |
#superb(sect = section, &block) ⇒ String
Calls the ERB file from the last inherited template with #section.erb
328 329 330 331 332 333 |
# File 'lib/yard/templates/template.rb', line 328 def superb(sect = section, &block) filename = self.class.find_nth_file(erb_file_for(sect), 2) return "" unless filename method_name = ErbCache.method_for(filename) { erb_with(IO.read(filename), filename) } send(method_name, &block) end |
#T(*path) ⇒ Template
Loads a template specified by path. If :template
or :format
is specified in the #options hash, they are prepended and appended to the path respectively.
202 203 204 205 206 |
# File 'lib/yard/templates/template.rb', line 202 def T(*path) # rubocop:disable Style/MethodName path.unshift(.template) if .template path.push(.format) if .format self.class.T(*path) end |
#yieldall(opts = nil, &block) ⇒ Object
Yields all subsections with any extra options
276 277 278 |
# File 'lib/yard/templates/template.rb', line 276 def yieldall(opts = nil, &block) with_section { run(opts, section, &block) } end |