123456789_123456789_123456789_123456789_123456789_

Module: YARD::Templates::Helpers::MarkupHelper

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
HtmlHelper
Defined in: lib/yard/templates/helpers/markup_helper.rb

Overview

Helper methods for loading and managing markup types.

Constant Summary

  • MARKUP_EXTENSIONS =

    Returns a list of extensions for various markup types. To register extensions for a type, add them to the array of extensions for the type.

    Since:

    • 0.6.0

    # File 'lib/yard/templates/helpers/markup_helper.rb', line 61 
    {
  :html => ['htm', 'html', 'shtml'],
  :text => ['txt'],
  :textile => ['textile', 'txtile'],
  :asciidoc => ['asciidoc', 'ad', 'adoc', 'asc'],
  :markdown => ['markdown', 'md', 'mdown', 'mkd'],
  :rdoc => ['rdoc'],
  :org => ['org'],
  :ruby => ['rb', 'ru']
}
  • MARKUP_FILE_SHEBANG =

    Contains the Regexp object that matches the shebang line of extra files to detect the markup type.

    # File 'lib/yard/templates/helpers/markup_helper.rb', line 74 
    /\A#!(\S+)\s*$/
  • MARKUP_PROVIDERS =

    The default list of markup providers for each markup type

    # File 'lib/yard/templates/helpers/markup_helper.rb', line 24 
    {
  :markdown => [
    {:lib => :redcarpet, :const => 'RedcarpetCompat'},
    {:lib => :rdiscount, :const => 'RDiscount'},
    {:lib => :kramdown, :const => 'Kramdown::Document'},
    {:lib => :bluecloth, :const => 'BlueCloth'},
    {:lib => :maruku, :const => 'Maruku'},
    {:lib => :'rpeg-markdown', :const => 'PEGMarkdown'},
    {:lib => :rdoc, :const => 'YARD::Templates::Helpers::Markup::RDocMarkdown'},
    {:lib => :commonmarker, :const => 'CommonMarker'}
  ],
  :textile => [
    {:lib => :redcloth, :const => 'RedCloth'}
  ],
  :textile_strict => [
    {:lib => :redcloth, :const => 'RedCloth'}
  ],
  :rdoc => [
    {:lib => nil, :const => 'YARD::Templates::Helpers::Markup::RDocMarkup'}
  ],
  :org => [
    {:lib => :'org-ruby', :const => 'Orgmode::Parser'}
  ],
  :asciidoc => [
    {:lib => :asciidoctor, :const => 'Asciidoctor'}
  ],
  :ruby => [],
  :text => [],
  :pre  => [],
  :html => [],
  :none => []
}

Class Attribute Summary

Class Method Summary

Instance Method Summary

Class Attribute Details

.markup_cache ⇒ Hash{Symbol=>{(:provider,:class)=>Object}} (rw)

This method is for internal use only.

Returns:

  • (Hash{Symbol=>{(:provider,:class)=>Object}}) —

    the cached markup providers

Since:

  • 0.6.4

[ GitHub ] 

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 18



attr_accessor :markup_cache


  







Class Method Details



  

    .clear_markup_cache  ⇒ void 
  



  

    
This method returns an undefined value.
Clears the markup provider cache information. Mainly used for testing.


  





  


  [ GitHub ]


  

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 11



def clear_markup_cache
  self.markup_cache = {}
end


  







Instance Method Details



  

    #load_markup_provider(type = options.markup)  ⇒ Boolean 
  



  

    
Attempts to load the first valid markup provider in MARKUP_PROVIDERS.
If a provider is specified, immediately try to load it.



On success this sets @markup_provider and @markup_class to
the provider name and library constant class/module respectively for
the loaded provider.



On failure this method will inform the user that no provider could be
found and exit the program.


  





  
Returns:


    
  
  • 
    (Boolean)
—    
    whether the markup provider was successfully loaded.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 87



def load_markup_provider(type = options.markup)
  return true if MarkupHelper.markup_cache[type]
  MarkupHelper.markup_cache[type] ||= {}

  providers = MARKUP_PROVIDERS[type.to_sym]
  return true if providers && providers.empty?
  if providers && options.markup_provider
    providers = providers.select {|p| p[:lib] == options.markup_provider }
  end

  if providers.nil? || providers.empty?
    log.error "Invalid markup type '#{type}' or markup provider " \
              "(#{options.markup_provider}) is not registered."
    return false
  end

  # Search for provider, return the library class name as const if found
  providers.each do |provider|
    begin require provider[:lib].to_s; rescue LoadError; next end if provider[:lib]
    begin klass = eval("::" + provider[:const]); rescue NameError; next end # rubocop:disable Lint/Eval
    MarkupHelper.markup_cache[type][:provider] = provider[:lib] # Cache the provider
    MarkupHelper.markup_cache[type][:class] = klass
    return true
  end

  # Show error message telling user to install first potential provider
  lib = providers.first[:lib] || type
  log.error "Missing '#{lib}' gem for #{type.to_s.capitalize} formatting. Install it with `gem install #{lib}`"
  false
end


  








  

    #markup_class(type = options.markup)  ⇒ Class 
  



  

    
Gets the markup provider class/module constant for a markup type
Call #load_markup_provider before using this method.


  





  
Parameters:


    
  
  • 
    type
    (Symbol)
    (defaults to: options.markup)
—    
    the markup type (:rdoc, :markdown, etc.)
    

    
  
    • 



Returns:


    
  
  • 
    (Class)
—    
    the markup class
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 158



def markup_class(type = options.markup)
  load_markup_provider(type)
  MarkupHelper.markup_cache[type][:class]
end


  








  

    #markup_file_contents(contents)  ⇒ String 
  



  

    
Deprecated. 
Use CodeObjects::ExtraFileObject#contents instead




Strips any shebang lines on the file contents that pertain to
markup or preprocessing data.


  





  
Returns:


    
  
  • 
    (String)
—    
    the file contents minus any preprocessing tags
    

    
  
    • 



Since:


    
  
  • 
    
    0.6.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 149



def markup_file_contents(contents)
  contents =~ MARKUP_FILE_SHEBANG ? $' : contents
end


  








  

    #markup_for_file(contents, filename)  ⇒ Symbol 
  



  

    
Checks for a shebang or looks at the file extension to determine
the markup type for the file contents. ::File extensions are registered
for a markup type in MARKUP_EXTENSIONS.



A shebang should be on the first line of a file and be in the form:



#!markup_type



Standard markup types are text, html, rdoc, markdown, textile


  





  
Parameters:



Returns:


    
  
  • 
    (Symbol)
—    
    the markup type recognized for the file
    

    
  
    • 


  
See Also:

  

Since:


    
  
  • 
    
    0.6.0
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 133



def markup_for_file(contents, filename)
  return $1.to_sym if contents && contents =~ MARKUP_FILE_SHEBANG # Shebang support

  ext = (File.extname(filename)[1..-1] || '').downcase
  MARKUP_EXTENSIONS.each do |type, exts|
    return type if exts.include?(ext)
  end
  options.markup
end


  








  

    #markup_provider(type = options.markup)  ⇒ Symbol 
  



  

    
Gets the markup provider name for a markup type
Call #load_markup_provider before using this method.


  





  
Parameters:


    
  
  • 
    type
    (Symbol)
    (defaults to: options.markup)
—    
    the markup type (:rdoc, :markdown, etc.)
    

    
  
    • 



Returns:


    
  
  • 
    (Symbol)
—    
    the markup provider name (usually the gem name of the library)
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/templates/helpers/markup_helper.rb', line 168



def markup_provider(type = options.markup)
  MarkupHelper.markup_cache[type][:provider]
end