123456789_123456789_123456789_123456789_123456789_

Module: YARD::Templates::Engine

Relationships & Source Files
Defined in: lib/yard/templates/engine.rb

Overview

This module manages all creation, handling and rendering of Template objects.

Class Attribute Summary

Class Method Summary

Class Attribute Details

.template_paths ⇒ Array<String> (rw)

Returns:

  • (Array<String>) —

    the list of registered template paths

[ GitHub ] 

  


# File 'lib/yard/templates/engine.rb', line 14



attr_accessor :template_paths


  







Class Method Details



  

    .find_template_paths(from_template, path)  ⇒ Array<String>  (private)
  



  

    
Searches through the registered .template_paths and returns
all full directories that have the path within them on disk.


  





  
Parameters:


    
  
  • 
    from_template
    (Template)
—    
    if provided, allows a relative
path to be specified from this template's full path.
    

    
  
    • 
  
  • 
    path
    (String)
—    
    the path component to search for in the
.template_paths
    

    
  
    • 



Returns:


    
  
  • 
    (Array<String>)
—    
    a list of full paths that are existing
candidates for a template module
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 160



def find_template_paths(from_template, path)
  paths = template_paths.dup
  paths = from_template.full_paths + paths if from_template

  paths.inject([]) do |acc, tp|
    full_path = File.cleanpath(File.join(tp, path))
    acc.unshift(full_path) if File.directory?(full_path)
    acc
  end.uniq
end


  








  

    .generate(objects, options = {})  ⇒ void 
  



  

    
This method returns an undefined value.
Passes a set of objects to the :fulldoc template for full documentation generation.
This is called by ::YARD::CLI::Yardoc to most commonly perform HTML
documentation generation.


  





  
Parameters:





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 100



def generate(objects, options = {})
  options = set_default_options(options)
  options.objects = objects
  options.object = Registry.root
  template(options.template, :fulldoc, options.format).run(options)
end


  








  

    .register_template_path(path)  ⇒ void 
  



  

    
This method returns an undefined value.
Registers a new template path in .template_paths


  





  
Parameters:


    
  
  • 
    path
    (String)
—    
    a new template path
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 20



def register_template_path(path)
  template_paths.push(path) unless template_paths.include?(path)
end


  








  

    .render(options = {})  ⇒ String 
  



  

    
Renders a template on a code object using
a set of default (overridable) options. Either the :object
or :type keys must be provided.



If a :serializer key is provided and :serialize is not set to
false, the rendered contents will be serialized through the ::YARD::Serializers::Base
object. See .with_serializer.


  





    

    
Examples:

        
Renders an object with html formatting



      
Engine.render(:format => :html, :object => obj)

        
Renders without an object



      
Engine.render(:type => :fulldoc, :otheropts => somevalue)

  


Parameters:


    
  
  • 
    options
    (Hash)
    (defaults to: {})
—    
    the options hash
    

    
  
    • 


    
Options Hash (options):

    
    
        
  • 
          :format
          (Symbol)
           — default:
              :text          
            — 
    the default format
    

            
    • 
        
  • 
          :type
          (Symbol)
           — default:
              nil          
            — 
    the :object's type.
    

            
    • 
        
  • 
          :template
          (Symbol)
           — default:
              :default          
            — 
    the default template
    

            
    • 
    


Returns:


    
  
  • 
    (String)
—    
    the rendered template
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 81



def render(options = {})
  options = set_default_options(options)
  mod = template(options.template, options.type, options.format)

  if options.serializer && options.serialize != false
    with_serializer(options.object, options.serializer) { mod.run(options) }
  else
    mod.run(options)
  end
end


  








  

    .set_default_options(options = {})  ⇒ void  (private)
  



  

    
This method returns an undefined value.
Sets default options on the options hash


  





  
Parameters:


    
  
  • 
    options
    (Hash)
    (defaults to: {})
—    
    the options hash
    

    
  
    • 


    
Options Hash (options):

    
    
        
  • 
          :format
          (Symbol)
           — default:
              :text          
            — 
    the default format
    

            
    • 
        
  • 
          :type
          (Symbol)
           — default:
              nil          
            — 
    the :object's type, if provided
    

            
    • 
        
  • 
          :template
          (Symbol)
           — default:
              :default          
            — 
    the default template
    

            
    • 
    




  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 140



def set_default_options(options = {})
  if options.is_a?(Hash)
    options = TemplateOptions.new.tap do |o|
      o.reset_defaults
      o.update(options)
    end
  end
  options.type ||= options.object.type if options.object
  options
end


  








  

    .template(*path)  ⇒ Template 
  



  

    
Creates a template module representing the path. Searches on disk
for the first directory named path (joined by '/') within the
template paths and builds a template module for. All other matching
directories in other template paths will be included in the
generated module as mixins (for overriding).


  





  
Parameters:


    
  
  • 
    path
    (Array<String, Symbol>)
—    
    a list of path components
    

    
  
    • 



Returns:


    
  
  • 
    (Template)
—    
    the module representing the template
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    if the path does not exist within one of the
.template_paths on disk.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 34



def template(*path)
  from_template = nil
  from_template = path.shift if path.first.is_a?(Template)
  path = path.join('/')
  full_paths = find_template_paths(from_template, path)

  path = File.cleanpath(path).gsub('../', '')
  raise ArgumentError, "No such template for #{path}" if full_paths.empty?
  mod = template!(path, full_paths)

  mod
end


  








  

    .template!(path, full_paths = nil)  ⇒ Template 
  



  

    
Forces creation of a template at path within a full_path.


  





  
Parameters:


    
  
  • 
    path
    (String)
—    
    the path name of the template
    

    
  
    • 
  
  • 
    full_paths
    (Array<String>)
    (defaults to: nil)
—    
    the full path on disk of the template
    

    
  
    • 



Returns:


    
  
  • 
    (Template)
—    
    the template module representing the path
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 52



def template!(path, full_paths = nil)
  full_paths ||= [path]
  full_paths = [full_paths] unless full_paths.is_a?(Array)
  name = template_module_name(full_paths.first)
  begin; return const_get(name); rescue NameError; nil end

  mod = const_set(name, Module.new)
  mod.send(:include, Template)
  mod.send(:initialize, path, full_paths)
  mod
end


  








  

    .template_module_name(path)  ⇒ String  (private)
  



  

    
The name of the module that represents a path


  





  
Parameters:


    
  
  • 
    path
    (String)
—    
    the path to generate a module name for
    

    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    the module name
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 175



def template_module_name(path)
  'Template_' + path.to_s.gsub(/[^a-z0-9]/i, '_')
end


  








  

    .with_serializer(object, serializer) { ... } 
  



  

    
Serializes the results of a block with a serializer object.


  





  
Parameters:



Yields:


    
  
  • 
    
    
    a block whose result will be serialize
    

    
  
    • 



Yield Returns:


    
  
  • 
    (String)
—    
    the contents to serialize
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/yard/templates/engine.rb', line 114



def with_serializer(object, serializer)
  output = nil
  filename = serializer.serialized_path(object)
  if serializer.respond_to?(:basepath)
    filename = File.join(serializer.basepath, filename)
  end
  log.capture("Generating #{filename}", nil) do
    serializer.before_serialize if serializer
    output = yield
    if serializer
      serializer.serialize(object, output)
      serializer.after_serialize(output)
    end
  end
  output
end