puppet-strings 0.4.0 → 0.99.0

data/lib/puppet-strings/yard/code_objects/group.rb

@@ -0,0 +1,30 @@
+require 'puppet-strings/yard/code_objects/base'
+
+# Implements the base class for "groups".
+#
+# A group behaves like a YARD namespace object, but displays differently in the HTML output.
+class PuppetStrings::Yard::CodeObjects::Group < PuppetStrings::Yard::CodeObjects::Base
+  # Gets the singleton instance of the group.
+  # @param [Symbol] key The key to lookup the group for.
+  # @return Returns the singleton instance of the group.
+  def self.instance(key)
+    instance = P(:root, key)
+    return instance unless instance.is_a?(YARD::CodeObjects::Proxy)
+    instance = self.new(:root, key)
+    instance.visibility = :hidden
+    P(:root).children << instance
+    instance
+  end
+
+  # Gets the path to the group.
+  # @return [String] Returns the path to the group.
+  def path
+    @name.to_s
+  end
+
+  # Gets the type of the group.
+  # @return [Symbol] Returns the type of the group.
+  def type
+    @name
+  end
+end

data/lib/puppet-strings/yard/code_objects/provider.rb

@@ -0,0 +1,93 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet providers.
+class PuppetStrings::Yard::CodeObjects::Providers < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @param [String] type The resource type name for the provider.
+  # @return Returns the singleton instance of the group.
+  def self.instance(type)
+    super("puppet_providers_#{type}".intern)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Providers'
+  end
+end
+
+# Implements the Puppet provider code object.
+class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :type_name, :confines, :features, :defaults, :commands
+
+  # Initializes a Puppet provider code object.
+  # @param [String] type_name The resource type name for the provider.
+  # @param [String] name The name of the provider.s
+  # @return [void]
+  def initialize(type_name, name)
+    @type_name = type_name
+    super(PuppetStrings::Yard::CodeObjects::Providers.instance(type_name), name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_provider
+  end
+
+  # Adds a confine to the provider.
+  # @param [String] key The confine's key.
+  # @param [String] value The confine's value.
+  # @return [void]
+  def add_confine(key, value)
+    return unless key && value
+    @confines ||= {}
+    @confines[key] = value
+  end
+
+  # Adds a feature to the provider.
+  # @param [String] feature The feature to add to the provider.
+  # @return [void]
+  def add_feature(feature)
+    return unless feature
+    @features ||= []
+    @features << feature
+  end
+
+  # Adds a default to the provider.
+  # @param [String] key The default's key.
+  # @param [String] value The default's value.
+  # @return [void]
+  def add_default(key, value)
+    return unless key && value
+    @defaults ||= {}
+    @defaults[key] = value
+  end
+
+  # Adds a command to the provider.
+  # @param [String] key The command's key.
+  # @param [String] value The command's value.
+  # @return [void]
+  def add_command(key, value)
+    return unless key && value
+    @commands ||= {}
+    @commands[key] = value
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:type_name] = type_name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:confines] = confines if confines && !confines.empty?
+    hash[:features] = features if features && !features.empty?
+    hash[:defaults] = defaults if defaults && !defaults.empty?
+    hash[:commands] = commands if commands && !commands.empty?
+    hash
+  end
+end

data/lib/puppet-strings/yard/code_objects/type.rb

@@ -0,0 +1,146 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet resource types.
+class PuppetStrings::Yard::CodeObjects::Types < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_types)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Resource Types'
+  end
+end
+
+# Implements the Puppet resource type code object.
+class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects::Base
+  # Represents a resource type parameter.
+  class Parameter
+    attr_reader :name, :values, :aliases
+    attr_accessor :docstring, :isnamevar, :default
+
+    # Initializes a resource type parameter or property.
+    # @param [String] name The name of the parameter or property.
+    # @param [String] docstring The docstring for the parameter or property.s
+    def initialize(name, docstring = nil)
+      @name = name
+      @docstring = docstring || ''
+      @values = []
+      @aliases = {}
+      @isnamevar = false
+      @default = nil
+    end
+
+    # Adds a value to the parameter or property.
+    # @param [String] value The value to add.
+    # @return [void]
+    def add(value)
+      @values << value
+    end
+
+    # Aliases a value to another value.
+    # @param [String] new The new (alias) value.
+    # @param [String] old The old (existing) value.
+    # @return [void]
+    def alias(new, old)
+      @values << new unless @values.include? new
+      @aliases[new] = old
+    end
+
+    # Converts the parameter to a hash representation.
+    # @return [Hash] Returns a hash representation of the parameter.
+    def to_hash
+      hash = {}
+      hash[:name] = name
+      hash[:description] = docstring unless docstring.empty?
+      hash[:values] = values unless values.empty?
+      hash[:aliases] = aliases unless aliases.empty?
+      hash[:isnamevar] = true if isnamevar
+      hash[:default] = default if default
+      hash
+    end
+  end
+
+  # Represents a resource type property (same attributes as a parameter).
+  class Property < Parameter
+  end
+
+  # Represents a resource type feature.
+  class Feature
+    attr_reader :name, :docstring
+
+    # Initializes a new feature.
+    # @param [String] name The name of the feature.
+    # @param [String] docstring The docstring of the feature.
+    def initialize(name, docstring)
+      @name = name
+      @docstring = docstring
+    end
+
+    # Converts the feature to a hash representation.
+    # @return [Hash] Returns a hash representation of the feature.
+    def to_hash
+      hash = {}
+      hash[:name] = name
+      hash[:description] = docstring unless docstring.empty?
+      hash
+    end
+  end
+
+  attr_reader :properties, :parameters, :features
+
+  # Initializes a new resource type.
+  # @param [String] name The resource type name.
+  # @return [void]
+  def initialize(name)
+    super(PuppetStrings::Yard::CodeObjects::Types.instance, name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_type
+  end
+
+  # Adds a parameter to the resource type
+  # @param [PuppetStrings::Yard::CodeObjects::Type::Parameter] parameter The parameter to add.
+  # @return [void]
+  def add_parameter(parameter)
+    @parameters ||= []
+    @parameters << parameter
+  end
+
+  # Adds a property to the resource type
+  # @param [PuppetStrings::Yard::CodeObjects::Type::Property] property The property to add.
+  # @return [void]
+  def add_property(property)
+    @properties ||= []
+    @properties << property
+  end
+
+  # Adds a feature to the resource type.
+  # @param [PuppetStrings::Yard::CodeObjects::Type::Feature] feature The feature to add.
+  # @return [void]
+  def add_feature(feature)
+    @features ||= []
+    @features << feature
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:properties] = properties.map(&:to_hash) if properties && !properties.empty?
+    hash[:parameters] = parameters.map(&:to_hash) if parameters && !parameters.empty?
+    hash[:features] = features.map(&:to_hash) if features && !features.empty?
+    hash
+  end
+end

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

@@ -0,0 +1,16 @@
+# The module for custom YARD handlers.
+module PuppetStrings::Yard::Handlers
+  # The module for custom Ruby YARD handlers.
+  module Ruby
+    require 'puppet-strings/yard/handlers/ruby/type_handler'
+    require 'puppet-strings/yard/handlers/ruby/provider_handler'
+    require 'puppet-strings/yard/handlers/ruby/function_handler'
+  end
+
+  # The module for custom Puppet YARD handlers.
+  module Puppet
+    require 'puppet-strings/yard/handlers/puppet/class_handler'
+    require 'puppet-strings/yard/handlers/puppet/defined_type_handler'
+    require 'puppet-strings/yard/handlers/puppet/function_handler'
+  end
+end

data/lib/puppet-strings/yard/handlers/puppet/base.rb

@@ -0,0 +1,44 @@
+# Implements the base handler for Puppet language handlers.
+class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
+  # Determine sif the handler handles the given statement.
+  # @param statement The statement that was parsed.
+  # @return [Boolean] Returns true if the statement is handled by this handler or false if not.
+  def self.handles?(statement)
+    handlers.any? {|handler| statement.is_a?(handler)}
+  end
+
+  protected
+  # Sets the parameter tag types for the given code object.
+  # This also performs some validation on the parameter tags.
+  # @param object The code object to set the parameter tag types for.
+  # @return [void]
+  def set_parameter_types(object)
+    # Ensure there is an actual parameter for each parameter tag
+    tags = object.tags(:param)
+    tags.each do |tag|
+      next if statement.parameters.find { |p| tag.name == p.name }
+      log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{statement.file}:#{statement.line}."
+    end
+
+    # Assign the types for the parameter
+    statement.parameters.each do |parameter|
+      tag = tags.find { |t| t.name == parameter.name }
+      unless tag
+        log.warn "Missing @param tag for parameter '#{parameter.name}' near #{statement.file}:#{statement.line}." unless object.docstring.empty?
+
+        # Add a tag with an empty docstring
+        object.add_tag YARD::Tags::Tag.new(:param, '', [parameter.type || 'Any'], parameter.name)
+        next
+      end
+
+      # Warn if the parameter is typed and the tag also has a type
+      log.warn "The @param tag for parameter '#{parameter.name}' should not contain a type specification near #{statement.file}:#{statement.line}: ignoring in favor of parameter type information." if parameter.type && tag.types && !tag.types.empty?
+
+      if parameter.type
+        tag.types = [parameter.type]
+      elsif !tag.types
+        tag.types = ['Any']
+      end
+    end
+  end
+end

data/lib/puppet-strings/yard/handlers/puppet/class_handler.rb

@@ -0,0 +1,23 @@
+require 'puppet-strings/yard/handlers/puppet/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/code_objects'
+
+# Implements the handler for Puppet classes.
+class PuppetStrings::Yard::Handlers::Puppet::ClassHandler < PuppetStrings::Yard::Handlers::Puppet::Base
+  handles PuppetStrings::Yard::Parsers::Puppet::ClassStatement
+
+  process do
+    # Register the object
+    object = PuppetStrings::Yard::CodeObjects::Class.new(statement)
+    register object
+
+    # Log a warning if missing documentation
+    log.warn "Missing documentation for Puppet class '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+
+    # Set the parameter types
+    set_parameter_types(object)
+
+    # Mark the class as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+  end
+end

data/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb

@@ -0,0 +1,23 @@
+require 'puppet-strings/yard/handlers/puppet/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/code_objects'
+
+# Implements the handler for Puppet defined types.
+class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings::Yard::Handlers::Puppet::Base
+  handles PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement
+
+  process do
+    # Register the object
+    object = PuppetStrings::Yard::CodeObjects::DefinedType.new(statement)
+    register object
+
+    # Log a warning if missing documentation
+    log.warn "Missing documentation for Puppet defined type '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+
+    # Set the parameter types
+    set_parameter_types(object)
+
+    # Mark the defined type as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+  end
+end

data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb

@@ -0,0 +1,42 @@
+require 'puppet-strings/yard/handlers/puppet/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/code_objects'
+
+# Implements the handler for Puppet classes.
+class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Yard::Handlers::Puppet::Base
+  handles PuppetStrings::Yard::Parsers::Puppet::FunctionStatement
+
+  process do
+    # Register the object
+    object = PuppetStrings::Yard::CodeObjects::Function.new(statement.name, PuppetStrings::Yard::CodeObjects::Function::PUPPET)
+    object.source = statement.source
+    object.source_type = parser.parser_type
+    register object
+
+    # Log a warning if missing documentation
+    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+
+    # Set the parameter tag types
+    set_parameter_types(object)
+
+    # Add a return tag
+    add_return_tag(object)
+
+    # Set the parameters on the object
+    object.parameters = statement.parameters.map { |p| [p.name, p.value] }
+
+    # Mark the class as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+  end
+
+  private
+  def add_return_tag(object)
+    tag = object.tag(:return)
+    if tag
+      tag.types = ['Any'] unless tag.types
+      return
+    end
+    log.warn "Missing @return tag near #{statement.file}:#{statement.line}."
+    object.add_tag YARD::Tags::Tag.new(:return, '', 'Any')
+  end
+end

data/lib/puppet-strings/yard/handlers/ruby/base.rb

@@ -0,0 +1,38 @@
+require 'ripper'
+
+# Implements the base handler for Ruby language handlers.
+class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
+  # A regular expression for detecting the start of a Ruby heredoc.
+  # Note: the first character of the heredoc start may have been cut off by YARD.
+  HEREDOC_START = /^<?<[\-~]?['"]?(\w+)['"]?[^\n]*[\n]?/
+
+  protected
+  # Converts the given Ruby AST node to a string representation.
+  # @param node The Ruby AST node to convert.
+  # @return [String] Returns a string representation of the node or nil if a string representation was not possible.
+  def node_as_string(node)
+    return nil unless node
+    case node.type
+    when :symbol, :symbol_literal
+      node.source[1..-1]
+    when :label
+      node.source[0..-2]
+    when :dyna_symbol
+      node.source
+    when :string_literal
+      content = node.jump(:tstring_content)
+      return content.source if content != node
+
+      # This attempts to work around a bug in YARD (https://github.com/lsegal/yard/issues/779)
+      # Check to see if the string source appears to have a heredoc open tag (or "most" of one)
+      # If so, remove the first line and the last line (if the latter contains the heredoc tag)
+      source = node.source
+      if source =~ HEREDOC_START
+        lines = source.split("\n")
+        source = lines[1..(lines.last.include?($1) ? -2 : -1)].join("\n") if lines.size > 1
+      end
+
+      source
+    end
+  end
+end