puppet-strings 0.4.0

data/lib/puppet_x/puppetlabs/strings/yard/json_registry_store.rb

@@ -0,0 +1,85 @@
+module YARD
+
+  class JsonRegistryStore < RegistryStore
+    def save(merge=true, file=nil)
+      super
+
+      @serializer = Serializers::JsonSerializer.new(@file)
+
+      sdb = Registry.single_object_db
+      if sdb == true || sdb == nil
+        serialize_output_schema(@store)
+      else
+        values(false).each do |object|
+          serialize_output_schema(object)
+        end
+      end
+      true
+    end
+
+    # @param obj [Hash] A hash representing the registry or part of the
+    # registry.
+    def serialize_output_schema(obj)
+
+        schema = {
+          :puppet_functions => [],
+          :puppet_providers => [],
+          :puppet_classes => [],
+          :defined_types => [],
+          :puppet_types => [],
+        }
+
+        schema[:puppet_functions] += obj.select do |key, val|
+          val.type == :method and (val['puppet_4x_function'] or
+                                   val['puppet_3x_function'])
+        end.values
+
+        schema[:puppet_classes] += obj.select do |key, val|
+          val.type == :hostclass
+        end.values
+
+        schema[:defined_types] += obj.select do |key, val|
+          val.type == :definedtype
+        end.values
+
+        schema[:puppet_providers] += obj.select do |key, val|
+          val.type == :provider
+        end.values
+
+        schema[:puppet_types] += obj.select do |key, val|
+          val.type == :type
+        end.values
+
+        @serializer.serialize(schema.to_json)
+    end
+  end
+
+  # Override the serializer because it puts the data at a wacky path and, more
+  # importantly, marshals the data with a bunch of non-printable characters.
+  module Serializers
+    class JsonSerializer < YardocSerializer
+
+      def initialize o
+        super
+        @options = {
+          :basepath => '.',
+          :extension => 'json',
+        }
+        @extension = 'json'
+        @basepath = '.'
+      end
+      def serialize(data)
+
+        if YARD::Config.options[:emit_json]
+          path = YARD::Config.options[:emit_json]
+          log.debug "Serializing json to #{path}"
+          File.open!(path, "wb") {|f| f.write data }
+        end
+        if YARD::Config.options[:emit_json_stdout]
+          puts data
+        end
+      end
+    end
+  end
+
+end

data/lib/puppet_x/puppetlabs/strings/yard/monkey_patches.rb

@@ -0,0 +1,68 @@
+require 'yard'
+require File.join(File.dirname(__FILE__), './json_registry_store')
+
+# TODO: As far as I can tell, monkeypatching is the officially recommended way
+# to extend these tools to cover custom usecases. Follow up on the YARD mailing
+# list or IRC to see if there is a better way.
+
+class YARD::CLI::Yardoc
+  def all_objects
+    YARD::Registry.all(:root, :module, :class, :type, :provider, :puppetnamespace, :hostclass, :definedtype)
+  end
+end
+
+class YARD::CLI::Stats
+  def stats_for_hostclasses
+    output 'Puppet Classes', *type_statistics(:hostclass)
+  end
+
+  def stats_for_definedtypes
+    output 'Puppet Defined Types', *type_statistics(:definedtype)
+  end
+
+  def stats_for_puppet_types
+    output 'Puppet Types', *type_statistics(:type)
+  end
+
+  def stats_for_puppet_provider
+    output 'Puppet Providers', *type_statistics(:provider)
+  end
+end
+
+class YARD::Logger
+  def show_progress
+    return false if YARD.ruby18? # threading is too ineffective for progress support
+    return false if YARD.windows? # windows has poor ANSI support
+    return false unless io.tty? # no TTY support on IO
+    # Here is the actual monkey patch. A simple fix to an inverted conditional.
+    # Without this Pry is unusable for debugging as the progress bar goes
+    # craaaaaaaazy.
+    return false unless level > INFO # no progress in verbose/debug modes
+    @show_progress
+  end
+
+  # Redirect Yard command line warnings to a log file called .yardwarns
+  # Yard warnings may be irrelevant, spurious, or may not conform with our
+  # styling and UX design. They are also printed on stdout by default.
+  def warn warning
+    f = File.new '.yardwarns', 'a'
+    f.write warning
+    f.close()
+  end
+end
+
+
+# 15:04:42       radens | lsegal: where would you tell yard to use your custom RegistryStore?
+# 15:09:54      @lsegal | https://github.com/lsegal/yard/blob/master/lib/yard/registry.rb#L428-L435
+# 15:09:54      @lsegal | you would set that attr on Registry
+# 15:09:54      @lsegal | it might be worth expanding that API to swap out the store class used
+# 15:10:49      @lsegal | specifically
+#                       | https://github.com/lsegal/yard/blob/master/lib/yard/registry.rb#L190 and
+#                       | replace RegistryStore there with a storage_class attr
+module YARD::Registry
+  class << self
+  def clear
+    self.thread_local_store = YARD::JsonRegistryStore.new
+  end
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/parser.rb

@@ -0,0 +1,30 @@
+require 'yard'
+require 'puppet/pops'
+
+require 'puppet_x/puppetlabs/strings'
+require 'puppet_x/puppetlabs/strings//pops/yard_transformer'
+
+class PuppetX::PuppetLabs::Strings::YARD::PuppetParser < YARD::Parser::Base
+  attr_reader :file, :source
+
+  def initialize(source, filename)
+    @source = source
+    @file = filename
+
+    @parser = Puppet::Pops::Parser::Parser.new()
+    @transformer = PuppetX::PuppetLabs::Strings::Pops::YARDTransformer.new()
+  end
+
+  def parse
+    @parse_result ||= @parser.parse_string(source)
+    self
+  end
+
+  def enumerator
+    statements = @transformer.transform(@parse_result)
+
+    # Ensure an array is returned and prune any nil values.
+    Array(statements).compact.reverse
+  end
+
+end

data/lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb

@@ -0,0 +1,9 @@
+require 'puppet_x/puppetlabs/strings/yard/core_ext/yard'
+# Creates a new code object based on the directive
+class PuppetX::PuppetLabs::Strings::YARD::Tags::PuppetTypeParameterDirective < YARD::Tags::Directive
+  def call
+    return if object.nil?
+    object.parameters << ([tag.text, tag.types].flatten)
+    object.parameter_details << {:name => tag.name, :desc => tag.text, :exists? => true, :puppet_type => true}
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb

@@ -0,0 +1,34 @@
+<div class="docstring">
+  <div class="discussion">
+    <p><%= htmlify(@class_details[:desc]) %></p>
+  </div>
+</div>
+<div class="tags">
+  <% if @class_details[:examples] != {}%>
+    <div class="examples">
+    <p class="tag_title">Examples:</p>
+    <% @class_details[:examples].each do |title, text| %>
+      <div class="inline"><p><%= title %></p></div>
+      <pre class="example code"><code><span><%= text %></span></code></pre>
+    <% end %>
+    </div>
+  <% end %>
+  <% if @class_details[:since] %>
+    <p class="tag_title">Since:</p>
+    <ul class="since">
+      <li>
+        <div class="inline">
+          <p><%= @class_details[:since] %></p>
+        </div>
+      </li>
+    </ul>
+  <% end %>
+  <% if @class_details[:return] %>
+    <p class="tag_title">Return:</p>
+    <ul class="return">
+      <li>
+        <%= @html_helper.generate_return_types(@class_details[:return][1], @class_details[:return][0]) %>
+      </li>
+    </ul>
+  <% end %>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/header.erb

@@ -0,0 +1,5 @@
+<div class='module_header'>
+  <h1>
+    <%= @header_text %>
+  </h1>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb

@@ -0,0 +1,6 @@
+<h2>Parameter Summary</h2>
+<div class="tags">
+  <ul class="param">
+    <%= @html_helper.generate_parameters(@param_details, object) %>
+  </ul>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/setup.rb

@@ -0,0 +1 @@
+include T('default/module/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/setup.rb

@@ -0,0 +1,49 @@
+include T('default/module')
+
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
+def init
+  sections :header, :box_info, :pre_docstring, :docstring, :parameter_details
+
+  @template_helper = TemplateHelper.new
+  @html_helper = HTMLHelper.new
+  @template_helper.check_parameters_match_docs object
+  params = object.parameters.map { |param| param.first }
+  param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+  param_details = @template_helper.extract_param_details(params, param_tags) unless params.nil?
+  @template_helper.check_types_match_docs object, param_details
+
+end
+
+def parameter_details
+  return if object.parameters.empty?
+
+  param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+  params = object.parameters
+
+  @param_details = []
+
+  @param_details = @template_helper.extract_param_details(params, param_tags, true)
+
+  erb(:parameter_details)
+end
+
+def header
+  if object.type == :hostclass
+    @header_text = "Puppet Class: #{object.name}"
+  elsif object.type == :definedtype
+    @header_text = "Puppet Defined Type: #{object.name}"
+  else
+    @header_text = "#{object.name}"
+  end
+
+  erb(:header)
+end
+
+def docstring
+
+  @class_details = @template_helper.extract_tag_data(object)
+
+  erb(:docstring)
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_class.erb

@@ -0,0 +1,2 @@
+<li><%= link_object(Registry.root, Registry.root.title, nil, false) %></li>
+<%= namespace_list %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_manifest.erb

@@ -0,0 +1 @@
+<%= namespace_list(:namespace_types => [:hostclass, :definedtype]) %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_plugin.erb

@@ -0,0 +1,21 @@
+<% unless P(:root, 'Puppet3xFunctions').is_a?(CodeObjects::Proxy) %>
+<li>
+  <a class='toggle'></a>
+  <%= link_object(P(:root, 'Puppet3xFunctions'), 'Puppet 3x Functions', nil, false) %>
+  <small class='search_info'>Puppet3xFunctions</small>
+</li>
+<ul>
+  <%= namespace_list(:root => P(:root,'Puppet3xFunctions'), :namespace_types => [:puppetnamespace, :method]) %>
+</ul>
+<% end %>
+
+<% unless P(:root, 'Puppet4xFunctions').is_a?(CodeObjects::Proxy) %>
+<li>
+  <a class='toggle'></a>
+  <%= link_object(P(:root, 'Puppet4xFunctions'), 'Puppet 4x Functions', nil, false) %>
+  <small class='search_info'>Puppet4xFunctions</small>
+</li>
+<ul>
+  <%= namespace_list(:root => P(:root,'Puppet4xFunctions'), :namespace_types => [:puppetnamespace, :method]) %>
+</ul>
+<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_provider.erb

@@ -0,0 +1 @@
+<%= namespace_list(:namespace_types => [:provider]) %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_type.erb

@@ -0,0 +1 @@
+<%= namespace_list(:namespace_types => [:type]) %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,82 @@
+def generate_class_list
+  @items = options.objects.select{|o| [:module, :class, :root].include? o.type} if options.objects
+  @list_title = "Class List"
+  @list_type = "class"
+  generate_list_contents
+end
+
+def generate_puppet_manifest_list
+  @items = options.objects.select{|o| [:hostclass, :definedtype].include? o.type} if options.objects
+  @list_title = "Puppet Manifest List"
+  # This is important. It causes some YARD JavaScript bits to hook in and
+  # perform the correct formatting.
+  @list_class = "class"
+  @list_type = "puppet_manifest"
+  generate_list_contents
+end
+
+def generate_puppet_plugin_list
+  # NOTE: PuppetNamaspaceObject might eventually be used for more than just a
+  # container for plugins...
+  @items = options.objects.select{|o| [:puppetnamespace].include? o.type} if options.objects
+  @list_title = "Puppet Plugin List"
+  # This is important. It causes some YARD JavaScript bits to hook in and
+  # perform the correct formatting.
+  @list_class = "class"
+  @list_type = "puppet_plugin"
+  generate_list_contents
+end
+
+def generate_puppet_type_list
+  @items = options.objects.select{|o| [:type].include? o.type} if options.objects
+  @list_title = "Puppet Type List"
+  @list_type = "puppet_type"
+  generate_list_contents
+end
+
+def generate_puppet_provider_list
+  @items = options.objects.select{|o| [:provider].include? o.type} if options.objects
+  @list_title = "Puppet Provider List"
+  @list_type = "puppet_provider"
+  generate_list_contents
+end
+
+# A hacked version of class_list that can be instructed to only display certain
+# namespace types. This allows us to separate Puppet bits from Ruby bits.
+def namespace_list(opts = {})
+  o = {
+    :root => Registry.root,
+    :namespace_types => [:module, :class]
+  }.merge(opts)
+
+  root = o[:root]
+  namespace_types = o[:namespace_types]
+
+  out = ""
+  children = run_verifier(root.children)
+  if root == Registry.root
+    children += @items.select {|o| o.namespace.is_a?(CodeObjects::Proxy) }
+  end
+  children.reject {|c| c.nil? }.sort_by {|child| child.path }.map do |child|
+    if namespace_types.include? child.type
+      if child.namespace.is_a?(CodeObjects::Proxy)
+        name = child.path
+      elsif child.is_a?(PuppetX::PuppetLabs::Strings::YARD::CodeObjects::TypeObject) || child.is_a?(PuppetX::PuppetLabs::Strings::YARD::CodeObjects::ProviderObject)
+        name = child.header_name
+      else
+        name = child.name
+      end
+      has_children = child.respond_to?(:children) && run_verifier(child.children).any? {|o| o.is_a?(CodeObjects::NamespaceObject) }
+      out << "<li>"
+      out << "<a class='toggle'></a> " if has_children
+      out << linkify(child, name)
+      out << " &lt; #{child.superclass.name}" if child.is_a?(CodeObjects::ClassObject) && child.superclass
+      out << "<small class='search_info'>"
+      out << child.namespace.title
+      out << "</small>"
+      out << "</li>"
+      out << "<ul>#{namespace_list(:root => child, :namespace_types => namespace_types)}</ul>" if has_children
+    end
+  end
+  out
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/html/box_info.erb

@@ -0,0 +1,22 @@
+<% n = 1 %>
+<dl class="box">
+  <% if object.parent_class %>
+    <dt class="r<%=n%>">Inherits:</dt>
+    <dd class="r<%=n%>">
+      <span class="inheritName"><%= linkify object.parent_class, object.parent_class.path %></span>
+      <ul class="fullTree">
+        <% object.inheritance_tree.reverse.each_with_index do |obj, i| %>
+          <li class="next"><%= obj == object ? obj.path : linkify(obj, obj.path) %></li>
+        <% end %>
+      </ul>
+      <a href="#" class="inheritanceTree">show all</a>
+    </dd>
+    <% n = 2 %>
+  <% end %>
+  <% unless object.root? %>
+    <dt class="r<%=n%> last">Defined in:</dt>
+    <dd class="r<%=n%> last"><%= erb(:defines) %></dd>
+  <% end %>
+</dl>
+<div class="clear"></div>
+

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/html/setup.rb

@@ -0,0 +1 @@
+include T('default/definedtype/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/html/subclasses.erb

@@ -0,0 +1,4 @@
+<div id="subclasses">
+  <h2>Direct Known Subclasses</h2>
+  <p class="children"><%= @subclasses.map {|child| linkify(child, child.path) }.join(", ") %></p>
+</div>