kafo_parsers 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 050298bac1a3127c0f8a02392ae7789d601d2136
-  data.tar.gz: fc1fd7e4f29774e9882ffd4b67d9b08267cbff07
+  metadata.gz: 0a6477915864cbf2a6ec73458c997e3665cb70d6
+  data.tar.gz: 5556804196ff59db1f71c01f490544c90f6b92f5
 SHA512:
-  metadata.gz: 2e2ebe79c2084ba65c66ee986d03097121e5429142aefce6a41c04fe7c671bd4c0051526dc31256e2986f7cc493519661b6cd0fd43521ea077bf2053b612f5e9
-  data.tar.gz: 2abdd8b59c17f7bd10d1a93a4b223bde07aad6fcd8f4acde7d30ce42ee4f67b60497fe2ce569063e556775695f5dabfbd3f8e8a6f00c800c1ceefd16e84571da
+  metadata.gz: 1e1f5e24969c68aa7769e9969cd337d45292520780db95e97e4f11dd280bb1b6846d146829b1e0e51480fa103b9608241d2915466493a9e91ed0f971ab5e96e7
+  data.tar.gz: a447adc8b3af98f7fb4430b11ba659ddd6ba0518c139d652b27fe2e1a16f05dbe06f0ad0e0902dabae46653b84da25bf01b36887a0df26a7b6671e6b7227d616

data/README.md

@@ -72,6 +72,86 @@ hash = KafoParsers::PuppetStringsModuleParser.parse('/puppet/module/manifests/in
 Output will be similar to PuppetModuleParser, only validations are not supported,
 since they are not parsed by puppet-strings.
 
+## Documentation syntax
+
+### RDoc syntax
+
+Classes and defined types should be prefixed with a comment section with an RDoc
+block, containing a description, headings for different parameter groups and
+parameters laid out as shown below:
+
+```puppet
+# Example class that installs Example
+#
+# Supports version 1 to 3.
+#
+# === Parameters::
+#
+# $foo::  Sets the value of foo in the Example config
+#
+# === Advanced parameters::
+#
+# $bar::  Sets the value of bar in the advanced config
+```
+
+Parameters may have multi-line descriptions and can have extra attributes
+defined on new lines below them. Supports:
+
+```puppet
+# $foo::  Sets the value of foo in the Example config
+#         condition: $bar == 'use_foo'
+#         type: Optional[String]
+```
+
+Supports:
+
+* `condition:` an expression to determine if the parameter is used
+* `type:` the data type of the parameter
+
+Used by:
+
+* `PuppetModuleParser`
+* `PuppetStringsModuleParser` (but deprecated, prefer YARD)
+
+### YARD syntax
+
+Classes and defined types should be prefixed with a comment section in YARD
+following the Puppet Strings documentation standard, as shown below:
+
+```puppet
+# Example class that installs Example
+#
+# Supports version 1 to 3.
+#
+# @param foo Sets the value of foo in the Example config
+# @param bar Sets the value of bar in the advanced config
+#            group: Advanced parameters
+```
+
+Parameters may have multi-line descriptions and can have extra attributes
+defined on new lines below them. Supports:
+
+```puppet
+# @param foo Sets the value of foo in the Example config
+#            condition: $bar == 'use_foo'
+```
+
+Supports:
+
+* `condition:` an expression to determine if the parameter is used
+* `group:` comma-separated list of groups, increasing in specificity
+
+Data types are given in the parameter list of the class, or can be given inline
+for Puppet 3 compatibility:
+
+```puppet
+# @param foo [Integer] Sets the value of foo in the Example config
+```
+
+Used by:
+
+* `PuppetStringsModuleParser`
+
 # License
 
 This project is licensed under the GPLv3+.

data/lib/kafo_parsers/doc_parser.rb

@@ -3,6 +3,7 @@ require 'rdoc'
 require 'rdoc/markup' # required for RDoc < 0.9.5
 require 'rdoc/markup/parser' # required for RDoc < 0.9.5
 require 'kafo_parsers/exceptions'
+require 'kafo_parsers/param_doc_parser'
 
 module KafoParsers
   class DocParser
@@ -15,7 +16,7 @@ module KafoParsers
       @docs           = {}
       @groups         = {}
       @conditions     = {}
-      @types          = Hash.new('string')
+      @types          = {}
       @rdoc           = rdoc_parser.parse(@text)
     end
 
@@ -46,34 +47,17 @@ module KafoParsers
       return if label.nil?
       key              = label.gsub(/[^A-Za-z0-9_-]/, '')
       @groups[key]     = current_groups
-      text_parts       = para.parts.first.parts.map!(&:strip)
-      attributes, docs = text_parts.partition { |line| line =~ ATTRIBUTE_LINE }
-      parse_attributes(key, attributes)
-      @docs[key] = docs
-    end
+      text_parts       = para.parts.first.parts
 
-    def parse_attributes(parameter, attributes)
-      condition = nil
-      attributes.each do |attribute|
-        data        = attribute.match(ATTRIBUTE_LINE)
-        name, value = data[1], data[2]
-
-        case name
-          when 'type'
-            @types[parameter] = value
-          when 'condition'
-            if condition.nil?
-              condition = value
-            else
-              raise KafoParsers::DocParseError, "Two or more conditions defined for #{name}"
-            end
-          else
-            raise KafoParsers::DocParseError, "Unknown attribute #{name}"
-        end
+      param_parser = ParamDocParser.new(key, text_parts)
+      @docs[key] = param_parser.doc
+      parse_attributes(key, param_parser)
+    end
 
-      end
-      condition              = [current_condition, condition].compact.join(' && ')
+    def parse_attributes(parameter, parser)
+      condition              = [current_condition, parser.condition].compact.join(' && ')
       @conditions[parameter] = condition.empty? ? nil : condition
+      @types[parameter]      = parser.type unless parser.type.nil?
     end
 
     def parse_header(heading)

data/lib/kafo_parsers/param_doc_parser.rb

@@ -0,0 +1,42 @@
+require 'kafo_parsers/exceptions'
+
+module KafoParsers
+  class ParamDocParser
+    ATTRIBUTE_LINE   = /^(condition|group|type)\s*:\s*(.*)/
+
+    def initialize(param, text)
+      @param = param
+      @metadata = {}
+      parse_paragraph([text].flatten)
+    end
+
+    attr_reader :param, :doc
+    [:condition, :group, :type].each do |attr|
+      define_method(attr) do
+        @metadata[attr]
+      end
+    end
+
+    private
+
+    def parse_paragraph(text)
+      text_parts       = text.map(&:strip)
+      attributes, docs = text_parts.partition { |line| line =~ ATTRIBUTE_LINE }
+      parse_attributes(attributes)
+      @doc = docs
+    end
+
+    def parse_attributes(attributes)
+      attributes.each do |attribute|
+        data        = attribute.match(ATTRIBUTE_LINE)
+        name, value = data[1], data[2]
+        raise KafoParsers::DocParseError, "Two or more #{name} lines defined for #{param}" if @metadata.key?(name)
+        @metadata[name.to_sym] = value
+      end
+
+      if @metadata.key?(:group)
+        @metadata[:group] = @metadata[:group].split(/\s*,\s*/)
+      end
+    end
+  end
+end

data/lib/kafo_parsers/puppet_module_parser.rb

@@ -83,14 +83,14 @@ module KafoParsers
     def values
       parameters = {}
       arguments  = @object.respond_to?(:arguments) ? @object.arguments : {}
-      arguments.each { |k, v| parameters[k] = v.respond_to?(:value) ? v.value : nil }
+      arguments.each { |k, v| parameters[k] = interpret_ast([v])[0] }
       parameters
     end
 
     def validations(param = nil)
       return [] if @object.code.nil?
       @object.code.select { |stmt| stmt.is_a?(Puppet::Parser::AST::Function) && stmt.name =~ /^validate_/ }.map do |v|
-        Validation.new(v.name, interpret_validation_args(v.arguments))
+        Validation.new(v.name, interpret_ast(v.arguments))
       end
     end
 
@@ -110,7 +110,7 @@ module KafoParsers
         parser             = DocParser.new(@object.doc).parse
         data[:docs]        = parser.docs
         data[:groups]      = parser.groups
-        data[:types]       = parser.types
+        data[:types]       = Hash.new('string').merge(parser.types)
         data[:conditions]  = parser.conditions
         data[:object_type] = @object.type.to_s
       end
@@ -119,14 +119,14 @@ module KafoParsers
 
     private
 
-    def interpret_validation_args(args)
+    def interpret_ast(args)
       args.map do |arg|
         if arg.is_a?(Puppet::Parser::AST::Variable)
           arg.to_s
         elsif arg.is_a?(Puppet::Parser::AST::ASTArray)
-          interpret_validation_args(arg.to_a)
+          interpret_ast(arg.to_a)
         elsif arg.is_a?(Puppet::Parser::AST::Concat)
-          interpret_validation_args(arg.value).join
+          interpret_ast(arg.value).join
         elsif arg.respond_to? :value
           arg.value
         else

data/lib/kafo_parsers/puppet_strings_module_parser.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 require 'json'
 require 'kafo_parsers/doc_parser'
+require 'kafo_parsers/param_doc_parser'
 
 module KafoParsers
   class PuppetStringsModuleParser
@@ -91,7 +92,7 @@ module KafoParsers
 
     # returns data in following form
     # {
-    #   :docs => { $param1 => 'documentation without types and conditions'}
+    #   :docs => { $param1 => ['documentation without types and conditions']}
     #   :types => { $param1 => 'boolean'},
     #   :groups => { $param1 => ['Parameters', 'Advanced']},
     #   :conditions => { $param1 => '$db_type == "mysql"'},
@@ -101,11 +102,29 @@ module KafoParsers
       if @parsed_hash.nil?
         raise KafoParsers::DocParseError, "no documentation found for manifest #{@file}, parsing error?"
       elsif !@parsed_hash['docstring'].nil? && !@parsed_hash['docstring']['text'].nil?
-        parser             = DocParser.new(@parsed_hash['docstring']['text']).parse
-        data[:docs]        = parser.docs
-        data[:groups]      = parser.groups
-        data[:types]       = merge_doc_types(parser.types)
-        data[:conditions]  = parser.conditions
+        # Lowest precedence: types given in the strings hash from class definition
+        tag_params.each do |param|
+          data[:types][param['name']] = param['types'][0] unless param['types'].nil?
+        end
+
+        # Next: types and other data from RDoc parser
+        rdoc_parser = DocParser.new(@parsed_hash['docstring']['text']).parse
+        data[:docs] = rdoc_parser.docs
+        data[:groups] = rdoc_parser.groups
+        data[:conditions] = rdoc_parser.conditions
+        data[:types].merge! rdoc_parser.types
+
+        # Highest precedence: data in YARD @param stored in the 'text' field
+        tag_params.each do |param|
+          param_name = param['name']
+          unless param['text'].nil? || param['text'].empty?
+            param_parser = ParamDocParser.new(param_name, param['text'].split($/))
+            data[:docs][param_name] = param_parser.doc if param_parser.doc
+            data[:groups][param_name] = param_parser.group if param_parser.group
+            data[:conditions][param_name] = param_parser.condition if param_parser.condition
+            data[:types][param_name] = param_parser.type if param_parser.type
+          end
+        end
       end
       data
     end
@@ -113,7 +132,6 @@ module KafoParsers
     private
 
     # default values using puppet strings includes $ symbol, e.g. "$::foreman::params::ssl"
-    # to keep the same API we strip $ if it's present
     #
     # values are reported as strings which is issue especially for :under
     # strings are double quoted
@@ -122,16 +140,11 @@ module KafoParsers
       if (value.start_with?("'") && value.end_with?("'")) || (value.start_with?('"') && value.end_with?('"'))
         value = value[1..-2]
       end
-      value = value[1..-1] if value.start_with?('$')
       value = :undef if value == 'undef'
 
       value
     end
 
-    def merge_doc_types(types)
-      Hash[tag_params.select { |param| !param['types'].nil? }.map { |param| [ param['name'], param['types'].first ] }].merge(types)
-    end
-
     def tag_params
       if @parsed_hash['docstring']['tags']
         @parsed_hash['docstring']['tags'].select { |tag| tag['tag_name'] == 'param' }

data/lib/kafo_parsers/version.rb

@@ -1,3 +1,3 @@
 module KafoParsers
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kafo_parsers
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Marek Hulan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-23 00:00:00.000000000 Z
+date: 2017-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,7 @@ files:
 - lib/kafo_parsers.rb
 - lib/kafo_parsers/doc_parser.rb
 - lib/kafo_parsers/exceptions.rb
+- lib/kafo_parsers/param_doc_parser.rb
 - lib/kafo_parsers/parsers.rb
 - lib/kafo_parsers/puppet_module_parser.rb
 - lib/kafo_parsers/puppet_strings_module_parser.rb