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

Included in:
HtmlHelper
Defined in:
lib/yard/templates/helpers/markup_helper.rb

Overview

Helper methods for loading and managing markup types.

Constant Summary collapse

MARKUP_PROVIDERS =

The default list of markup providers for each markup type

{
  :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 => []
}
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

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

/\A#!(\S+)\s*$/

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

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

Returns the cached markup providers.

Returns:

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

    the cached markup providers

Since:

  • 0.6.4



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

def markup_cache
  @markup_cache
end

Class Method Details

.clear_markup_cache ⇒ void

This method returns an undefined value.

Clears the markup provider cache information. Mainly used for testing.



11
12
13
 
# 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.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# 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



158
159
160
161
 
# 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



149
150
151
 
# 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



133
134
135
136
137
138
139
140
141
 
# 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)



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

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