puppet-strings 2.1.0 → 2.5.0

data/lib/puppet-strings/yard/parsers/puppet/parser.rb

@@ -41,41 +41,48 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
   end
 
   private
-  def transform_Program(o)
+
+  def transform_Program(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     # Cache the lines of the source text; we'll use this to locate comments
     @lines = o.source_text.lines.to_a
     o.definitions.map { |d| @visitor.visit(d) }
   end
 
-  def transform_Factory(o)
+  def transform_Factory(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     @visitor.visit(o.current)
   end
 
-  def transform_HostClassDefinition(o)
+  def transform_HostClassDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::ClassStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_ResourceTypeDefinition(o)
+  def transform_ResourceTypeDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_FunctionDefinition(o)
+  def transform_FunctionDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::FunctionStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_PlanDefinition(o)
+  def transform_PlanDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::PlanStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_Object(o)
+  def transform_TypeAlias(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+    statement = PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_Object(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     # Ignore anything else (will be compacted out of the resulting array)
   end
 end

data/lib/puppet-strings/yard/parsers/puppet/statement.rb

@@ -165,4 +165,29 @@ module PuppetStrings::Yard::Parsers::Puppet
     end
   end
 
+  # Implements the Puppet data type alias statement.
+  class DataTypeAliasStatement < Statement
+    attr_reader :name
+    attr_reader :alias_of
+
+    # Initializes the Puppet data type alias statement.
+    # @param [Puppet::Pops::Model::TypeAlias] object The model object for the type statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super(object, file)
+
+      type_expr = object.type_expr
+      case type_expr
+      when Puppet::Pops::Model::AccessExpression
+        # TODO: I don't like rebuilding the source from the AST, but AccessExpressions don't expose the original source
+        @alias_of = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr.left_expr).extract_text + '['
+        @alias_of << type_expr.keys.map { |key| ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(key).extract_text }.join(', ')
+        @alias_of << ']'
+      else
+        adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr)
+        @alias_of = adapter.extract_text
+      end
+      @name = object.name
+    end
+  end
 end

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

@@ -1,7 +1,9 @@
 # The module for custom YARD tags.
 module PuppetStrings::Yard::Tags
+  require 'puppet-strings/yard/tags/factory'
   require 'puppet-strings/yard/tags/parameter_directive'
   require 'puppet-strings/yard/tags/property_directive'
   require 'puppet-strings/yard/tags/overload_tag'
   require 'puppet-strings/yard/tags/summary_tag'
+  require 'puppet-strings/yard/tags/enum_tag'
 end

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

@@ -0,0 +1,12 @@
+require 'yard/tags/option_tag'
+
+# Implements an enum tag for describing enumerated value data types
+
+class PuppetStrings::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/puppet-strings/yard/tags/factory.rb

@@ -0,0 +1,16 @@
+require 'yard/tags/default_factory'
+require 'puppet-strings/yard/tags/enum_tag'
+
+class PuppetStrings::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)
+    PuppetStrings::Yard::Tags::EnumTag.new(tag_name, name, parse_tag_with_name(tag_name, text))
+  end
+end

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

@@ -99,8 +99,8 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
     hash[:tag_name] = tag_name
     hash[:text] = text if text
     hash[:signature] = signature
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) if !docstring.blank?
-    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring) if !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

data/lib/puppet-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/puppet-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -7,6 +7,15 @@ def generate_puppet_class_list
   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

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

@@ -23,6 +23,8 @@
               <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 %>

data/lib/puppet-strings/yard/templates/default/layout/html/setup.rb

@@ -4,7 +4,7 @@ def init
   case object
   when '_index.html'
     @page_title = options.title
-    sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
+    sections :layout, [:index, [:listing, [:classes, :data_types, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
   else
     super
   end
@@ -30,6 +30,10 @@ def layout
     @nav_url = url_for_list('puppet_class')
     @page_title = "Puppet Class: #{object.name}"
     @path = object.path
+  when PuppetStrings::Yard::CodeObjects::DataType, PuppetStrings::Yard::CodeObjects::DataTypeAlias
+    @nav_url = url_for_list('puppet_data_type')
+    @page_title = "Data Type: #{object.name}"
+    @path = object.path
   when PuppetStrings::Yard::CodeObjects::DefinedType
     @nav_url = url_for_list('puppet_defined_type')
     @page_title = "Defined Type: #{object.name}"
@@ -76,6 +80,11 @@ def create_menu_lists
       title: 'Puppet Classes',
       search_title: 'Puppet Classes'
     },
+    {
+      type: 'puppet_data_type',
+      title: 'Data Types',
+      search_title: 'Data Types',
+    },
     {
       type: 'puppet_defined_type',
       title: 'Defined Types',
@@ -155,6 +164,14 @@ def classes
   erb(:objects)
 end
 
+# Renders the data types section.
+# @return [String] Returns the rendered section.
+def data_types
+  @title = 'Data Type Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_data_type, :puppet_data_type_alias)
+  erb(:objects)
+end
+
 # Renders the defined types section.
 # @return [String] Returns the rendered section.
 def defined_types

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Data Type: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/method_details_list.erb

@@ -0,0 +1,6 @@
+<h2>Data Type Functions</h2>
+<% method_listing.each_with_index do |meth, i| %>
+  <div id="<%= meth.name %>-instance_method"><h3><%= meth.name %></h3>
+  <%= yieldall :object => meth, :owner => object, :index => i %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/setup.rb

@@ -0,0 +1,13 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :method_details_list, [T('method_details')], :source
+end
+
+def method_listing
+  sort_listing(object.functions)
+end
+
+def sort_listing(list)
+  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
+end

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/alias_of.erb

@@ -0,0 +1,10 @@
+<% if @alias_of && !@alias_of.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <div class="docstring">
+    <div class="discussion">
+      <pre class="code"><span class="info"><%= @alias_of %></span></pre>
+    </div>
+  </div>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Data Type Alias: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/setup.rb

@@ -0,0 +1,17 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :alias_of, :note, :todo, T('tags'), :source
+end
+
+# Renders the alias_of section.
+# @return [String] Returns the rendered section.
+def alias_of
+  # Properties are the same thing as parameters (from the documentation standpoint),
+  # so reuse the same template but with a different title and data source.
+  #@parameters = object.properties || []
+  #@parameters.sort_by! { |p| p.name }
+  @tag_title = 'Alias of'
+  @alias_of = object.alias_of
+  erb(:alias_of)
+end

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb

@@ -16,7 +16,9 @@ end
 def properties
   # Properties are the same thing as parameters (from the documentation standpoint),
   # so reuse the same template but with a different title and data source.
-  @parameters = object.properties || []
+  #
+  # "checks" such as "creates" and "onlyif" are another type of property
+  @parameters = (object.properties || []) + (object.checks || [])
   @parameters.sort_by! { |p| p.name }
   @tag_title = 'Properties'
   erb(:parameters)

data/lib/puppet-strings/yard/templates/default/tags/html/enum.erb

@@ -0,0 +1,17 @@
+<% if object.has_tag?(:enum) %>
+  <% object.parameters.each do |param, default| %>
+    <% tags = object.tags(:enum).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
+    <% next if tags.empty? %>
+    <p class="tag_title">Enum Options (<tt><%= param %></tt>):</p>
+    <ul class="option">
+      <% for tag in tags %>
+        <li>
+          <span class="name"><%= tag.pair.name %></span>
+          <% if tag.pair.text && tag.pair.text =~ /\S/ %>
+            &mdash; <%= htmlify_line(tag.pair.text) %>
+          <% end %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/tags/setup.rb

@@ -4,6 +4,7 @@ def param
   tag(:param) if
     object.type == :method ||
     object.type == :puppet_class ||
+    object.type == :puppet_data_type ||
     object.type == :puppet_defined_type ||
     object.type == :puppet_function ||
     object.type == :puppet_task ||
@@ -15,3 +16,9 @@ end
 def overload
   erb(if object.type == :puppet_function then :puppet_overload else :overload end)
 end
+
+# Renders the enum section.
+# @return [String] Returns the rendered section.
+def enum
+  erb(:enum)
+end

data/lib/puppet-strings/yard/util.rb

@@ -28,4 +28,52 @@ module PuppetStrings::Yard::Util
     end
     data
   end
+
+  # 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.
+  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
+
+  # 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.
+  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
 end