puppet-strings 0.4.0

data/lib/puppet_x/puppetlabs/strings/yard/code_objects/defined_type_object.rb

@@ -0,0 +1,33 @@
+require 'json'
+
+class PuppetX::PuppetLabs::Strings::YARD::CodeObjects::DefinedTypeObject < PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject
+  # A list of parameters attached to this class.
+  # @return [Array<Array(String, String)>]
+  attr_accessor :parameters
+  attr_accessor :type_info
+
+  def to_s
+    name.to_s
+  end
+
+  def to_json(*a)
+    {
+      "name"             => @name,
+      "file"             => file,
+      "line"             => line,
+      "parameters"       => Hash[@parameters],
+      "docstring"        => Puppet::Util::Docs.scrub(@docstring),
+      "signatures"       => @type_info.map do |signature|
+        signature.map do |key, value|
+          {
+            "name" => key,
+            "type" => value,
+          }
+        end
+      end,
+      "examples"              => self.tags.map do |tag|
+          tag.text if tag.tag_name == 'example'
+      end.compact,
+    }.to_json(*a)
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/code_objects/host_class_object.rb

@@ -0,0 +1,22 @@
+class PuppetX::PuppetLabs::Strings::YARD::CodeObjects::HostClassObject < PuppetX::PuppetLabs::Strings::YARD::CodeObjects::DefinedTypeObject
+  # The {HostClassObject} that this class inherits from, if any.
+  # @return [HostClassObject, Proxy, nil]
+  attr_accessor :parent_class
+
+  # NOTE: `include_mods` is never used as it makes no sense for Puppet, but
+  # this is called by `YARD::Registry` and it will pass a parameter.
+  def inheritance_tree(include_mods = false)
+    if parent_class.is_a?(PuppetX::PuppetLabs::Strings::YARD::CodeObjects::HostClassObject)
+      # Cool. We got a host class. Return self + parent inheritance tree.
+      [self] + parent_class.inheritance_tree
+    elsif parent_class.is_a?(YARD::CodeObjects::Proxy)
+      # We have a reference to a parent that has not been created yet. Just
+      # return it.
+      [self, parent_class]
+    else
+      # Most likely no parent class. But also possibly an object that we
+      # shouldn't inherit from. Just return self.
+      [self]
+    end
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/code_objects/method_object.rb

@@ -0,0 +1,62 @@
+class YARD::CodeObjects::MethodObject
+
+  # Override to_s and to_json methods in Yard's MethodObject so that they
+  # return output formatted as I like for puppet 3x and 4x methods.
+  def to_s
+    if self[:puppet_4x_function] || self[:puppet_3x_function]
+      name.to_s
+    else
+      super
+    end
+  end
+
+  def to_json(*a)
+    if self[:puppet_4x_function]
+      {
+        "name"                  => @name,
+        "file"                  => file,
+        "line"                  => line,
+        "function_api_version"  => 4,
+        "docstring"             => Puppet::Util::Docs.scrub(@docstring),
+        "examples"              => self.tags.map do |tag|
+            tag.text if tag.tag_name == 'example'
+          end.compact,
+        "documented_params"     => @parameters.map do |tuple|
+          {
+            "name" => tuple[0],
+            "type" => tuple[1],
+          }
+        end,
+       "signatures"       => @type_info.map do |signature|
+          signature.map do |key, value|
+            {
+              "name" => key,
+              "type" => value,
+            }
+          end
+        end,
+      }.to_json(*a)
+    elsif self[:puppet_3x_function]
+      {
+        "name"                  => @name,
+        "file"                  => file,
+        "line"                  => line,
+        "function_api_version"  => 3,
+        "docstring"             => Puppet::Util::Docs.scrub(@docstring),
+        "documented_params"     => @parameters.map do |tuple|
+          {
+            "name" => tuple[0],
+            "type" => tuple[1],
+          }
+        end,
+        "examples"              => self.tags.map do |tag|
+            tag.text if tag.tag_name == 'example'
+          end.compact,
+      }.to_json(*a)
+    else
+      super
+    end
+  end
+
+
+end

data/lib/puppet_x/puppetlabs/strings/yard/code_objects/provider_object.rb

@@ -0,0 +1,24 @@
+class PuppetX::PuppetLabs::Strings::YARD::CodeObjects::ProviderObject < PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject
+  # A list of parameters attached to this class.
+  # @return [Array<Array(String, String)>]
+  attr_accessor :parameters
+
+  def to_json(*a)
+    {
+      "name"             => @name,
+      "type_name"        => @type_name,
+      "file"             => file,
+      "line"             => line,
+      "docstring"        => Puppet::Util::Docs.scrub(@docstring),
+      "commands"         => @commands,
+      "confines"         => @confines,
+      "defaults"         => @defaults,
+      "features"         => @features,
+      "examples"              => self.tags.map do |tag|
+          tag.text if tag.tag_name == 'example'
+      end.compact,
+    }.to_json(*a)
+  end
+
+
+end

data/lib/puppet_x/puppetlabs/strings/yard/code_objects/puppet_namespace_object.rb

@@ -0,0 +1,48 @@
+class PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject < YARD::CodeObjects::NamespaceObject
+
+  attr_accessor :type_info
+  # NOTE: `YARD::Registry#resolve` requires a method with this signature to
+  # be present on all subclasses of `NamespaceObject`.
+  def inheritance_tree(include_mods = false)
+    [self]
+  end
+
+  def to_s
+    name.to_s
+  end
+
+  def to_json(*a)
+    {
+      "name"             => @name,
+      "file"             => file,
+      "line"             => line,
+      "docstring"        => @docstring,
+      "examples"              => self.tags.map do |tag|
+          tag.text if tag.tag_name == 'example'
+      end.compact,
+    }.to_json(*a)
+  end
+
+  # FIXME: We used to override `self.new` to ensure no YARD proxies were
+  # created for namespaces segments that did not map to a host class or
+  # defined type. Fighting the system in this way turned out to be
+  # counter-productive.
+  #
+  # However, if a proxy is left in, YARD will drop back to namspace-mangling
+  # heuristics that are very specific to Ruby and which produce ugly paths in
+  # the resulting output. Need to find a way to address this.
+  #
+  # Tried:
+  #
+  #   - Overriding self.new in the code object. Failed because self.new
+  #     overrides are gross and difficult to pull off. Especially when
+  #     replacing an existing override.
+  #
+  #   - Adding functionality to the base handler to ensure something other
+  #     than a proxy occupies each namespace segment. Failed because once a
+  #     code object is created with a namespace, it will never update.
+  #     Unless that namespace is set to a Proxy.
+  #
+  # def self.new(namespace, name, *args, &block)
+end
+

data/lib/puppet_x/puppetlabs/strings/yard/code_objects/type_object.rb

@@ -0,0 +1,42 @@
+class PuppetX::PuppetLabs::Strings::YARD::CodeObjects::TypeObject < PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject
+  # A list of parameters attached to this class.
+  # @return [Array<Array(String, String)>]
+  attr_accessor :parameters
+
+  def to_json(*a)
+    {
+      "name"             => @name,
+      "file"             => file,
+      "line"             => line,
+      "docstring"        => Puppet::Util::Docs.scrub(@docstring),
+      "parameters"       => @parameter_details.map do |obj|
+        {
+          "allowed_values" => obj[:allowed_values] ? obj[:allowed_values].flatten : [],
+          "default"        => obj[:default],
+          "docstring"      => Puppet::Util::Docs.scrub(obj[:desc] || ''),
+          "namevar"        => obj[:namevar],
+          "name"           => obj[:name],
+        }
+      end,
+      "examples"              => self.tags.map do |tag|
+          tag.text if tag.tag_name == 'example'
+      end.compact,
+      "properties"         => @property_details.map do |obj|
+        {
+          "allowed_values" => obj[:allowed_values] ? obj[:allowed_values].flatten : [],
+          "default"        => obj[:default],
+          "docstring"      => Puppet::Util::Docs.scrub(obj[:desc] || ''),
+          "name"           => obj[:name],
+        }
+      end,
+      "features"         => @features.map do |obj|
+        {
+          "docstring" => Puppet::Util::Docs.scrub(obj[:desc] || ''),
+          "methods"   => obj[:methods],
+          "name"      => obj[:name],
+        }
+      end,
+    }.to_json(*a)
+  end
+
+end

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

@@ -0,0 +1,40 @@
+require 'yard'
+
+require 'puppet_x/puppetlabs/strings'
+
+# Patch the regular expression used to match namespaces
+# so it will allow namespace segments that begin with
+# both uppercase and lowercase letters (i.e. both
+# Puppet::Namespace and puppet::namespace)
+YARD::CodeObjects.send(:remove_const, :CONSTANTMATCH)
+YARD::CodeObjects::CONSTANTMATCH = /[a-zA-Z]\w*/
+
+# This is a temporary hack until a new version of YARD is
+# released. We submitted a patch to YARD to add the
+# CONSTANTSTART constant so that we could patch it and
+# successfully match our own namesapces. However until
+# the next version of the YARD gem is released, we must
+# patch the problematic method itself as it is not yet
+# using the added variable
+if defined? YARD::CodeObjects::CONSTANTSTART
+  YARD::CodeObjects.send(:remove_const, :CONSTANTSTART)
+  YARD::CodeObjects::CONSTANTSTART = /^[a-zA-Z]/
+else
+  class YARD::CodeObjects::Proxy
+    def proxy_path
+      if @namespace.root?
+        (@imethod ? YARD::CodeObjects::ISEP : "") + name.to_s
+      elsif @origname
+        if @origname =~ /^[a-zA-Z]/
+          @origname
+        else
+          [namespace.path, @origname].join
+        end
+      elsif name.to_s =~ /^[a-zA-Z]/ # const
+        name.to_s
+      else # class meth?
+        [namespace.path, name.to_s].join(YARD::CodeObjects::CSEP)
+      end
+    end
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/handlers/base.rb

@@ -0,0 +1,13 @@
+require 'puppet_x/puppetlabs/strings/yard/core_ext/yard'
+
+class PuppetX::PuppetLabs::Strings::YARD::Handlers::Base < ::YARD::Handlers::Base
+  # Easy access to Pops model objects for handler matching.
+  include Puppet::Pops::Model
+  # Easy access to custom code objects from which documentation is generated.
+  include PuppetX::PuppetLabs::Strings::YARD::CodeObjects
+
+  def self.handles?(statement)
+    handlers.any? {|h| h == statement.type}
+  end
+
+end

data/lib/puppet_x/puppetlabs/strings/yard/handlers/defined_type_handler.rb

@@ -0,0 +1,31 @@
+class PuppetX::PuppetLabs::Strings::YARD::Handlers::DefinedTypeHandler < PuppetX::PuppetLabs::Strings::YARD::Handlers:: Base
+  handles ResourceTypeDefinition
+
+  process do
+    obj = DefinedTypeObject.new(:root, statement.pops_obj.name) do |o|
+      o.parameters = statement.parameters.map do |a|
+        param_tuple = [a[0].pops_obj.name]
+        param_tuple << ( a[1].nil? ? nil : a[1].source )
+      end
+    end
+    tp = Puppet::Pops::Types::TypeParser.new
+    param_type_info = {}
+    statement.pops_obj.parameters.each do |pop_param|
+      # If the parameter's type expression is nil, default to Any
+      if pop_param.type_expr == nil
+        param_type_info[pop_param.name] = Puppet::Pops::Types::TypeFactory.any()
+      else
+        begin
+          param_type_info[pop_param.name] =  tp.interpret_any(pop_param.type_expr)
+        rescue Puppet::ParseError => e
+          # If the type could not be interpreted insert a prominent warning
+          param_type_info[pop_param.name] = "Type Error: #{e.message}"
+        end
+      end
+    end
+    obj.type_info = [param_type_info]
+
+
+    register obj
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/handlers/heredoc_helper.rb

@@ -0,0 +1,80 @@
+class HereDocHelper
+  # NOTE: The following methods duplicate functionality from
+  # Puppet::Util::Reference and Puppet::Parser::Functions.functiondocs
+  #
+  # However, implementing this natively in YARD is a good test for the
+  # feasibility of extracting custom Ruby documentation. In the end, the
+  # existing approach taken by Puppet::Util::Reference may be the best due to
+  # the heavy use of metaprogramming in Types and Providers.
+
+  # Extracts the Puppet function name and options hash from the parsed
+  # definition.
+  #
+  # @return [(String, Hash{String => String})]
+  def process_parameters(statement)
+    # Passing `false` to prameters excludes the block param from the returned
+    # list.
+    name, opts = statement.parameters(false).compact
+
+    name = process_element(name)
+
+    # Don't try to process options if we don't have any
+    if !opts.nil?
+      opts = opts.map do |tuple|
+        # Jump down into the S-Expression that represents a hashrocket, `=>`,
+        # and the values on either side of it.
+        tuple.jump(:assoc).map{|e| process_element(e)}
+      end
+
+      options = Hash[opts]
+    else
+      options = {}
+    end
+
+    [name, options]
+  end
+
+  # Sometimes the YARD parser returns Heredoc strings that start with `<-`
+  # instead of `<<-`.
+  HEREDOC_START = /^<?<-/
+
+  def is_heredoc?(str)
+    HEREDOC_START.match(str)
+  end
+
+    # Turns an entry in the method parameter list into a string.
+    #
+    # @param ele [YARD::Parser::Ruby::AstNode]
+    # @return [String]
+    def process_element(ele)
+      ele = ele.jump(:ident, :string_content)
+
+      case ele.type
+      when :ident
+        ele.source
+      when :string_content
+        source = ele.source
+        if is_heredoc? source
+          process_heredoc(source)
+        else
+          source
+        end
+      end
+    end
+
+  # Cleans up and formats Heredoc contents parsed by YARD.
+  #
+  # @param source [String]
+  # @return [String]
+  def process_heredoc(source)
+    source = source.lines.to_a
+
+    # YARD adds a line of source context on either side of the Heredoc
+    # contents.
+    source.shift
+    source.pop
+
+    # This utility method normalizes indentation and trims whitespace.
+    Puppet::Util::Docs.scrub(source.join)
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/handlers/host_class_handler.rb

@@ -0,0 +1,42 @@
+class PuppetX::PuppetLabs::Strings::YARD::Handlers::HostClassHandler < PuppetX::PuppetLabs::Strings::YARD::Handlers::Base
+  handles HostClassDefinition
+
+  process do
+    obj = HostClassObject.new(:root, statement.pops_obj.name)
+
+    obj.parameters = statement.parameters.map do |a|
+      param_tuple = [a[0].pops_obj.name]
+      param_tuple << ( a[1].nil? ? nil : a[1].source )
+    end
+    tp = Puppet::Pops::Types::TypeParser.new
+    param_type_info = {}
+    statement.pops_obj.parameters.each do |pop_param|
+      # If the parameter's type expression is nil, default to Any
+      if pop_param.type_expr == nil
+        param_type_info[pop_param.name] = Puppet::Pops::Types::TypeFactory.any()
+      else
+        begin
+          # This is a bit of a hack because we were using a method that was previously
+          # API private. See PDOC-75 for more details
+          if Puppet::Pops::Types::TypeParser.instance_method(:interpret_any).arity == 2
+            param_type_info[pop_param.name] = tp.interpret_any(pop_param.type_expr, nil)
+          else
+            param_type_info[pop_param.name] = tp.interpret_any(pop_param.type_expr)
+          end
+        rescue Puppet::ParseError => e
+          # If the type could not be interpreted insert a prominent warning
+          param_type_info[pop_param.name] = "Type Error: #{e.message}"
+        end
+      end
+    end
+    obj.type_info = [param_type_info]
+
+    statement.pops_obj.tap do |o|
+      if o.parent_class
+        obj.parent_class = P(:root, o.parent_class)
+      end
+    end
+
+    register obj
+  end
+end