module PuppetStrings::Yard::Util

The module for various puppet-strings utility helpers.

Public Class Methods

ast_to_text(ast) click to toggle source

Convert Puppet AST to text. @param [Puppet::Pops::Model::PopsObject] ast The Puppet AST to convert to text. @return [String] Returns a string of Puppet code.

# 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) click to toggle source

Converts a YARD::Docstring (or String) to a docstring hash for JSON output. @param [YARD::Docstring, String] docstring The docstring to convert to a hash. @param [Array] select_tags List of tags to select. Other tags will be filtered out. @return [Hash] Returns a hash representation of the given docstring.

# 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
scrub_string(str) click to toggle source

Trims indentation from trailing whitespace and removes ruby literal quotation syntax ‘%Q{}` and `%{q}` from parsed strings. @param [String] str The string to scrub. @return [String] A scrubbed string.

# 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) click to toggle source

Converts a list of tags into an array of hashes. @param [Array] tags List of tags to be converted into an array of hashes. @return [Array] Returns an array of tag hashes.

# 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