(maint) Add a PuppetStack that adds stack entries to the backtrace

This adds a mechanism which can be used to make an entry
on the ruby stack that indiciates that it is a puppet stack frame.
The frame is visible in the ruby backtrace and PuppetStack provides a
stacktrace that is filtered to only contain .pp entries.

This adds the mechanism and a test. The mechanism is not yet in use.

Author: hlindberg

lib/puppet/pops.rb

@@ -14,6 +14,7 @@ module Pops
 
     require 'puppet/pops/patterns'
     require 'puppet/pops/utils'
+    require 'puppet/pops/puppet_stack'
 
     require 'puppet/pops/adaptable'
     require 'puppet/pops/adapters'

lib/puppet/pops/puppet_stack.rb

@@ -0,0 +1,43 @@
+module Puppet::Pops
+# Module for making a call such that there is an identifiable entry on
+# the ruby call stack enabling getting a puppet call stack
+# To use this make a call with:
+# ```
+# Puppet::Pops::PuppetStack.stack(file, line, receiver, message, args)
+# ```
+# To get the stack call:
+# ```
+# Puppet::Pops::PuppetStack.stacktrace
+#
+# When getting a backtrace in Ruby, the puppet stack frames are
+# identified as coming from "in 'stack'" and having a ".pp" file
+# name.
+# To support testing, a given file that is an empty string, or nil
+# as well as a nil line number are supported. Such stack frames
+# will be represented with the text `unknown` and `0´ respectively.
+#
+module PuppetStack
+  # Sends a message to an obj such that it appears to come from
+  # file, line when calling stacktrace.
+  #
+  def self.stack(file, line, obj, message, args, &block)
+    file = '' if file.nil?
+    line = 0 if line.nil?
+
+    if block_given?
+      Kernel.eval("obj.send(message, *args, &block)", Kernel.binding(), file, line)
+    else
+      Kernel.eval("obj.send(message, *args)", Kernel.binding(), file, line)
+    end
+  end
+
+  def self.stacktrace
+    result = caller().reduce([]) do |memo, loc|
+      if loc =~ /^(.*\.pp)?:([0-9]+):in `stack'/
+        memo << [$1.nil? ? 'unknown' : $1, $2.to_i]
+      end
+      memo
+    end.reverse
+  end
+end
+end

spec/unit/pops/puppet_stack_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+require 'puppet/pops'
+
+describe 'Puppet::Pops::PuppetStack' do
+  class StackTraceTest
+    def get_stacktrace
+      Puppet::Pops::PuppetStack.stacktrace
+    end
+
+    def one_level
+      Puppet::Pops::PuppetStack.stack("one_level.pp", 1234, self, :get_stacktrace, [])
+    end
+
+    def one_level
+      Puppet::Pops::PuppetStack.stack("one_level.pp", 1234, self, :get_stacktrace, [])
+    end
+
+    def two_levels
+      Puppet::Pops::PuppetStack.stack("two_levels.pp", 1237, self, :level2, [])
+    end
+
+    def level2
+      Puppet::Pops::PuppetStack.stack("level2.pp", 1240, self, :get_stacktrace, [])
+    end
+
+    def gets_block(a, &block)
+      block.call(a)
+    end
+
+    def gets_args_and_block(a, b, &block)
+      block.call(a, b)
+    end
+
+    def with_nil_file
+      Puppet::Pops::PuppetStack.stack(nil, 1250, self, :get_stacktrace, [])
+    end
+
+    def with_empty_string_file
+      Puppet::Pops::PuppetStack.stack('', 1251, self, :get_stacktrace, [])
+    end
+  end
+
+  it 'returns an empty array from stacktrace when there is nothing on the stack' do
+    expect(Puppet::Pops::PuppetStack.stacktrace).to eql([])
+  end
+
+  it 'returns a one element array with file, line from stacktrace when there is one entry on the stack' do
+    expect(StackTraceTest.new.one_level).to eql([['one_level.pp', 1234]])
+  end
+
+  it 'returns an array from stacktrace with information about each level with oldest frame last' do
+    expect(StackTraceTest.new.two_levels).to eql([['two_levels.pp', 1237], ['level2.pp', 1240]])
+  end
+
+  it 'accepts file to be nil' do
+    expect(StackTraceTest.new.with_nil_file).to eql([['unknown', 1250]])
+  end
+
+  it 'accepts file to be empty_string' do
+    expect(StackTraceTest.new.with_empty_string_file).to eql([['unknown', 1251]])
+  end
+
+  it 'stacktrace is empty when call has returned' do
+    StackTraceTest.new.two_levels
+    expect(Puppet::Pops::PuppetStack.stacktrace).to eql([])
+  end
+
+  it 'allows passing a block to the stack call' do
+    expect(Puppet::Pops::PuppetStack.stack("test.pp", 1, StackTraceTest.new, :gets_block, ['got_it']) {|x| x }).to eql('got_it')
+  end
+
+  it 'allows passing multiple variables and a block' do
+    expect(
+      Puppet::Pops::PuppetStack.stack("test.pp", 1, StackTraceTest.new, :gets_args_and_block, ['got_it', 'again']) {|x, y| [x,y].join(' ')}
+      ).to eql('got_it again')
+  end
+
+end