Class: PuppetStrings::Markdown::Base

Inherits:
Object
  • Object
show all
Includes:
Helpers
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=>"No longer supported and will be removed in a future release",
       :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 +
""}

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#code_maybe_block

Constructor Details

#initialize(registry, component_type) ⇒ Base

Returns a new instance of Base.



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

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

Class Method Details

.group_name(name = nil) ⇒ String

Set or return the name of the group

Parameters:

  • Name (Optional[String]) —

    of the group to set

Returns:

  • (String) —

    Name of the group



62
63
64
65
 
# File 'lib/puppet-strings/markdown/base.rb', line 62

def self.group_name(name = nil)
  @group_name = name if name
  @group_name
end

.items ⇒ Array

Returns list of items.

Returns:

  • (Array) —

    list of items



77
78
79
80
81
82
83
 
# 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

.yard_types(types = nil) ⇒ Array[Symbol]

Set or return the types registered with YARD

Parameters:

  • Array (Optional[Array[Symbol]]) —

    of symbols registered with YARD to set

Returns:

  • (Array[Symbol]) —

    Array of symbols registered with YARD



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

def self.yard_types(types = nil)
  @yard_types = types if types
  @yard_types
end

Instance Method Details

#defaults ⇒ Hash

Returns any defaults found for the component.

Returns:

  • (Hash) —

    any defaults found for the component



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

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

#enums ⇒ Array

Returns enum tag hashes.

Returns:

  • (Array) —

    enum tag hashes



155
156
157
 
# File 'lib/puppet-strings/markdown/base.rb', line 155

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



170
171
172
173
 
# 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 ⇒ Array

Returns example tag hashes.

Returns:

  • (Array) —

    example tag hashes



140
141
142
 
# File 'lib/puppet-strings/markdown/base.rb', line 140

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



191
192
193
 
# File 'lib/puppet-strings/markdown/base.rb', line 191

def link
  clean_link(name)
end

#name ⇒ String

Returns top-level name.

Returns:

  • (String) —

    top-level name



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

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

#options ⇒ Array

Returns option tag hashes.

Returns:

  • (Array) —

    option tag hashes



150
151
152
 
# File 'lib/puppet-strings/markdown/base.rb', line 150

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



162
163
164
165
 
# 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 ⇒ Array

Returns parameter tag hashes.

Returns:

  • (Array) —

    parameter tag hashes



131
132
133
134
135
136
137
 
# 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? ⇒ Boolean

Returns:

  • (Boolean) 


195
196
197
 
# File 'lib/puppet-strings/markdown/base.rb', line 195

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

#raises ⇒ Array

Returns raise tag hashes.

Returns:

  • (Array) —

    raise tag hashes



145
146
147
 
# File 'lib/puppet-strings/markdown/base.rb', line 145

def raises
  select_tags('raise')
end

#render(template) ⇒ String

Returns full markdown rendering of a component.

Returns:

  • (String) —

    full markdown rendering of a component



208
209
210
211
212
213
214
215
 
# 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 ⇒ String

Returns data type of return value.

Returns:

  • (String) —

    data type of return value



116
117
118
 
# 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 ⇒ Array

Returns @see tag hashes.

Returns:

  • (Array) —

    @see tag hashes



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

def see
  select_tags('see')
end

#since ⇒ String

Returns text from @since tag.

Returns:

  • (String) —

    text from @since tag



121
122
123
 
# 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 ⇒ String

Returns ‘Overview’ text (untagged text).

Returns:

  • (String) —

    ‘Overview’ text (untagged text)



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

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



181
182
183
184
185
186
187
188
 
# 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") ⇒ Object 



199
200
201
202
203
204
205
 
# 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