Add a new function "fetch"

Dmitry Ilyin · Dmitry Ilyin · commit 4d2e388b4d31 · 2015-08-26T02:31:35.000+03:00
* Extracts a value from a deeply-nested data structure
diff --git a/README.markdown b/README.markdown
@@ -1023,6 +1023,40 @@ Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x |
 
 **stdlib 5.x**: When released, stdlib 5.x will drop support for Puppet 2.7.x. Please see [this discussion](https://github.com/puppetlabs/puppetlabs-stdlib/pull/176#issuecomment-30251414).
 
+#### `fetch`
+
+*Type*: rvalue.
+
+Looks up into a complex structure of arrays and hashes and returns a value
+or the default value if nothing was found.
+
+Key can contain slashes to describe path components. The function will go down
+the structure and try to extract the required value.
+
+$data = {
+  'a' => {
+    'b' => [
+      'b1',
+      'b2',
+      'b3',
+    ]
+  }
+}
+
+$value = fetch($data, 'a/b/2', 'not_found', '/')
+=> $value = 'b3'
+
+a -> first hash key
+b -> second hash key
+2 -> array index starting with 0
+
+not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil.
+/ -> (optional) path delimiter. Defaults to '/'.
+
+In addition to the required "key" argument, "structure" accepts default
+argument. It will be returned if no value was found or a path component is
+missing. And the fourth argument can set a variable path separator.
+
 ##Development
 
 Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)
diff --git a/lib/puppet/parser/functions/fetch.rb b/lib/puppet/parser/functions/fetch.rb
@@ -0,0 +1,70 @@
+module Puppet::Parser::Functions
+  newfunction(
+      :fetch,
+      :type => :rvalue,
+      :arity => -2,
+      :doc => <<-eos
+Looks up into a compex structure of arrays and hashes and returns a value
+or the default value if nothing was found.
+
+Key can contain slashes to describe path components. The fuction will go down
+the structure and try to extract the required value.
+
+$data = {
+  'a' => {
+    'b' => [
+      'b1',
+      'b2',
+      'b3',
+    ]
+  }
+}
+
+$value = fetch($data, 'a/b/2', 'not_found', '/')
+=> $value = 'b3'
+
+a -> first hash key
+b -> second hash key
+2 -> array index starting with 0
+
+not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil.
+/ -> (optional) path delimiter. Defaults to '/'.
+
+In addition to the required "key" argument, "structure" accepts default
+argument. It will be returned if no value was found or a path component is
+missing. And the fourth argument can set a variable path separator.
+  eos
+  ) do |args|
+
+    path_lookup = lambda do |data, path, default|
+      # no data -> return default
+      break default if data.nil?
+      # wrong path -> return default
+      break default unless path.is_a? Array
+      # empty path -> value found
+      break data unless path.any?
+      # non-empty path and non-structure data -> return default
+      break default unless data.is_a? Hash or data.is_a? Array
+
+      key = path.shift
+      if data.is_a? Array
+        begin
+          key = Integer key
+        rescue ArgumentError
+          break default
+        end
+      end
+      path_lookup.call data[key], path, default
+    end
+
+    data = args[0]
+    path = args[1]
+    default = args[2]
+    separator = args[3]
+    separator = '/' unless separator
+
+    path = '' unless path
+    path = path.split separator
+    path_lookup.call data, path, default
+  end
+end
diff --git a/spec/acceptance/fetch_spec.rb b/spec/acceptance/fetch_spec.rb
@@ -0,0 +1,47 @@
+#! /usr/bin/env ruby -S rspec
+require 'spec_helper_acceptance'
+
+describe 'fetch function', :unless => UNSUPPORTED_PLATFORMS.include?(fact('operatingsystem')) do
+  describe 'success' do
+    it 'fetches a value' do
+      pp = <<-EOS
+      $data = {
+        'a' => { 'b' => 'passing'}
+      }
+
+      $tests = fetch($a, 'a/b')
+      notice(inline_template('tests are <%= @tests.inspect %>'))
+      EOS
+
+      apply_manifest(pp, :catch_failures => true) do |r|
+        expect(r.stdout).to match(/tests are "passing"/)
+      end
+    end
+  end
+  describe 'failure' do
+    it 'uses a default value' do
+      pp = <<-EOS
+      $data = {
+        'a' => { 'b' => 'passing'}
+      }
+
+      $tests = fetch($a, 'c/d', 'using the default value')
+      notice(inline_template('tests are <%= @tests.inspect %>'))
+      EOS
+
+      apply_manifest(pp, :expect_failures => true) do |r|
+        expect(r.stdout).to match(/using the default value/)
+      end
+    end
+
+    it 'raises error on incorrect number of arguments' do
+      pp = <<-EOS
+      $o = fetch()
+      EOS
+
+      apply_manifest(pp, :expect_failures => true) do |r|
+        expect(r.stderr).to match(/wrong number of arguments/i)
+      end
+    end
+  end
+end
diff --git a/spec/functions/fetch_spec.rb b/spec/functions/fetch_spec.rb
@@ -0,0 +1,136 @@
+require 'spec_helper'
+
+describe 'the structure function' do
+  let(:scope) { PuppetlabsSpec::PuppetInternals.scope }
+
+
+  it 'should exist' do
+    expect(Puppet::Parser::Functions.function('fetch')).to eq 'function_fetch'
+  end
+
+  context 'single values' do
+
+    it 'should be able to return a single value' do
+      expect(scope.function_fetch(['test'])).to eq 'test'
+    end
+
+    it 'should use the default value if data is a single value and path is present' do
+      expect(scope.function_fetch(['test', 'path', 'default'])).to eq 'default'
+    end
+
+    it 'should return default if there is no data' do
+      expect(scope.function_fetch([nil, nil, 'default'])).to eq 'default'
+    end
+
+    it 'should be able to use data structures as default values' do
+      expect(scope.function_fetch(['test', 'path', {'a' => 'a'}])).to eq({'a' => 'a'})
+    end
+  end
+
+  context 'structure values' do
+    it 'extracts a hash value' do
+      data = {
+        'a' => "1",
+      }
+      expect(scope.function_fetch([data, 'a', '2'])).to eq '1'
+    end
+
+    it 'returns the default value if there is no hash value' do
+      data = {
+          'a' => "1",
+      }
+      expect(scope.function_fetch([data, 'b', '2'])).to eq '2'
+    end
+
+    it 'should extract a deep hash value' do
+      data = {
+          'a' => {
+              'b' => 'c'
+          }
+      }
+      expect(scope.function_fetch([data, 'a/b', 'default'])).to eq 'c'
+    end
+
+    it 'should return default value if path is not found' do
+      data = {
+          'a' => {
+              'b' => 'c'
+          }
+      }
+      expect(scope.function_fetch([data, 'missing', 'default'])).to eq 'default'
+    end
+
+    it 'should return default if path is too long' do
+      data = {
+          'a' => {
+              'b' => 'c'
+          }
+      }
+      expect(scope.function_fetch([data, 'a/b/c/d', 'default'])).to eq 'default'
+    end
+
+    it 'should support array index in the path' do
+      data = {
+          'a' => {
+              'b' => ['b0', 'b1', 'b2', 'b3']
+          }
+      }
+      expect(scope.function_fetch([data, 'a/b/2', 'default'])).to eq 'b2'
+    end
+
+    it 'should return default if index is out of array length' do
+      data = {
+          'a' => {
+              'b' => ['b0', 'b1', 'b2', 'b3']
+          }
+      }
+      expect(scope.function_fetch([data, 'a/b/5', 'default'])).to eq 'default'
+    end
+
+    it 'should be able to path though both array and hashes' do
+      data = {
+          'a' => {
+              'b' => [
+                  'b0',
+                  'b1',
+                  {
+                      'x' => {
+                          'y' => 'z'
+                      }
+                  },
+                  'b3'
+              ]
+          }
+      }
+      expect(scope.function_fetch([data, 'a/b/2/x/y', 'default'])).to eq 'z'
+    end
+
+    it 'should be able to return "true" value' do
+      data = {
+          'a' => false,
+          'b' => true,
+      }
+      expect(scope.function_fetch([data, 'b', 1])).to eq true
+      expect(scope.function_fetch([data, 'c', true])).to eq true
+    end
+
+    it 'should be able to return "false" value' do
+      data = {
+          'a' => false,
+          'b' => true,
+      }
+      expect(scope.function_fetch([data, 'a', 1])).to eq false
+      expect(scope.function_fetch([data, 'c', false])).to eq false
+    end
+
+    it 'should be able to use a custom path separator' do
+      data = {
+          'a' => {
+              'b' => 'c'
+          }
+      }
+      expect(scope.function_fetch([data, 'a::b', nil, '::'])).to eq 'c'
+      expect(scope.function_fetch([data, 'a::c', nil, '::'])).to eq nil
+    end
+  end
+end
