Module: PuppetStrings::Yard::Util

Defined in:
lib/puppet-strings/yard/util.rb

Overview

The module for various puppet-strings utility helpers.

Class Method Summary collapse

Class Method Details

.ast_to_text(ast) ⇒ String

Convert Puppet AST to text.

Parameters:

  • ast (Puppet::Pops::Model::PopsObject) —

    The Puppet AST to convert to text.

Returns:

  • (String) —

    Returns a string of Puppet code.



84
85
86
 
# File 'lib/puppet-strings/yard/util.rb', line 84

def self.ast_to_text(ast)
  ast.locator.extract_tree_text(ast)
end

.docstring_to_hash(docstring, select_tags = nil) ⇒ Hash

Converts a YARD::Docstring (or String) to a docstring hash for JSON output.

Parameters:

  • docstring (YARD::Docstring, String) —

    The docstring to convert to a hash.

  • select_tags (Array) (defaults to: nil) —

    List of tags to select. Other tags will be filtered out.

Returns:

  • (Hash) —

    Returns a hash representation of the given docstring.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/puppet-strings/yard/util.rb', line 60

def self.docstring_to_hash(docstring, select_tags = nil)
  hash = {}
  hash[:text] = docstring

  if docstring.is_a? YARD::Docstring
    tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })

    unless tags.empty?
      hash[:tags] = tags
      #   .sort_by do |tag|
      #   sort_key = tag[:tag_name].dup
      #   sort_key << "-#{tag[:name]}" if tag[:name]
      #   sort_key << "-#{tag[:opt_name]}" if tag[:opt_name]
      #   sort_key
      # end
    end
  end

  hash
end

.github_to_yard_links(data) ⇒ String

hacksville, usa YARD creates ids in the html with with the style of “label-Module+description”, where the markdown we use in the README involves the GitHub-style, which is #module-description. This takes our GitHub-style links and converts them to reference the YARD-style ids.

Parameters:

  • data (String) —

    HTML document to convert

Returns:

  • (String) —

    HTML document with links converted

See Also:



25
26
27
28
29
30
31
 
# File 'lib/puppet-strings/yard/util.rb', line 25

def self.github_to_yard_links(data)
  data.scan(/href="\#(.+)"/).each do |bad_link|
    data = data.gsub("=\"##{bad_link.first}\"", "=\"#label-#{bad_link.first.capitalize.tr('-', '+')}\"")
  end

  data
end

.scrub_string(str) ⇒ String

Trims indentation from trailing whitespace and removes ruby literal quotation syntax ‘%Q{}` and `%q` from parsed strings.

Parameters:

  • str (String) —

    The string to scrub.

Returns:

  • (String) —

    A scrubbed string.



11
12
13
14
15
16
 
# File 'lib/puppet-strings/yard/util.rb', line 11

def self.scrub_string(str)
  match = str.match(/^%[Qq]{(.*)}$/m)
  return Puppet::Util::Docs.scrub(match[1]) if match

  Puppet::Util::Docs.scrub(str)
end

.tags_to_hashes(tags) ⇒ Array

Converts a list of tags into an array of hashes.

Parameters:

  • tags (Array) —

    List of tags to be converted into an array of hashes.

Returns:

  • (Array) —

    Returns an array of tag hashes.



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/puppet-strings/yard/util.rb', line 36

def self.tags_to_hashes(tags)
  # Skip over the API tags that are public
  tags.select { |t| t.tag_name != 'api' || t.text != 'public' }.map do |t|
    next t.to_hash if t.respond_to?(:to_hash)

    tag = { tag_name: t.tag_name }
    # grab nested information for @option and @enum tags
    if tag[:tag_name] == 'option' || tag[:tag_name] == 'enum'
      tag[:opt_name] = t.pair.name
      tag[:opt_text] = t.pair.text
      tag[:opt_types] = t.pair.types if t.pair.types
      tag[:parent] = t.name
    end
    tag[:text] = t.text if t.text
    tag[:types] = t.types if t.types
    tag[:name] = t.name if t.name
    tag
  end
end