puppet-strings 0.4.0 → 0.99.0

data/lib/puppet_x/puppetlabs/strings/pops/yard_transformer.rb

@@ -1,47 +0,0 @@
-# Loosely based on the TreeDumper classes in Pops::Model. The responsibility of
-# this class is to walk a Pops::Model and output objects that can be consumed
-# by YARD handlers.
-#
-# @note Currently, this class only extracts node, host class and type
-#   definitions.
-class PuppetX::PuppetLabs::Strings::Pops::YARDTransformer
-  def initialize
-    @transform_visitor = Puppet::Pops::Visitor.new(self, 'transform')
-  end
-
-  def transform(o)
-    @transform_visitor.visit(o)
-  end
-
-  private
-
-  def transform_Factory(o)
-    transform(o.current)
-  end
-
-  def transform_Program(o)
-    o.definitions.map{|d| transform(d)}
-  end
-
-  # Extract comments from type definitions and class definitions. Wrap them
-  # into YARDStatement objects that provide an interface for YARD handlers.
-  def transform_NamedDefinition(o)
-    obj = PuppetX::PuppetLabs::Strings::Pops::YARDStatement.new(o)
-    obj.parameters = o.parameters.map do |p|
-      param_tuple = [transform(p)]
-      param_tuple << ( p.value.nil? ? nil : transform(p.value) )
-    end
-
-    obj
-  end
-
-  # Catch-all visitor.
-  def transform_Positioned(o)
-    PuppetX::PuppetLabs::Strings::Pops::YARDStatement.new(o)
-  end
-
-  # nil in... nil out!
-  def transform_NilClass(o)
-    nil
-  end
-end

data/lib/puppet_x/puppetlabs/strings/util.rb

@@ -1,65 +0,0 @@
-require 'puppet_x/puppetlabs/strings/actions'
-
-module PuppetX::PuppetLabs::Strings::Util
-  MODULE_SOURCEFILES = ['manifests/**/*.pp', 'lib/**/*.rb']
-
-  def self.generate(args = [])
-    yardoc_actions = PuppetX::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace])
-
-    # The last element of the argument array should be the options hash.
-    # We don't have any options yet, so for now just pop the hash off and
-    # toss it.
-    #
-    # NOTE: The Puppet Face will throw 'unrecognized option' errors if any
-    # YARD options are passed to it. The best way to approach this problem is
-    # by using the `.yardopts` file. YARD will autoload any options placed in
-    # that file.
-    options = args.pop
-    YARD::Config.options = YARD::Config.options.merge(options) if options
-
-    # For now, assume the remaining positional args are a list of manifest
-    # and ruby files to parse.
-    yard_args = (args.empty? ? MODULE_SOURCEFILES : args)
-
-    # If json is going to be emitted to stdout, suppress statistics.
-    if options && options[:emit_json_stdout]
-      yard_args.push('--no-stats')
-    end
-
-    # This line monkeypatches yard's progress indicator so it doesn't write
-    # all over the terminal. This should definitely not be in real code, but
-    # it's very handy for debugging with pry
-    #class YARD::Logger; def progress(*args); end; end
-    YARD::Tags::Library.define_directive("puppet.type.param",
-      :with_types_and_name,
-      PuppetX::PuppetLabs::Strings::YARD::Tags::PuppetTypeParameterDirective)
-
-    yardoc_actions.generate_documentation(*yard_args)
-  end
-
-  def self.serve(args = [])
-    server_actions = PuppetX::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace])
-
-    args.pop
-
-    module_names = args
-
-    # FIXME: This is pretty inefficient as it forcibly re-generates the YARD
-    # indicies each time the server is started. However, it ensures things are
-    # generated properly.
-    module_list = server_actions.index_documentation_for_modules(module_names, MODULE_SOURCEFILES)
-
-    module_tuples = server_actions.generate_module_tuples(module_list)
-
-    module_tuples.map! do |mod|
-      [mod[:name], mod[:index_path]]
-    end
-
-    # The `-m` flag means a list of name/path pairs will follow. The name is
-    # used as the module name and the path indicates which `.yardoc` index to
-    # generate documentation from.
-    yard_args = %w[-m -q] + module_tuples.flatten
-
-    server_actions.serve_documentation(*yard_args)
-  end
-end

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

@@ -1,33 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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