Module: YARD::Templates::Template

Includes:
ErbCache, Helpers::BaseHelper, Helpers::MethodHelper
Defined in:
lib/yard/templates/template.rb

Defined Under Namespace

Modules: ClassMethods

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes included from Helpers::BaseHelper

#object, #serializer

Instance Method Summary collapse

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_object, #link_object, #link_url, #linkify, #run_verifier

Methods included from ErbCache

clear!, method_for

Class Attribute Details

.extra_includes ⇒ Array<Module>

Returns a list of modules to be automatically included into any new template module.

Returns:

  • (Array<Module>) —

    a list of modules to be automatically included into any new template module



12
13
14
 
# File 'lib/yard/templates/template.rb', line 12

def extra_includes
  @extra_includes
end

Instance Attribute Details

#class ⇒ Object

Returns the value of attribute class.



6
7
8
 
# File 'lib/yard/templates/template.rb', line 6

def class
  @class
end

#options ⇒ Object

Returns the value of attribute options.



7
8
9
 
# File 'lib/yard/templates/template.rb', line 7

def options
  @options
end

#section ⇒ Object

Returns the value of attribute section.



6
7
8
 
# File 'lib/yard/templates/template.rb', line 6

def section
  @section
end

Instance Method Details

#erb(section) { ... } ⇒ String

Returns the contents of the ERB rendered section.

Parameters:

  • section (String, Symbol) —

    the section name

Yields:

  • calls subsections to be rendered

Returns:

  • (String) —

    the contents of the ERB rendered section



234
235
236
237
238
239
 
# File 'lib/yard/templates/template.rb', line 234

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) 



297
298
299
 
# File 'lib/yard/templates/template.rb', line 297

def erb_file_for(section)
  "#{section}.erb"
end

#erb_with(content, filename = nil) ⇒ Object (protected) 



301
302
303
304
305
 
# File 'lib/yard/templates/template.rb', line 301

def erb_with(content, filename = nil)
  erb = ERB.new(content, nil, options[:format] == :text ? '<>' : nil)
  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 }

Parameters:

  • basename (String) —

    the name of the file

  • allow_inherited (Boolean) (defaults to: false) —

    whether inherited templates can be inserted with {{{__super__}}}

Returns:

  • (String) —

    the contents of a file identified by basename. All template paths (including any mixed in templates) are searched for the file

Raises:

  • (ArgumentError)

See Also:



261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/yard/templates/template.rb', line 261

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

Examples:

A default set of sections

def init
  sections :section1, :section2, [:subsection1, :etc]
end

See Also:



188
189
 
# File 'lib/yard/templates/template.rb', line 188

def init
end

#initialize(opts = {}) ⇒ Object 



134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/yard/templates/template.rb', line 134

def initialize(opts = {})
  @cache, @cache_filename = {}, {}
  @sections, @options = [], {}
  add_options(opts)
  
  extend(Helpers::HtmlHelper) if options[:format] == :html
  extend(Helpers::TextHelper) if options[:format] == :text
  extend(Helpers::UMLHelper) if options[:format] == :dot
  extend(*Template.extra_includes) unless Template.extra_includes.empty?

  init
end

#inspect ⇒ Object 



291
292
293
 
# File 'lib/yard/templates/template.rb', line 291

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

Parameters:

  • opts (Hash, nil) (defaults to: nil) —

    any extra options to apply to sections

  • sects (Section, Array) (defaults to: sections) —

    a section list of sections to render

  • start_at (Fixnum) (defaults to: 0) —

    the index in the section list to start from

  • break_first (Boolean) (defaults to: false) —

    if true, renders only the first section

Yields:

  • (opts) —

    calls for the subsections to be rendered

Yield Parameters:

  • opts (Hash) —

    any extra options to yield

Returns:

  • (String) —

    the rendered sections joined together



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/yard/templates/template.rb', line 201

def run(opts = nil, sects = sections, start_at = 0, break_first = false, &block)
  out = ""
  return out if sects.nil?
  sects = sects[start_at..-1] if start_at > 0
  sects = Section.new(nil, sects) unless sects.is_a?(Section)
  add_options(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

Examples:

Sets a set of erb sections

sections :a, :b, :c # searches for a.erb, b.erb, c.erb

Sets a set of method and erb sections

sections :a, :b, :c # a is a method, the rest are erb files

Sections with subsections

sections :header, [:name, :children]
# the above will call header.erb and only renders the subsections
# if they are yielded by the template (see #yieldall)

Parameters:

  • args (Array<Symbol, String, Template, Array>) —

    the sections to use to render the template. For symbols and strings, the section will be executed as a method (if one exists), or rendered from the file “name.erb” where name is the section name. For templates, they will have YARD::Templates::Template::ClassMethods#run called on them. Any subsections can be yielded to using yield or #yieldall



175
176
177
178
 
# File 'lib/yard/templates/template.rb', line 175

def sections(*args)
  @sections = Section.new(nil, *args) if args.size > 0
  @sections
end

#superb(section = section, &block) ⇒ String

Calls the ERB file from the last inherited template with #section.erb

Parameters:

  • section (Symbol, String) (defaults to: section) —

    if provided, uses a specific section name

Returns:

  • (String) —

    the rendered ERB file in any of the inherited template paths.



279
280
281
282
283
284
 
# File 'lib/yard/templates/template.rb', line 279

def superb(section = section, &block)
  filename = self.class.find_nth_file(erb_file_for(section), 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 prependend and appended to the path respectively.

Parameters:

  • path (Array<String, Symbol>) —

    the path of the template

Returns:

  • (Template) —

    the loaded template module



153
154
155
156
157
 
# File 'lib/yard/templates/template.rb', line 153

def T(*path)
  path.unshift(options[:template]) if options[:template]
  path.push(options[:format]) if options[:format]
  self.class.T(*path)
end

#yieldall(opts = nil, &block) ⇒ Object

Yields all subsections with any extra options

Parameters:

  • opts (Hash) (defaults to: nil) —

    extra options to be applied to subsections



227
228
229
 
# File 'lib/yard/templates/template.rb', line 227

def yieldall(opts = nil, &block)
  with_section { run(opts, section, &block) }
end