# 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 Method Summary collapse

- .clear_markup_cache ⇒ void

  Clears the markup provider cache information.

## Instance Method Summary collapse

- #load_markup_provider(type = options.markup) ⇒ Boolean

  Attempts to load the first valid markup provider in MARKUP_PROVIDERS.

- #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.

- #markup_file_contents(contents) ⇒ String deprecated Deprecated.

  Use CodeObjects::ExtraFileObject#contents instead

- #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.

- #markup_provider(type = options.markup) ⇒ Symbol

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

## 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:

- contents (`String`) —

  Unused. Was necessary prior to 0.7.0. Newer versions of YARD use CodeObjects::ExtraFileObject#contents

Returns:

- (`Symbol`) —

  the markup type recognized for the file

See Also:

- MARKUP_EXTENSIONS

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