class PuppetStrings::Markdown::Base

This class makes elements in a YARD::Registry hash easily accessible for templates.

Here’s an example hash: {:name=>:klass, :file=>“(stdin)”, :line=>16, :inherits=>“foo::bar”, :docstring=>

{:text=>"An overview for a simple class.",
 :tags=>
  [{:tag_name=>"summary", :text=>"A simple class."},
   {:tag_name=>"since", :text=>"1.0.0"},
   {:tag_name=>"see", :name=>"www.puppet.com"},
   {:tag_name=>"deprecated", :text=>"No longer supported and will be removed in a future release"},
   {:tag_name=>"example",
    :text=>
     "class { 'klass':\n" +
     "  param1 => 1,\n" +
     "  param3 => 'foo',\n" +
     "}",
    :name=>"This is an example"},
   {:tag_name=>"author", :text=>"eputnam"},
   {:tag_name=>"option", :name=>"opts"},
   {:tag_name=>"raise", :text=>"SomeError"},
   {:tag_name=>"param",
    :text=>"First param.",
    :types=>["Integer"],
    :name=>"param1"},
   {:tag_name=>"param",
    :text=>"Second param.",
    :types=>["Any"],
    :name=>"param2"},
   {:tag_name=>"param",
    :text=>"Third param.",
    :types=>["String"],
    :name=>"param3"}]},

:defaults=>{“param1”=>“1”, “param2”=>“undef”, “param3”=>“‘hi’”}, :source=>

"class klass (\n" +
"  Integer $param1 = 1,\n" +
"  $param2 = undef,\n" +
"  String $param3 = 'hi'\n" +
") inherits foo::bar {\n" +
"}"}

Public Class Methods

group_name(name = nil) click to toggle source

Set or return the name of the group

@param [Optional] Name of the group to set @return [String] Name of the group

# File lib/puppet-strings/markdown/base.rb, line 62
def self.group_name(name = nil)
  @group_name = name if name
  @group_name
end
items() click to toggle source

@return [Array] list of items

# File lib/puppet-strings/markdown/base.rb, line 77
def self.items
  yard_types
    .flat_map { |type| YARD::Registry.all(type) }
    .sort_by(&:name)
    .map(&:to_hash)
    .map { |i| new(i) }
end
new(registry, component_type) click to toggle source
# File lib/puppet-strings/markdown/base.rb, line 85
def initialize(registry, component_type)
  @type = component_type
  @registry = registry
  @tags = registry[:docstring][:tags] || []
end
yard_types(types = nil) click to toggle source

Set or return the types registered with YARD

@param [Optional[Array]] Array of symbols registered with YARD to set @return [Array] Array of symbols registered with YARD

# File lib/puppet-strings/markdown/base.rb, line 71
def self.yard_types(types = nil)
  @yard_types = types if types
  @yard_types
end

Public Instance Methods

defaults() click to toggle source

@return [Hash] any defaults found for the component

# File lib/puppet-strings/markdown/base.rb, line 176
def defaults
  @registry[:defaults] unless @registry[:defaults].nil?
end
enums() click to toggle source

@return [Array] enum tag hashes

# File lib/puppet-strings/markdown/base.rb, line 155
def enums
  select_tags('enum')
end
enums_for_param(parameter_name) click to toggle source

@param parameter_name

parameter name to match to enum tags

@return [Array] enum tag hashes that have a parent parameter_name

# File lib/puppet-strings/markdown/base.rb, line 170
def enums_for_param(parameter_name)
  enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
  enums_for_p unless enums_for_p.nil? || enums_for_p.empty?
end
examples() click to toggle source

@return [Array] example tag hashes

# File lib/puppet-strings/markdown/base.rb, line 140
def examples
  select_tags('example')
end
name() click to toggle source

@return [String] top-level name

# File lib/puppet-strings/markdown/base.rb, line 106
def name
  @registry[:name]&.to_s
end
options() click to toggle source

@return [Array] option tag hashes

# File lib/puppet-strings/markdown/base.rb, line 150
def options
  select_tags('option')
end
options_for_param(parameter_name) click to toggle source

@param parameter_name

parameter name to match to option tags

@return [Array] option tag hashes that have a parent parameter_name

# File lib/puppet-strings/markdown/base.rb, line 162
def options_for_param(parameter_name)
  opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
  opts_for_p unless opts_for_p.nil? || opts_for_p.empty?
end
params() click to toggle source

@return [Array] parameter tag hashes

# File lib/puppet-strings/markdown/base.rb, line 131
def params
  tags = @tags.select { |tag| tag[:tag_name] == 'param' }.map do |param|
    param[:link] = clean_link("$#{name}::#{param[:name]}")
    param
  end
  tags.empty? ? nil : tags
end
private?() click to toggle source
# File lib/puppet-strings/markdown/base.rb, line 195
def private?
  @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
end
raises() click to toggle source

@return [Array] raise tag hashes

# File lib/puppet-strings/markdown/base.rb, line 145
def raises
  select_tags('raise')
end
render(template) click to toggle source

@return [String] full markdown rendering of a component

# File lib/puppet-strings/markdown/base.rb, line 208
def render(template)
  file = File.join(File.dirname(__FILE__), 'templates', template)
  begin
    PuppetStrings::Markdown.erb(file).result(binding)
  rescue StandardError => e
    raise "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
  end
end
return_type() click to toggle source

@return [String] data type of return value

# File lib/puppet-strings/markdown/base.rb, line 116
def return_type
  @tags.find { |tag| tag[:tag_name] == 'return' }[:types][0] if @tags.any? { |tag| tag[:tag_name] == 'return' }
end
see() click to toggle source

@return [Array] @see tag hashes

# File lib/puppet-strings/markdown/base.rb, line 126
def see
  select_tags('see')
end
since() click to toggle source

@return [String] text from @since tag

# File lib/puppet-strings/markdown/base.rb, line 121
def since
  @tags.find { |tag| tag[:tag_name] == 'since' }[:text] if @tags.any? { |tag| tag[:tag_name] == 'since' }
end
text() click to toggle source

@return [String] ‘Overview’ text (untagged text)

# File lib/puppet-strings/markdown/base.rb, line 111
def text
  @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
end
toc_info() click to toggle source

@return [Hash] information needed for the table of contents

# File lib/puppet-strings/markdown/base.rb, line 181
def toc_info
  {
    name: name.to_s,
    link: link,
    desc: summary || @registry[:docstring][:text][0..140].tr("\n", ' '),
    private: private?
  }
end
word_wrap(text, line_width: 120, break_sequence: "\n") click to toggle source
# File lib/puppet-strings/markdown/base.rb, line 199
def word_wrap(text, line_width: 120, break_sequence: "\n")
  return unless text

  text.split("\n").map! { |line|
    line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
  } * break_sequence
end

Private Instance Methods

select_tags(name) click to toggle source
# File lib/puppet-strings/markdown/base.rb, line 219
def select_tags(name)
  tags = @tags.select { |tag| tag[:tag_name] == name }
  tags.empty? ? nil : tags
end