puppet-strings 2.1.0 → 2.2.0

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

@@ -22,7 +22,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   # Represents a resource type parameter.
   class Parameter
     attr_reader :name, :values, :aliases
-    attr_accessor :docstring, :isnamevar, :default, :data_type
+    attr_accessor :docstring, :isnamevar, :default, :data_type, :required_features
 
     # Initializes a resource type parameter or property.
     # @param [String] name The name of the parameter or property.
@@ -63,6 +63,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
       hash[:data_type] = data_type unless data_type.empty?
       hash[:aliases] = aliases unless aliases.empty?
       hash[:isnamevar] = true if isnamevar
+      hash[:required_features] = required_features if required_features
       hash[:default] = default if default
       hash
     end
@@ -140,7 +141,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.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?

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

@@ -3,6 +3,7 @@ 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/type_extras_handler'
     require 'puppet-strings/yard/handlers/ruby/rsapi_handler'
     require 'puppet-strings/yard/handlers/ruby/provider_handler'
     require 'puppet-strings/yard/handlers/ruby/function_handler'

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

@@ -33,6 +33,17 @@ class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
       end
 
       source
+    when :regexp_literal
+      node.source
     end
   end
+
+  def get_name(statementobject, statementtype)
+    parameters = statementobject.parameters(false)
+    raise YARD::Parser::UndocumentableError, "Expected at least one parameter to #{statementtype} at #{statementobject.file}:#{statementobject.line}." if parameters.empty?
+    name = node_as_string(parameters.first)
+    raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name
+    name
+  end
+
 end

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

@@ -35,7 +35,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
     # Create and register the function object
     is_3x = module_name == 'Puppet::Parser::Functions' || module_name == 'newfunction'
     object = PuppetStrings::Yard::CodeObjects::Function.new(
-      get_name,
+      get_name(statement, 'Puppet::Functions.create_function'),
       is_3x ? PuppetStrings::Yard::CodeObjects::Function::RUBY_3X : PuppetStrings::Yard::CodeObjects::Function::RUBY_4X
     )
     object.source = statement
@@ -68,14 +68,6 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
   end
 
   private
-  def get_name
-    parameters = statement.parameters(false)
-    raise YARD::Parser::UndocumentableError, "Expected at least one parameter to Puppet::Functions.create_function at #{statement.file}:#{statement.line}." if parameters.empty?
-    name = node_as_string(parameters.first)
-    raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name
-    name
-  end
-
   def add_tags(object)
     log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
     log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @param tags near #{object.file}:#{object.line}: parameter documentation should be made on the dispatch call." unless object.tags(:param).empty?

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

@@ -24,7 +24,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
     raise YARD::Parser::UndocumentableError, "Could not determine the resource type name for the provider defined at #{statement.file}:#{statement.line}." unless type_name
 
     # Register the object
-    object = PuppetStrings::Yard::CodeObjects::Provider.new(type_name, get_name)
+    object = PuppetStrings::Yard::CodeObjects::Provider.new(type_name, get_name(statement, "'provide'"))
     register object
 
     # Extract the docstring
@@ -41,14 +41,6 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
   end
 
   private
-  def get_name
-    parameters = statement.parameters(false)
-    raise YARD::Parser::UndocumentableError, "Expected at least one parameter to 'provide' at #{statement.file}:#{statement.line}." if parameters.empty?
-    name = node_as_string(parameters.first)
-    raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name
-    name
-  end
-
   def register_provider_docstring(object)
     # Walk the tree searching for assignments or calls to desc/doc=
     statement.traverse do |child|

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

@@ -71,7 +71,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
       array_from_node(node)
     when :var_ref
       var_ref_from_node(node)
-    when :symbol, :symbol_literal, :label, :dyna_symbol, :string_literal
+    when :symbol, :symbol_literal, :label, :dyna_symbol, :string_literal, :regexp_literal
       node_as_string(node)
     else
       raise_parse_error("unexpected construct #{node.type}")

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

@@ -0,0 +1,130 @@
+require 'puppet-strings/yard/handlers/ruby/base'
+
+class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handlers::Ruby::Base
+  protected
+  def get_type_yard_object(name)
+    #Have to guess the path - if we create the object to get the true path from the code,
+    #it also shows up in the .at call - self registering?
+    guess_path = "puppet_types::#{name}"
+    object = YARD::Registry.at(guess_path)
+
+    return object unless object.nil?
+
+    #Didn't find, create instead
+    object = PuppetStrings::Yard::CodeObjects::Type.new(name)
+    register object
+    object
+  end
+    
+  def find_docstring(node, kind)
+    # Walk the tree searching for assignments or calls to desc/doc=
+    node.traverse do |child|
+      if child.type == :assign
+        ivar = child.jump(:ivar)
+        next unless ivar != child && ivar.source == '@doc'
+        docstring = node_as_string(child[1])
+        log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
+        return PuppetStrings::Yard::Util.scrub_string(docstring)
+      elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
+        # Look for a call to a dispatch method with a block
+        next unless child.method_name &&
+                (child.method_name.source == 'desc' || child.method_name.source == 'doc=') &&
+                child.parameters(false).count == 1
+
+        docstring = node_as_string(child.parameters[0])
+        log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
+        return PuppetStrings::Yard::Util.scrub_string(docstring)
+      end
+    end
+    log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}."
+    nil
+  end
+
+  def create_parameter(name, node)
+    parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(name, find_docstring(node, "Puppet resource parameter '#{name}'"))
+    set_values(node, parameter)
+    parameter
+  end
+
+  def create_property(name, node)
+    property = PuppetStrings::Yard::CodeObjects::Type::Property.new(name, find_docstring(node, "Puppet resource property '#{name}'"))
+    set_values(node, property)
+    property
+  end
+
+  def set_values(node, object)
+    return unless node.block && node.block.count >= 2
+
+    node.block[1].children.each do |child|
+      next unless child.is_a?(YARD::Parser::Ruby::MethodCallNode) && child.method_name
+
+      method_name = child.method_name.source
+      parameters = child.parameters(false)
+
+      if method_name == 'newvalue'
+        next unless parameters.count >= 1
+        object.add(node_as_string(parameters[0]) || parameters[0].source)
+      elsif method_name == 'newvalues'
+        parameters.each do |p|
+          object.add(node_as_string(p) || p.source)
+        end
+      elsif method_name == 'aliasvalue'
+        next unless parameters.count >= 2
+        object.alias(node_as_string(parameters[0]) || parameters[0].source, node_as_string(parameters[1]) || parameters[1].source)
+      elsif method_name == 'defaultto'
+        next unless parameters.count >= 1
+        object.default = node_as_string(parameters[0]) || parameters[0].source
+      elsif method_name == 'isnamevar'
+        object.isnamevar = true
+      elsif method_name == 'defaultvalues' && object.name == 'ensure'
+        object.add('present')
+        object.add('absent')
+        object.default = 'present'
+      end
+    end
+
+    parameters = node.parameters(false)
+
+    if parameters.count >= 2
+      kvps = parameters[1].find_all { |kvp| kvp.count == 2 }
+      required_features_kvp = kvps.find { |kvp| node_as_string(kvp[0]) == 'required_features' }
+      object.required_features = node_as_string(required_features_kvp[1]) unless required_features_kvp.nil?
+    end
+
+    if object.is_a? PuppetStrings::Yard::CodeObjects::Type::Parameter
+      # Process the options for parameter base types
+      if parameters.count >= 2
+        parameters[1].each do |kvp|
+          next unless kvp.count == 2
+          next unless node_as_string(kvp[0]) == 'parent'
+          if kvp[1].source == 'Puppet::Parameter::Boolean'
+            object.add('true') unless object.values.include? 'true'
+            object.add('false') unless object.values.include? 'false'
+            object.add('yes') unless object.values.include? 'yes'
+            object.add('no') unless object.values.include? 'no'
+          end
+          break
+        end
+      end
+    end
+  end
+
+  def set_default_namevar(object)
+    return unless object.properties || object.parameters
+    default = nil
+    if object.properties
+      object.properties.each do |property|
+        return nil if property.isnamevar
+        default = property if property.name == 'name'
+      end
+    end
+    if object.parameters
+      object.parameters.each do |parameter|
+        return nil if parameter.isnamevar
+        default ||= parameter if parameter.name == 'name'
+      end
+    end
+    default.isnamevar = true if default
+  end
+end
+      

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

@@ -0,0 +1,56 @@
+require 'puppet-strings/yard/handlers/helpers'
+require 'puppet-strings/yard/handlers/ruby/type_base'
+require 'puppet-strings/yard/code_objects'
+require 'puppet-strings/yard/util'
+
+# Implements the handler for Puppet resource type newparam/newproperty calls written in Ruby.
+class PuppetStrings::Yard::Handlers::Ruby::TypeExtrasHandler < PuppetStrings::Yard::Handlers::Ruby::TypeBase
+  # The default docstring when ensurable is used without given a docstring.
+  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze
+
+  namespace_only
+  handles method_call(:newparam)
+  handles method_call(:newproperty)
+
+  process do
+
+    # Our entry point is a type newproperty/newparam compound statement like this:
+    #  "Puppet::Type.type(:file).newparam(:content) do"
+    # We want to
+    #  Verify the structure
+    #  Capture the three parameters (e.g. type: 'file', newproperty or newparam?, name: 'source')
+    #  Proceed with collecting data
+    #  Either decorate an existing type object or store for future type object parsing
+
+    # Only accept calls to Puppet::Type.type(<type>).newparam/.newproperty
+    # e.g. "Puppet::Type.type(:file).newparam(:content) do" would yield:
+    #   module_name:  "Puppet::Type"
+    #   method1_name: "type"
+    #   typename:     "file"
+    #   method2_name: "newparam"
+    #   propertyname: "content"
+
+    return unless (statement.count > 1) && (statement[0].children.count > 2)
+    module_name = statement[0].children[0].source
+    method1_name = statement[0].children[1].source
+    return unless (module_name == 'Puppet::Type' || module_name == 'Type') && method1_name == 'type'
+
+    typename = get_name(statement[0], 'Puppet::Type.type')
+    method2_name = caller_method
+    propertyname = get_name(statement, "Puppet::Type.type().#{method2_name}")
+
+    typeobject = get_type_yard_object(typename)
+
+    # node - what should it be here?
+    node = statement #?? not sure... test...
+
+    if method2_name == 'newproperty'
+      typeobject.add_property(create_property(propertyname, node))
+    elsif method2_name == 'newparam'
+      typeobject.add_parameter(create_parameter(propertyname, node))
+    end
+
+    # Set the default namevar
+    set_default_namevar(typeobject)
+  end
+end

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

@@ -1,10 +1,10 @@
 require 'puppet-strings/yard/handlers/helpers'
-require 'puppet-strings/yard/handlers/ruby/base'
+require 'puppet-strings/yard/handlers/ruby/type_base'
 require 'puppet-strings/yard/code_objects'
 require 'puppet-strings/yard/util'
 
 # Implements the handler for Puppet resource types written in Ruby.
-class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Handlers::Ruby::Base
+class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Handlers::Ruby::TypeBase
   # The default docstring when ensurable is used without given a docstring.
   DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze
 
@@ -17,8 +17,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
     module_name = statement[0].source
     return unless module_name == 'Puppet::Type' || module_name == 'Type'
 
-    object = PuppetStrings::Yard::CodeObjects::Type.new(get_name)
-    register object
+    object = get_type_yard_object(get_name(statement, 'Puppet::Type.newtype'))
 
     docstring = find_docstring(statement, "Puppet resource type '#{object.name}'")
     register_docstring(object, docstring, nil) if docstring
@@ -37,38 +36,6 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
   end
 
   private
-  def get_name
-    parameters = statement.parameters(false)
-    raise YARD::Parser::UndocumentableError, "Expected at least one parameter to Puppet::Type.newtype at #{statement.file}:#{statement.line}." if parameters.empty?
-    name = node_as_string(parameters.first)
-    raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name
-    name
-  end
-
-  def find_docstring(node, kind)
-    # Walk the tree searching for assignments or calls to desc/doc=
-    node.traverse do |child|
-      if child.type == :assign
-        ivar = child.jump(:ivar)
-        next unless ivar != child && ivar.source == '@doc'
-        docstring = node_as_string(child[1])
-        log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
-        return PuppetStrings::Yard::Util.scrub_string(docstring)
-      elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
-        # Look for a call to a dispatch method with a block
-        next unless child.method_name &&
-                    (child.method_name.source == 'desc' || child.method_name.source == 'doc=') &&
-                    child.parameters(false).count == 1
-
-        docstring = node_as_string(child.parameters[0])
-        log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
-        return PuppetStrings::Yard::Util.scrub_string(docstring)
-      end
-    end
-    log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}."
-    nil
-  end
-
   def populate_type_data(object)
     # Traverse the block looking for properties/parameters/features
     block = statement.block
@@ -116,83 +83,4 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
       end
     end
   end
-
-  def create_parameter(name, node)
-    parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(name, find_docstring(node, "Puppet resource parameter '#{name}'"))
-    set_values(node, parameter)
-    parameter
-  end
-
-  def create_property(name, node)
-    property = PuppetStrings::Yard::CodeObjects::Type::Property.new(name, find_docstring(node, "Puppet resource property '#{name}'"))
-    set_values(node, property)
-    property
-  end
-
-  def set_values(node, object)
-    return unless node.block && node.block.count >= 2
-
-    node.block[1].children.each do |child|
-      next unless child.is_a?(YARD::Parser::Ruby::MethodCallNode) && child.method_name
-
-      method_name = child.method_name.source
-      parameters = child.parameters(false)
-
-      if method_name == 'newvalue'
-        next unless parameters.count >= 1
-        object.add(node_as_string(parameters[0]) || parameters[0].source)
-      elsif method_name == 'newvalues'
-        parameters.each do |p|
-          object.add(node_as_string(p) || p.source)
-        end
-      elsif method_name == 'aliasvalue'
-        next unless parameters.count >= 2
-        object.alias(node_as_string(parameters[0]) || parameters[0].source, node_as_string(parameters[1]) || parameters[1].source)
-      elsif method_name == 'defaultto'
-        next unless parameters.count >= 1
-        object.default = node_as_string(parameters[0]) || parameters[0].source
-      elsif method_name == 'isnamevar'
-        object.isnamevar = true
-      elsif method_name == 'defaultvalues' && object.name == 'ensure'
-        object.add('present')
-        object.add('absent')
-        object.default = 'present'
-      end
-    end
-    if object.is_a? PuppetStrings::Yard::CodeObjects::Type::Parameter
-      # Process the options for parameter base types
-      parameters = node.parameters(false)
-      if parameters.count >= 2
-        parameters[1].each do |kvp|
-          next unless kvp.count == 2
-          next unless node_as_string(kvp[0]) == 'parent'
-          if kvp[1].source == 'Puppet::Parameter::Boolean'
-            object.add('true') unless object.values.include? 'true'
-            object.add('false') unless object.values.include? 'false'
-            object.add('yes') unless object.values.include? 'yes'
-            object.add('no') unless object.values.include? 'no'
-          end
-          break
-        end
-      end
-    end
-  end
-
-  def set_default_namevar(object)
-    return unless object.properties || object.parameters
-    default = nil
-    if object.properties
-      object.properties.each do |property|
-        return nil if property.isnamevar
-        default = property if property.name == 'name'
-      end
-    end
-    if object.parameters
-      object.parameters.each do |parameter|
-        return nil if parameter.isnamevar
-        default ||= parameter if parameter.name == 'name'
-      end
-    end
-    default.isnamevar = true if default
-  end
 end

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

@@ -22,7 +22,9 @@ class PuppetStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base
   def parse
     begin
       json = JSON.parse(source)
-      @statements.push(PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file))
+      # TODO: this should compare json to a Task metadata json-schema or perform some other hueristics
+      # to determine what type of statement it represents
+      @statements.push(PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file)) unless json.empty?
     rescue
       log.error "Failed to parse #{@file}: "
       @statements = []