Class: PuppetStrings::Markdown::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet-strings/markdown/base.rb

Overview

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

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

{:text=>"An overview for a simple class.",
 :tags=>
  [{:tag_name=>"summary", :text=>"A simple class.",
   :text=>"1.0.0",
   :name=>"www.puppet.com",
       :text=>
     "class { 'klass':\n" +
     "  param1 => 1,\n" +
     "  param3 => 'foo',\n" +
     "",
    :name=>"This is an example"},
   :text=>"eputnam",
   :name=>"opts",
   :text=>"SomeError",
       :text=>"First param.",
    :types=>["Integer"],
    :name=>"param1",
       :text=>"Second param.",
    :types=>["Any"],
    :name=>"param2",
       :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 +
""}

Instance Method Summary collapse

Constructor Details

#initialize(registry, component_type) ⇒ Base

Returns a new instance of Base.



52
53
54
55
56
 
# File 'lib/puppet-strings/markdown/base.rb', line 52

def initialize(registry, component_type)
  @type = component_type
  @registry = registry
  @tags = registry[:docstring][:tags] || []
end

Instance Method Details

#defaults ⇒ Hash

Returns any defaults found for the component.

Returns:

  • (Hash) —

    any defaults found for the component



138
139
140
 
# File 'lib/puppet-strings/markdown/base.rb', line 138

def defaults
  @registry[:defaults] unless @registry[:defaults].nil?
end

#enums ⇒ Array

Returns enum tag hashes.

Returns:

  • (Array) —

    enum tag hashes



117
118
119
 
# File 'lib/puppet-strings/markdown/base.rb', line 117

def enums
  select_tags('enum')
end

#enums_for_param(parameter_name) ⇒ Array

Returns enum tag hashes that have a parent parameter_name.

Parameters:

  • parameter_name —

    parameter name to match to enum tags

Returns:

  • (Array) —

    enum tag hashes that have a parent parameter_name



132
133
134
135
 
# File 'lib/puppet-strings/markdown/base.rb', line 132

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.length.zero?
end

#examples ⇒ Array

Returns example tag hashes.

Returns:

  • (Array) —

    example tag hashes



102
103
104
 
# File 'lib/puppet-strings/markdown/base.rb', line 102

def examples
  select_tags('example')
end

#link ⇒ String

Returns makes the component name suitable for a GitHub markdown link.

Returns:

  • (String) —

    makes the component name suitable for a GitHub markdown link



153
154
155
 
# File 'lib/puppet-strings/markdown/base.rb', line 153

def link
  name.delete('::').strip.gsub(' ','-').downcase
end

#name ⇒ String

Returns top-level name.

Returns:

  • (String) —

    top-level name



72
73
74
 
# File 'lib/puppet-strings/markdown/base.rb', line 72

def name
  @registry[:name]&.to_s
end

#options ⇒ Array

Returns option tag hashes.

Returns:

  • (Array) —

    option tag hashes



112
113
114
 
# File 'lib/puppet-strings/markdown/base.rb', line 112

def options
  select_tags('option')
end

#options_for_param(parameter_name) ⇒ Array

Returns option tag hashes that have a parent parameter_name.

Parameters:

  • parameter_name —

    parameter name to match to option tags

Returns:

  • (Array) —

    option tag hashes that have a parent parameter_name



124
125
126
127
 
# File 'lib/puppet-strings/markdown/base.rb', line 124

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.length.zero?
end

#params ⇒ Array

Returns parameter tag hashes.

Returns:

  • (Array) —

    parameter tag hashes



97
98
99
 
# File 'lib/puppet-strings/markdown/base.rb', line 97

def params
  select_tags('param')
end

#private? ⇒ Boolean

Returns:

  • (Boolean) 


170
171
172
 
# File 'lib/puppet-strings/markdown/base.rb', line 170

def private?
  @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
end

#raises ⇒ Array

Returns raise tag hashes.

Returns:

  • (Array) —

    raise tag hashes



107
108
109
 
# File 'lib/puppet-strings/markdown/base.rb', line 107

def raises
  select_tags('raise')
end

#render(template) ⇒ String

Returns full markdown rendering of a component.

Returns:

  • (String) —

    full markdown rendering of a component



183
184
185
186
187
188
189
190
 
# File 'lib/puppet-strings/markdown/base.rb', line 183

def render(template)
  begin
    file = File.join(File.dirname(__FILE__),"templates/#{template}")
    ERB.new(File.read(file), nil, '-').result(binding)
  rescue StandardError => e
    fail "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
  end
end

#return_type ⇒ String

Returns data type of return value.

Returns:

  • (String) —

    data type of return value



82
83
84
 
# File 'lib/puppet-strings/markdown/base.rb', line 82

def return_type
  @tags.find { |tag| tag[:tag_name] == 'return' }[:types][0] if @tags.any? { |tag| tag[:tag_name] == 'return' }
end

#see ⇒ Array

Returns @see tag hashes.

Returns:

  • (Array) —

    @see tag hashes



92
93
94
 
# File 'lib/puppet-strings/markdown/base.rb', line 92

def see
  select_tags('see')
end

#since ⇒ String

Returns text from @since tag.

Returns:

  • (String) —

    text from @since tag



87
88
89
 
# File 'lib/puppet-strings/markdown/base.rb', line 87

def since
  @tags.find { |tag| tag[:tag_name] == 'since' }[:text] if @tags.any? { |tag| tag[:tag_name] == 'since' }
end

#text ⇒ String

Returns ‘Overview’ text (untagged text).

Returns:

  • (String) —

    ‘Overview’ text (untagged text)



77
78
79
 
# File 'lib/puppet-strings/markdown/base.rb', line 77

def text
  @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
end

#toc_info ⇒ Hash

Returns information needed for the table of contents.

Returns:

  • (Hash) —

    information needed for the table of contents



143
144
145
146
147
148
149
150
 
# File 'lib/puppet-strings/markdown/base.rb', line 143

def toc_info
  {
    name: name.to_s,
    link: link,
    desc: summary || @registry[:docstring][:text][0..140].gsub("\n",' '),
    private: private?
  }
end

#value_string(value) ⇒ String

Some return, default, or valid values need to be in backticks. Instead of fu in the handler or code_object, this just does the change on the front.

Parameters:

  • value —

    any string

Returns:

  • (String) —

    value or value in backticks if it is in a list



161
162
163
164
165
166
167
168
 
# File 'lib/puppet-strings/markdown/base.rb', line 161

def value_string(value)
  to_symbol = %w[undef true false]
  if to_symbol.include? value
    return "`#{value}`"
  else
    return value
  end
end

#word_wrap(text, line_width: 120, break_sequence: "\n") ⇒ Object 



174
175
176
177
178
179
180
 
# File 'lib/puppet-strings/markdown/base.rb', line 174

def word_wrap(text, line_width: 120, break_sequence: "\n")
  return unless text

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