openvox-strings 5.0.0

data/lib/openvox-strings/yard/parsers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# The module for custom YARD parsers.
+module OpenvoxStrings::Yard::Parsers
+  # The module for custom YARD parsers for JSON.
+  module JSON
+    require 'openvox-strings/yard/parsers/json/parser'
+  end
+
+  # The module for custom YARD parsers for the Puppet language.
+  module Puppet
+    require 'openvox-strings/yard/parsers/puppet/parser'
+  end
+end

data/lib/openvox-strings/yard/tags/enum_tag.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'yard/tags/option_tag'
+
+# Implements an enum tag for describing enumerated value data types
+class OpenvoxStrings::Yard::Tags::EnumTag < YARD::Tags::OptionTag
+  # Registers the tag with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_tag('puppet.enum', :enum, :with_enums)
+    YARD::Tags::Library.visible_tags.place(:enum).after(:option)
+  end
+end

data/lib/openvox-strings/yard/tags/factory.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'yard/tags/default_factory'
+require 'openvox-strings/yard/tags/enum_tag'
+
+# Factory for creating tags.
+class OpenvoxStrings::Yard::Tags::Factory < YARD::Tags::DefaultFactory
+  # Parses tag text and creates a new enum tag type. Modeled after
+  # the parse_tag_with_options method in YARD::Tags::DefaultFactory.
+  #
+  # @param tag_name        the name of the tag to parse
+  # @param [String] text   the raw tag text
+  # @return [Tag]          a tag object with the tag_name, name, and nested Tag as type
+  def parse_tag_with_enums(tag_name, text)
+    name, text = *extract_name_from_text(text)
+    OpenvoxStrings::Yard::Tags::EnumTag.new(tag_name, name, parse_tag_with_name(tag_name, text))
+  end
+end

data/lib/openvox-strings/yard/tags/overload_tag.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Implements an overload tag for Puppet functions
+#
+# This differs from Yard's overload tag in that the signatures are formatted according to Puppet language rules.
+class OpenvoxStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
+  attr_reader :parameters, :docstring
+
+  # Initializes the overload tag.
+  # @param [String, Symbol] name The name of the function being overloaded.
+  # @param [String] docstring The docstring for the overload.
+  # @return [void]
+  def initialize(name, docstring)
+    super(:overload, nil)
+    @name = name.to_s
+    @parameters = []
+    @docstring = YARD::Docstring.new(docstring)
+  end
+
+  # Gets the signature of the overload.
+  # @return [String] Returns the signature of the overload.
+  def signature
+    tags = self.tags(:param)
+    args = @parameters.map do |parameter|
+      name, default = parameter
+      tag = tags.find { |t| t.name == name } if tags
+      type = tag&.types ? "#{tag.type} " : 'Any '
+      prefix = (name[0]).to_s if name.start_with?('*', '&')
+      name = name[1..] if prefix
+      default = " = #{default}" if default
+      "#{type}#{prefix}$#{name}#{default}"
+    end.join(', ')
+    "#{@name}(#{args})"
+  end
+
+  # Adds a tag to the overload's docstring.
+  # @param [YARD::Tag] tag The tag to add to the overload's docstring.
+  # @return [void]
+  def add_tag(tag)
+    @docstring.add_tag(tag)
+  end
+
+  # Gets the first tag of the given name.
+  # @param [String, Symbol] name The name of the tag.
+  # @return [YARD::Tag] Returns the first tag if found or nil if not found.
+  def tag(name)
+    @docstring.tag(name)
+  end
+
+  # Gets all tags or tags of a given name.
+  # @param [String, Symbol] name The name of the tag to get or nil for all tags.
+  # @return [Array<Yard::Tag>] Returns an array of tags.
+  def tags(name = nil)
+    @docstring.tags(name)
+  end
+
+  # Determines if a tag with the given name is present.
+  # @param [String, Symbol] name The tag name.
+  # @return [Boolean] Returns true if there is at least one tag with the given name or false if not.
+  def has_tag?(name) # rubocop:disable Naming/PredicateName
+    @docstring.has_tag?(name)
+  end
+
+  # Sets the object associated with this tag.
+  # @param [Object] value The object to associate with this tag.
+  # @return [void]
+  def object=(value)
+    super
+    @docstring.object = value
+    @docstring.tags.each { |tag| tag.object = value }
+  end
+
+  # Responsible for forwarding method calls to the associated object.
+  # @param [Symbol] method_name The method being invoked.
+  # @param [Array] args The args passed to the method.
+  # @param block The block passed to the method.
+  # @return Returns what the method call on the object would return.
+  def method_missing(method_name, ...)
+    return object.send(method_name, ...) if object.respond_to? method_name
+
+    super
+  end
+
+  # Determines if the associated object responds to the give missing method name.
+  # @param [Symbol, String] method_name The name of the method to check.
+  # @param [Boolean] include_all True to include all methods in the check or false for only public methods.
+  # @return [Boolean] Returns true if the object responds to the method or false if not.
+  def respond_to_missing?(method_name, include_all = false)
+    object.respond_to?(method_name, include_all) || super
+  end
+
+  # Gets the type of the object associated with this tag.
+  # @return [Symbol] Returns the type of the object associated with this tag.
+  def type
+    object.type
+  end
+
+  # Converts the overload tag to a hash representation.
+  # @return [Hash] Returns a hash representation of the overload.
+  def to_hash
+    hash = {}
+    hash[:tag_name] = tag_name
+    hash[:text] = text if text
+    hash[:signature] = signature
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring) unless docstring.blank?
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:types] = types if types
+    hash[:name] = name if name
+    hash
+  end
+end

data/lib/openvox-strings/yard/tags/parameter_directive.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects'
+
+# Implements a parameter directive (e.g. #@!puppet.type.param) for documenting Puppet resource types.
+class OpenvoxStrings::Yard::Tags::ParameterDirective < YARD::Tags::Directive
+  # Called to invoke the directive.
+  # @return [void]
+  def call
+    return unless object.respond_to?(:add_parameter)
+
+    # Add a parameter to the resource
+    parameter = OpenvoxStrings::Yard::CodeObjects::Type::Parameter.new(tag.name, tag.text)
+    tag.types&.each do |value|
+      parameter.add(value)
+    end
+    object.add_parameter parameter
+  end
+
+  # Registers the directive with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_directive('puppet.type.param', :with_types_and_name, self)
+  end
+end

data/lib/openvox-strings/yard/tags/property_directive.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects'
+
+# Implements a parameter directive (e.g. #@!puppet.type.property) for documenting Puppet resource types.
+class OpenvoxStrings::Yard::Tags::PropertyDirective < YARD::Tags::Directive
+  # Called to invoke the directive.
+  # @return [void]
+  def call
+    return unless object.respond_to?(:add_property)
+
+    # Add a property to the resource
+    property = OpenvoxStrings::Yard::CodeObjects::Type::Property.new(tag.name, tag.text)
+    tag.types&.each do |value|
+      property.add(value)
+    end
+    object.add_property property
+  end
+
+  # Registers the directive with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_directive('puppet.type.property', :with_types_and_name, self)
+  end
+end

data/lib/openvox-strings/yard/tags/summary_tag.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Implements a summary tag for general purpose short descriptions
+class OpenvoxStrings::Yard::Tags::SummaryTag < YARD::Tags::Tag
+  # Registers the tag with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_tag('puppet.summary', :summary)
+  end
+end

data/lib/openvox-strings/yard/tags.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The module for custom YARD tags.
+module OpenvoxStrings::Yard::Tags
+  require 'openvox-strings/yard/tags/factory'
+  require 'openvox-strings/yard/tags/parameter_directive'
+  require 'openvox-strings/yard/tags/property_directive'
+  require 'openvox-strings/yard/tags/overload_tag'
+  require 'openvox-strings/yard/tags/summary_tag'
+  require 'openvox-strings/yard/tags/enum_tag'
+end

data/lib/openvox-strings/yard/templates/default/fulldoc/html/css/common.css

@@ -0,0 +1,8 @@
+/* Ensure the search bar doesn't overlap with links */
+.fixed_header {
+  padding-bottom: 25px;
+}
+
+#full_list {
+  padding-top: 15px;
+}

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_class.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(false)) %>
+        <% if item.type == :puppet_data_type_alias %><small>Alias</small><% end %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_function.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(false)) %>
+        <small><%= item.function_type %></small>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_plan.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_provider.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+        <small>Resource type: <em><%=item.type_name%></em></small>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_task.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/full_list_puppet_type.erb

@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/openvox-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Generates the searchable Puppet class list.
+# @return [void]
+def generate_puppet_class_list
+  @items = Registry.all(:puppet_class).sort_by { |c| c.name.to_s }
+  @list_title = 'Puppet Class List'
+  @list_type = 'puppet_class'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet data type list.
+# @return [void]
+def generate_puppet_data_type_list
+  @items = Registry.all(:puppet_data_type, :puppet_data_type_alias).sort_by { |dt| dt.name.to_s }
+  @list_title = 'Data Type List'
+  @list_type = 'puppet_data_type'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet defined type list.
+# @return [void]
+def generate_puppet_defined_type_list
+  @items = Registry.all(:puppet_defined_type).sort_by { |dt| dt.name.to_s }
+  @list_title = 'Defined Type List'
+  @list_type = 'puppet_defined_type'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet resource type list.
+# @return [void]
+def generate_puppet_type_list
+  @items = Registry.all(:puppet_type).sort_by { |t| t.name.to_s }
+  @list_title = 'Resource Type List'
+  @list_type = 'puppet_type'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet provider list.
+# @return [void]
+def generate_puppet_provider_list
+  @items = Registry.all(:puppet_provider).sort_by { |p| p.name.to_s }
+  @list_title = 'Provider List'
+  @list_type = 'puppet_provider'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet function list.
+# @return [void]
+def generate_puppet_function_list
+  @items = Registry.all(:puppet_function).sort_by { |f| f.name.to_s }
+  @list_title = 'Puppet Function List'
+  @list_type = 'puppet_function'
+  generate_list_contents
+end
+
+# Generates the searchable Ruby method list.
+# @return [void]
+def generate_method_list
+  @items = prune_method_listing(Registry.all(:method), false)
+  @items = @items.reject { |m| m.name.to_s =~ /=$/ && m.is_attribute? }
+  @items = @items.sort_by { |m| m.name.to_s }
+  @list_title = 'Ruby Method List'
+  @list_type = 'method'
+  generate_list_contents
+end
+
+# Generate a searchable Ruby class list in the output.
+# @return [void]
+def generate_class_list
+  @items = options.objects if options.objects
+  @list_title = 'Ruby Class List'
+  @list_type = 'class'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet Task list.
+# @return [void]
+def generate_puppet_task_list
+  @items = Registry.all(:puppet_task).sort_by { |t| t.name.to_s }
+  @list_title = 'Puppet Task List'
+  @list_type = 'puppet_task'
+  generate_list_contents
+end
+
+# Generates the searchable Puppet Plan list.
+# @return [void]
+def generate_puppet_plan_list
+  @items = Registry.all(:puppet_plan).sort_by { |t| t.name.to_s }
+  @list_title = 'Puppet Plan List'
+  @list_type = 'puppet_plan'
+  generate_list_contents
+end

data/lib/openvox-strings/yard/templates/default/layout/html/footer.erb

@@ -0,0 +1,3 @@
+<div id="footer">
+     Generated by <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>.
+</div>

data/lib/openvox-strings/yard/templates/default/layout/html/objects.erb

@@ -0,0 +1,37 @@
+<% unless @objects_by_letter.empty? %>
+<h2><%= @title %></h2>
+
+  <% i = 0 %>
+<table>
+  <tr>
+    <td valign='top' width="33%">
+  <% @objects_by_letter.sort_by {|l,o| l.to_s }.each do |letter, objects| %>
+    <% if (i += 1) % 8 == 0 %>
+    </td>
+    <td valign='top' width="33%">
+      <% i = 0 %>
+    <% end %>
+      <ul id="alpha_<%= letter %>" class="alpha">
+        <li class="letter"><%= letter %></li>
+          <ul>
+    <% objects.each do |obj| %>
+            <li>
+      <%= linkify obj, obj.name %>
+      <% if (obj.type == :module || obj.type == :class) && !obj.namespace.root? %>
+              <small>(<%= obj.namespace.path %>)</small>
+      <% elsif obj.type == :puppet_provider %>
+              <small>(Resource type: <%= obj.type_name %>)</small>
+      <% elsif obj.type == :puppet_function %>
+              <small>(<%= obj.function_type %>)</small>
+      <% elsif obj.type == :puppet_data_type_alias %>
+              <small>(Alias)</small>
+      <% end %>
+            </li>
+    <% end %>
+      </ul>
+    </ul>
+  <% end %>
+    </td>
+  </tr>
+</table>
+<% end %>