puppet-strings 2.2.0 → 2.3.0

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

@@ -301,9 +301,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
       name = '&' + name
     end
 
-    unless type
-      type = tag && tag.types ? tag.type : 'Any'
-    end
+    type ||= tag && tag.types ? tag.type : 'Any'
     type = optional ? "Optional[#{type}]" : type
 
     object.parameters << [name, to_puppet_literal(default)]

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

@@ -15,7 +15,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
     # Only accept calls to Puppet::ResourceApi
     return unless statement.count > 1
     module_name = statement[0].source
-    return unless [ 'Puppet::ResourceApi' ].include? module_name
+    return unless ['Puppet::ResourceApi'].include? module_name
 
     schema = extract_schema
 
@@ -92,7 +92,7 @@ class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::H
     # puts "hash from #{node.inspect}"
 
     kv_pairs = node.children.collect do |assoc|
-      [ value_from_node(assoc.children[0]), value_from_node(assoc.children[1]) ]
+      [value_from_node(assoc.children[0]), value_from_node(assoc.children[1])]
     end
     Hash[kv_pairs]
   end

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

@@ -15,7 +15,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
     register object
     object
   end
-    
+
   def find_docstring(node, kind)
     # Walk the tree searching for assignments or calls to desc/doc=
     node.traverse do |child|
@@ -98,10 +98,10 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
           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'
+            object.add('true') unless object.values.include? 'true' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
+            object.add('false') unless object.values.include? 'false' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
+            object.add('yes') unless object.values.include? 'yes' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
+            object.add('no') unless object.values.include? 'no' # rubocop:disable Performance/InefficientHashSearch Not supported on Ruby 2.1
           end
           break
         end
@@ -127,4 +127,3 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeBase < PuppetStrings::Yard::Handl
     default.isnamevar = true if default
   end
 end
-      

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

@@ -25,7 +25,7 @@ class PuppetStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base
       # 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
+    rescue  # rubocop:disable Style/RescueStandardError  Just catch everything
       log.error "Failed to parse #{@file}: "
       @statements = []
     end

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

@@ -41,41 +41,48 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
   end
 
   private
-  def transform_Program(o)
+
+  def transform_Program(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     # Cache the lines of the source text; we'll use this to locate comments
     @lines = o.source_text.lines.to_a
     o.definitions.map { |d| @visitor.visit(d) }
   end
 
-  def transform_Factory(o)
+  def transform_Factory(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     @visitor.visit(o.current)
   end
 
-  def transform_HostClassDefinition(o)
+  def transform_HostClassDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::ClassStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_ResourceTypeDefinition(o)
+  def transform_ResourceTypeDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_FunctionDefinition(o)
+  def transform_FunctionDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::FunctionStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_PlanDefinition(o)
+  def transform_PlanDefinition(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     statement = PuppetStrings::Yard::Parsers::Puppet::PlanStatement.new(o, @file)
     statement.extract_docstring(@lines)
     statement
   end
 
-  def transform_Object(o)
+  def transform_TypeAlias(o) # rubocop:disable Naming/UncommunicativeMethodParamName
+    statement = PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement.new(o, @file)
+    statement.extract_docstring(@lines)
+    statement
+  end
+
+  def transform_Object(o) # rubocop:disable Naming/UncommunicativeMethodParamName
     # Ignore anything else (will be compacted out of the resulting array)
   end
 end

data/lib/puppet-strings/yard/parsers/puppet/statement.rb

@@ -165,4 +165,29 @@ module PuppetStrings::Yard::Parsers::Puppet
     end
   end
 
+  # Implements the Puppet data type alias statement.
+  class DataTypeAliasStatement < Statement
+    attr_reader :name
+    attr_reader :alias_of
+
+    # Initializes the Puppet data type alias statement.
+    # @param [Puppet::Pops::Model::TypeAlias] object The model object for the type statement.
+    # @param [String] file The file containing the statement.
+    def initialize(object, file)
+      super(object, file)
+
+      type_expr = object.type_expr
+      case type_expr
+      when Puppet::Pops::Model::AccessExpression
+        # TODO: I don't like rebuilding the source from the AST, but AccessExpressions don't expose the original source
+        @alias_of = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr.left_expr).extract_text + '['
+        @alias_of << type_expr.keys.map { |key| ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(key).extract_text }.join(', ')
+        @alias_of << ']'
+      else
+        adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr)
+        @alias_of = adapter.extract_text
+      end
+      @name = object.name
+    end
+  end
 end

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

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

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(false)) %>
+        <% if item.type == :puppet_data_type_alias %><small>Alias</small><% end %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -7,6 +7,15 @@ def generate_puppet_class_list
   generate_list_contents
 end
 
+# Generates the searchable Puppet data type list.
+# @return [void]
+def generate_puppet_data_type_list
+  @items = Registry.all(:puppet_data_type, :puppet_data_type_alias).sort_by {|dt| dt.name.to_s }
+  @list_title = 'Data Type List'
+  @list_type = 'puppet_data_type'
+  generate_list_contents
+end
+
 # Generates the searchable Puppet defined type list.
 # @return [void]
 def generate_puppet_defined_type_list

data/lib/puppet-strings/yard/templates/default/layout/html/objects.erb

@@ -23,6 +23,8 @@
               <small>(Resource type: <%= obj.type_name %>)</small>
       <% elsif obj.type == :puppet_function %>
               <small>(<%= obj.function_type %>)</small>
+      <% elsif obj.type == :puppet_data_type_alias %>
+              <small>(Alias)</small>
       <% end %>
             </li>
     <% end %>

data/lib/puppet-strings/yard/templates/default/layout/html/setup.rb

@@ -4,7 +4,7 @@ def init
   case object
   when '_index.html'
     @page_title = options.title
-    sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
+    sections :layout, [:index, [:listing, [:classes, :data_types, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
   else
     super
   end
@@ -30,6 +30,10 @@ def layout
     @nav_url = url_for_list('puppet_class')
     @page_title = "Puppet Class: #{object.name}"
     @path = object.path
+  when PuppetStrings::Yard::CodeObjects::DataType, PuppetStrings::Yard::CodeObjects::DataTypeAlias
+    @nav_url = url_for_list('puppet_data_type')
+    @page_title = "Data Type: #{object.name}"
+    @path = object.path
   when PuppetStrings::Yard::CodeObjects::DefinedType
     @nav_url = url_for_list('puppet_defined_type')
     @page_title = "Defined Type: #{object.name}"
@@ -76,6 +80,11 @@ def create_menu_lists
       title: 'Puppet Classes',
       search_title: 'Puppet Classes'
     },
+    {
+      type: 'puppet_data_type',
+      title: 'Data Types',
+      search_title: 'Data Types',
+    },
     {
       type: 'puppet_defined_type',
       title: 'Defined Types',
@@ -155,6 +164,14 @@ def classes
   erb(:objects)
 end
 
+# Renders the data types section.
+# @return [String] Returns the rendered section.
+def data_types
+  @title = 'Data Type Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_data_type, :puppet_data_type_alias)
+  erb(:objects)
+end
+
 # Renders the defined types section.
 # @return [String] Returns the rendered section.
 def defined_types

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Data Type: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/setup.rb

@@ -0,0 +1,5 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :source
+end

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/alias_of.erb

@@ -0,0 +1,10 @@
+<% if @alias_of && !@alias_of.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <div class="docstring">
+    <div class="discussion">
+      <pre class="code"><span class="info"><%= @alias_of %></span></pre>
+    </div>
+  </div>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Data Type Alias: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/setup.rb

@@ -0,0 +1,17 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :alias_of, :note, :todo, T('tags'), :source
+end
+
+# Renders the alias_of section.
+# @return [String] Returns the rendered section.
+def alias_of
+  # Properties are the same thing as parameters (from the documentation standpoint),
+  # so reuse the same template but with a different title and data source.
+  #@parameters = object.properties || []
+  #@parameters.sort_by! { |p| p.name }
+  @tag_title = 'Alias of'
+  @alias_of = object.alias_of
+  erb(:alias_of)
+end

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/tags/setup.rb

@@ -4,6 +4,7 @@ def param
   tag(:param) if
     object.type == :method ||
     object.type == :puppet_class ||
+    object.type == :puppet_data_type ||
     object.type == :puppet_defined_type ||
     object.type == :puppet_function ||
     object.type == :puppet_task ||

data/lib/puppet/face/strings.rb

@@ -117,7 +117,7 @@ Puppet::Face.define(:strings, '0.0.1') do
       
       if args.length > 1
         if options[:list]
-          $stderr.puts "WARNING: ignoring types when listing all types."
+          warn "WARNING: ignoring types when listing all types."
         else
           options[:describe_types] = args[0..-2]
         end
@@ -159,10 +159,10 @@ Puppet::Face.define(:strings, '0.0.1') do
     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."
+        warn "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead."
       end
       if options[:emit_json_stdout]
-        $stderr.puts "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead."
+        warn "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead."
       end
       markup = options[:markup]
       generate_options[:markup] = markup if markup

data/spec/acceptance/emit_json_options_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper_acceptance'
+
+describe 'Emitting JSON' do
+  before(:all) do
+    @test_module_path = sut_module_path(/Module test/)
+    @remote_tmp_path = sut_tmp_path
+  end
+
+  let(:expected) do
+    {
+      "puppet_classes" => [],
+      "data_types" => [],
+      "data_type_aliases" => [],
+      "defined_types" => [],
+      "resource_types" => [],
+      "providers" => [],
+      "puppet_functions" => [
+        "name" => "function3x",
+        "file" => "#{@test_module_path}/lib/puppet/parser/functions/function3x.rb",
+        "line" => 1,
+        "type" => "ruby3x",
+        "signatures" => [
+          {
+            "signature" =>"function3x()",
+            "docstring" => {
+              "text" => "This is the function documentation for `function3x`",
+              "tags" => [
+                {
+                  "tag_name"=>"return",
+                  "text"=>"",
+                  "types"=>["Any"]
+                }
+              ]
+            }
+          },
+        ],
+        "docstring" => {
+          "text" => "This is the function documentation for `function3x`",
+          "tags" => ["tag_name" => "return", "text" => "", "types" => ["Any"]]},
+          "source" => "Puppet::Parser::Functions.newfunction(:function3x, :doc => \"This is the function documentation for `function3x`\") do |args|\nend"
+      ],
+      "puppet_tasks" => [],
+      "puppet_plans" => []
+    }
+  end
+
+  [
+    { :title => '--format json and STDOUT', :cmd_line => '--format json' },
+    { :title => '--emit-json-stdout', :cmd_line => '--emit-json-stdout' }
+  ].each do |testcase|
+    it "should emit JSON to stdout when using #{testcase[:title]}" do
+      output = PuppetLitmus::Serverspec.run_shell("puppet strings generate #{testcase[:cmd_line]} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\"").stdout.chomp
+      expect(JSON.parse(output)).to eq(expected)
+    end
+  end
+
+  [
+    { :title => '--format json and --out', :cmd_line => '--format json --out "TMPFILE"' },
+    { :title => '--emit-json', :cmd_line => '--emit-json "TMPFILE"' },
+  ].each do |testcase|
+    it "should write JSON to a file when using #{testcase[:title]}" do
+      tmpfile = File.join(@remote_tmp_path, 'json_output.json')
+      cmd = "puppet strings generate #{testcase[:cmd_line].gsub('TMPFILE', tmpfile)} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\""
+      PuppetLitmus::Serverspec.run_shell(cmd)
+      output = JSON.parse(file(tmpfile).content)
+      expect(output).to eq(expected)
+    end
+  end
+end