puppet-strings 2.1.0 → 2.2.0

data/lib/puppet-strings/yard/tags/overload_tag.rb

@@ -99,7 +99,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
     hash[:tag_name] = tag_name
     hash[:text] = text if text
     hash[:signature] = signature
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) if !docstring.blank?
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring) if !docstring.blank?
     defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:types] = types if types

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

@@ -28,4 +28,52 @@ module PuppetStrings::Yard::Util
     end
     data
   end
+
+  # Converts a list of tags into an array of hashes.
+  # @param [Array] tags List of tags to be converted into an array of hashes.
+  # @return [Array] Returns an array of tag hashes.
+  def self.tags_to_hashes(tags)
+    # Skip over the API tags that are public
+    tags.select { |t| (t.tag_name != 'api' || t.text != 'public') }.map do |t|
+      next t.to_hash if t.respond_to?(:to_hash)
+
+      tag = { tag_name: t.tag_name }
+      # grab nested information for @option tags
+      if tag[:tag_name] == 'option'
+        tag[:opt_name] = t.pair.name
+        tag[:opt_text] = t.pair.text
+        tag[:opt_types] = t.pair.types
+        tag[:parent] = t.name
+      end
+      tag[:text] = t.text if t.text
+      tag[:types] = t.types if t.types
+      tag[:name] = t.name if t.name
+      tag
+    end
+  end
+
+  # Converts a YARD::Docstring (or String) to a docstring hash for JSON output.
+  # @param [YARD::Docstring, String] docstring The docstring to convert to a hash.
+  # @param [Array] select_tags List of tags to select. Other tags will be filtered out.
+  # @return [Hash] Returns a hash representation of the given docstring.
+  def self.docstring_to_hash(docstring, select_tags=nil)
+    hash = {}
+    hash[:text] = docstring
+
+    if docstring.is_a? YARD::Docstring
+      tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })
+
+      unless tags.empty?
+        hash[:tags] = tags
+        #   .sort_by do |tag|
+        #   sort_key = tag[:tag_name].dup
+        #   sort_key << "-#{tag[:name]}" if tag[:name]
+        #   sort_key << "-#{tag[:opt_name]}" if tag[:opt_name]
+        #   sort_key
+        # end
+      end
+    end
+
+    hash
+  end
 end

data/lib/puppet/face/strings.rb

@@ -81,6 +81,65 @@ Puppet::Face.define(:strings, '0.0.1') do
     end
   end
 
+  action(:describe) do #This is Kris' experiment with string based describe
+    option "--list" do
+      summary "list types"
+    end
+    option "--providers" do
+      summary "provide details on providers"
+    end
+
+#TODO: Implement the rest of describe behavior
+#     * --help:
+#   Print this help text
+
+# * --providers:
+#   Describe providers in detail for each type
+
+# * --list:
+#   List all types
+
+# * --meta:
+#   List all metaparameters
+
+# * --short:
+#   List only parameters without detail
+
+
+    when_invoked do |*args|
+      check_required_features
+      require 'puppet-strings'
+
+      options = args.last
+      options[:describe] = true
+      options[:stdout] = true
+      options[:format] = 'json'
+      
+      if args.length > 1
+        if options[:list]
+          $stderr.puts "WARNING: ignoring types when listing all types."
+        else
+          options[:describe_types] = args[0..-2]
+        end
+      end
+
+      #TODO: Set up search_patterns and whatever else needed to collect data for describe - currently missing some
+      #          manifests/**/*.pp
+      #          functions/**/*.pp
+      #          tasks/*.json
+      #          plans/*.pp
+      search_patterns = %w(
+        types/**/*.pp
+        lib/**/*.rb
+      )
+      PuppetStrings::generate(
+        search_patterns,
+        build_generate_options(options)
+      )
+      nil
+    end
+  end
+
   # Checks that the required features are installed.
   # @return [void]
   def check_required_features
@@ -98,7 +157,6 @@ Puppet::Face.define(:strings, '0.0.1') do
     generate_options[:debug] = Puppet[:debug]
     generate_options[:backtrace] = Puppet[:trace]
     generate_options[:yard_args] = yard_args unless yard_args.empty?
-
     if options
       if options[:emit_json]
         $stderr.puts "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead."
@@ -110,6 +168,13 @@ Puppet::Face.define(:strings, '0.0.1') do
       generate_options[:markup] = markup if markup
       generate_options[:path] = options[:out] if options[:out]
       generate_options[:stdout] = options[:stdout]
+
+      if options[:describe]
+        generate_options[:describe] = true
+        generate_options[:describe_types] = options[:describe_types]
+        generate_options[:describe_list] = options[:list]
+      end
+
       format = options[:format]
       if format
         if format.casecmp('markdown').zero?

data/spec/fixtures/unit/markdown/output.md

@@ -266,6 +266,8 @@ The database server name.
 
 The encryption key to use.
 
+Required features: encryption.
+
 ##### `encrypt`
 
 Valid values: `true`, `false`, yes, no
@@ -282,6 +284,14 @@ Type: Puppet Language
 
 A simple Puppet function.
 
+#### Examples
+
+##### Test
+
+```puppet
+$result = func(1, 2)
+```
+
 #### `func(Integer $param1, Any $param2, String $param3 = hi)`
 
 A simple Puppet function.
@@ -291,6 +301,14 @@ Returns: `Undef` Returns nothing.
 Raises:
 * `SomeError` this is some error
 
+##### Examples
+
+###### Test
+
+```puppet
+$result = func(1, 2)
+```
+
 ##### `param1`
 
 Data type: `Integer`
@@ -319,12 +337,28 @@ Type: Ruby 3.x API
 
 Documentation for an example 3.x function.
 
+#### Examples
+
+##### Calling the function.
+
+```puppet
+func3x('hi', 10)
+```
+
 #### `func3x(String $param1, Integer $param2)`
 
 Documentation for an example 3.x function.
 
 Returns: `Undef`
 
+##### Examples
+
+###### Calling the function.
+
+```puppet
+func3x('hi', 10)
+```
+
 ##### `param1`
 
 Data type: `String`
@@ -343,12 +377,34 @@ Type: Ruby 4.x API
 
 An example 4.x function.
 
+#### Examples
+
+##### Calling the function
+
+```puppet
+$result = func4x(1, 'foo')
+```
+
+##### Calling the function with all args
+
+```puppet
+$result = func4x(1, 'foo', ['bar'])
+```
+
 #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
 
 An overview for the first overload.
 
 Returns: `Undef` Returns nothing.
 
+##### Examples
+
+###### Calling the function foo
+
+```puppet
+$result = func4x(1, 'foooo')
+```
+
 ##### `param1`
 
 Data type: `Integer`
@@ -378,6 +434,14 @@ An overview for the second overload.
 
 Returns: `String` Returns a string.
 
+##### Examples
+
+###### Calling the function bar
+
+```puppet
+$result = func4x(1, 'bar', ['foo'])
+```
+
 ##### `param`
 
 Data type: `Boolean`

data/spec/fixtures/unit/markdown/output_with_plan.md

@@ -270,6 +270,8 @@ The database server name.
 
 The encryption key to use.
 
+Required features: encryption.
+
 ##### `encrypt`
 
 Valid values: `true`, `false`, yes, no
@@ -286,6 +288,14 @@ Type: Puppet Language
 
 A simple Puppet function.
 
+#### Examples
+
+##### Test
+
+```puppet
+$result = func(1, 2)
+```
+
 #### `func(Integer $param1, Any $param2, String $param3 = hi)`
 
 A simple Puppet function.
@@ -295,6 +305,14 @@ Returns: `Undef` Returns nothing.
 Raises:
 * `SomeError` this is some error
 
+##### Examples
+
+###### Test
+
+```puppet
+$result = func(1, 2)
+```
+
 ##### `param1`
 
 Data type: `Integer`
@@ -323,12 +341,28 @@ Type: Ruby 3.x API
 
 Documentation for an example 3.x function.
 
+#### Examples
+
+##### Calling the function.
+
+```puppet
+func3x('hi', 10)
+```
+
 #### `func3x(String $param1, Integer $param2)`
 
 Documentation for an example 3.x function.
 
 Returns: `Undef`
 
+##### Examples
+
+###### Calling the function.
+
+```puppet
+func3x('hi', 10)
+```
+
 ##### `param1`
 
 Data type: `String`
@@ -347,12 +381,34 @@ Type: Ruby 4.x API
 
 An example 4.x function.
 
+#### Examples
+
+##### Calling the function
+
+```puppet
+$result = func4x(1, 'foo')
+```
+
+##### Calling the function with all args
+
+```puppet
+$result = func4x(1, 'foo', ['bar'])
+```
+
 #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
 
 An overview for the first overload.
 
 Returns: `Undef` Returns nothing.
 
+##### Examples
+
+###### Calling the function foo
+
+```puppet
+$result = func4x(1, 'foooo')
+```
+
 ##### `param1`
 
 Data type: `Integer`
@@ -382,6 +438,14 @@ An overview for the second overload.
 
 Returns: `String` Returns a string.
 
+##### Examples
+
+###### Calling the function bar
+
+```puppet
+$result = func4x(1, 'bar', ['foo'])
+```
+
 ##### `param`
 
 Data type: `Boolean`

data/spec/spec_helper.rb

@@ -17,6 +17,7 @@ end
 
 require 'mocha'
 require 'rspec'
+require 'json_spec'
 require 'puppet/version'
 require 'puppet-strings'
 require 'puppet-strings/markdown'

data/spec/unit/puppet-strings/describe_spec.rb

@@ -0,0 +1,141 @@
+require 'spec_helper'
+require 'puppet-strings/describe'
+require 'tempfile'
+
+#TODO:
+#basic describe
+#params from other files (e.g. file content)
+#--providers - list providers in detail
+#X--list - list all providers summary
+#--meta - List all metaparameters
+#--short - only list params
+
+describe PuppetStrings::Describe do
+  before :each do
+    # Populate the YARD registry with both Puppet and Ruby source
+
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
+Puppet::Type.newtype(:database) do
+  desc 'An example database server resource type.'
+end
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
+Puppet::ResourceApi.register_type(
+  name: 'apt_key',
+  docs: <<-EOS,
+@summary Example resource type using the new API.
+@raise SomeError
+This type provides Puppet with the capabilities to manage GPG keys needed
+by apt to perform package validation. Apt has it's own GPG keyring that can
+be manipulated through the `apt-key` command.
+@example here's an example
+  apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
+    source => 'http://apt.puppetlabs.com/pubkey.gpg'
+  }
+
+**Autorequires**:
+If Puppet is given the location of a key file which looks like an absolute
+path this type will autorequire that file.
+  EOS
+)
+SOURCE
+
+     YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
+  Puppet::Type.type(:file).newproperty(:content) do
+    include Puppet::Util::Checksums
+    include Puppet::DataSync
+
+    attr_reader :actual_content
+
+    desc <<-'EOT'
+      The desired contents of a file, as a string. This attribute is mutually
+      exclusive with `source` and `target`.
+    EOT
+  end
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
+  Puppet::Type.newtype(:file) do
+    include Puppet::Util::Checksums
+    include Puppet::Util::Backups
+    include Puppet::Util::SymbolicFileMode
+
+    @doc = "Manages files, including their content, ownership, and permissions.
+
+      The `file` type can manage normal files, directories, and symlinks; the
+      type should be specified in the `ensure` attribute."
+
+    newparam(:path) do
+      desc <<-'EOT'
+        The path to the file to manage.  Must be fully qualified.
+
+        On Windows, the path should include the drive letter and should use `/` as
+        the separator character (rather than `\\`).
+      EOT
+      isnamevar
+    end
+
+  end
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
+Puppet::Type.type(:file).newproperty(:source) do
+  include Puppet::Util::Checksums
+  include Puppet::DataSync
+
+  attr_reader :actual_content
+
+  desc <<-'EOT'
+    The desired contents of a file, as a string. This attribute is mutually
+    exclusive with `source` and `target`.
+  EOT
+end
+SOURCE
+  end
+
+  describe 'rendering DESCRIBE to stdout' do
+    it 'should output the expected describe content for the list of types' do
+      output = <<-DATA
+These are the types known to puppet:
+apt_key         - This type provides Puppet with the capabiliti ...
+database        - An example database server resource type.
+file            - Manages files, including their content, owner ...
+      DATA
+      expect{ PuppetStrings::Describe.render(nil, true) }.to output(output).to_stdout
+    end
+    it 'should output the expected describe content for a type' do
+      output = <<-DATA
+
+file
+====
+Manages files, including their content, ownership, and permissions.
+
+The `file` type can manage normal files, directories, and symlinks; the
+type should be specified in the `ensure` attribute.
+
+Parameters
+----------
+
+- **content**
+The desired contents of a file, as a string. This attribute is mutually
+exclusive with `source` and `target`.
+
+- **path**
+The path to the file to manage.  Must be fully qualified.
+
+On Windows, the path should include the drive letter and should use `/` as
+the separator character (rather than `\\`).
+
+- **source**
+The desired contents of a file, as a string. This attribute is mutually
+exclusive with `source` and `target`.
+
+Providers
+---------
+DATA
+      expect{ PuppetStrings::Describe.render(['file']) }.to output(output).to_stdout
+    end
+  end
+end