module YARD::Templates::Helpers::HtmlHelper

Monkey into YARD's {www.rubydoc.info/gems/yard/YARD/Templates/Helpers/HtmlHelper HtmlHelper} module to add common methods we want available in HTML templates.

Public Instance Methods

htmlify_cucumber_line(text, markup=nil, strip: true) click to toggle source

Like {#htmlify_cucumber_text} but operates on single lines via {#h} for `:none`.

@param [String] text

The text to HTML-ify.

@param [nil | to_sym] markup

What markup to use; see {#htmlify_cucumber_text} for details.

@param [Boolean] strip

Should `text` have {String#strip} called on it first when rendering
markup?

@return [String]

HTML.
# File lib/yard/templates/helpers/html_helper.rb, line 131
def htmlify_cucumber_line(text, markup=nil, strip: true)
  # Resolve the `markup` {Symbol}
  markup = resolve_cucumber_markup markup
  
  # Switch off to the appropriate method.
  case markup
  when :none
    # Do what it was before: call {#h}
    h(text)
  when :default
    # Do whatever the rest of YARD is doing.
    htmlify_line(strip ? text.strip : text)
  else
    htmlify_line(strip ? text.strip : text, markup)
  end
end
htmlify_cucumber_text(text, markup=nil, strip: true) click to toggle source

Wrapper for HTML-ifying text from Cucumber features and scenarios that takes into account the `yard-cucumber.markup` config value.

@param [String] text

String to be converted to HTML markup.

@param [nil | to_sym] markup

The markup with which to parse the text:

1.  `nil` consults the `yard-cucumber.markup` config setting, then 
    proceeds with that value as if it was passed in.

    If the setting is missing or has a `nil` value, then `:none` is used
    to maintain the same behavior as before this method was introduced.

2.  `:none` uses {#htmlify_with_newlines}, which is what the call sites
    for this method used to use beforehand.

3.  `:default` uses {#htmlify} with no `markup` argument, causing it to
    use whatever markup is configured in the {#options}.

4.  Anything else is passed as the `markup` argument to {#htmlify}.

@param [Boolean] strip

When `true`, {String#strip} will be called on `text` before HTML-ifying.

Texts strings from features and scenarios seem to sometimes have at least
leading whitespace that does not seem intended given the `.feature` file.

This can trigger code-formatting on the text when processing with 
Markdown, and I might imagine cause weirdness given other markups as well.

*NOTE* To preserve legacy behavior `text` is *never* stripped when 
`markup` is resolved to `:none`.

@return [String]

HTML markup.
# File lib/yard/templates/helpers/html_helper.rb, line 97
def htmlify_cucumber_text(text, markup=nil, strip: true)
  # Resolve the `markup` {Symbol}
  markup = resolve_cucumber_markup markup
  
  # Switch off to the appropriate method.
  case markup
  when :none
    # Do what it was before: call {#htmlify_with_newlines}, escapes entities
    # and replaces "\n" with `<br/>` tags.
    htmlify_with_newlines(text)
  when :default
    # Do whatever the rest of YARD is doing.
    htmlify(strip ? text.strip : text)
  else
    htmlify(strip ? text.strip : text, markup)
  end
end
htmlify_with_newlines(text) click to toggle source

Original HTML-ification method, that is now referred to as `:none` markup. Escapes HTML entities and replaces newlines with `<br/>`.

@note 2019.01.10 nrser

This method used to be duplicated in `lib/templates/default/`...

1.  {file:lib/templates/default/feature/html/setup.rb feature/html/setup.rb}
2.  {file:lib/templates/default/featuredirectory/html/setup.rb featuredirectory/html/setup.rb}

but de-duplicated it to here after creating this file for
{#htmlify_cucumber_text}.

@see htmlify_cucumber_text

@param [String] text

String to be converted to HTML markup.

@return [String]

HTML markup.
# File lib/yard/templates/helpers/html_helper.rb, line 32
def htmlify_with_newlines(text)
  text.split("\n").collect {|c| h(c).gsub(/\s/,'&nbsp;') }.join("<br/>")
end

Private Instance Methods

resolve_cucumber_markup(markup = nil) click to toggle source

Resolve the `markup` value given an argument, as provided to {#htmlify_cucumber_text} or {#htmlify_cucumber_line}. Looks in the config when given `nil`, and defaults to `:none` to preserve old behavior if it finds nothing there either.

@param [nil | to_sym] markup

The argument value.

@return [Symbol]

The value to use.
# File lib/yard/templates/helpers/html_helper.rb, line 47
def resolve_cucumber_markup(markup = nil)
  if markup.nil?
    markup = YARD::Config.options[ :'yard-cucumber.markup' ] || :none
  end
  
  markup = markup.to_sym unless markup.is_a?( Symbol )
  
  markup
end