(MODULES-2516) Adds an is_a() function

The data type system is very hard to understand. Many people don't
understand why

    type_of([1,2,3]) == Array

will fail, but

    type_of([1,2,3]) <= Array

passes. This does a simpler validation that doesn't rely on explicit
data types. Instead, use

    $foo = [1,2,3]
    if $foo.is_a(Array) {
      notify { 'This is an array': }
    }

This is based on code by Ben Ford <ben.ford@puppetlabs.com>.

  * Added acceptance tests
  * Added dispatch
  * Improved unit tests
  * Added docs to README

5 files changed, 111 insertions, 1 deletions

diff --git a/README.markdown b/README.markdown
index f95d37d..aeacfdc 100644
--- a/README.markdown
+++ b/README.markdown
@@ -403,6 +403,29 @@ Converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns
 
 Returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. *Type*: rvalue.
 
+#### `is_a`
+
+Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks.
+
+  ~~~
+  foo = 3
+  $bar = [1,2,3]
+  $baz = 'A string!'
+
+  if $foo.is_a(Integer) {
+    notify  { 'foo!': }
+  }
+  if $bar.is_a(Array) {
+    notify { 'bar!': }
+  }
+  if $baz.is_a(String) {
+    notify { 'baz!': }
+  }
+  ~~~
+
+See the documentation for "The Puppet Type System" for more information about types.
+See the `assert_type()` function for flexible ways to assert the type of a value.
+
 #### `is_array`
 
 Returns 'true' if the variable passed to this function is an array. *Type*: rvalue.
diff --git a/lib/puppet/functions/is_a.rb b/lib/puppet/functions/is_a.rb
new file mode 100644
index 0000000..da98b03
--- /dev/null
+++ b/lib/puppet/functions/is_a.rb
@@ -0,0 +1,32 @@
+# Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks.
+#
+# @example how to check a data type
+#   # check a data type
+#       foo = 3
+#       $bar = [1,2,3]
+#       $baz = 'A string!'
+#
+#       if $foo.is_a(Integer) {
+#         notify  { 'foo!': }
+#       }
+#       if $bar.is_a(Array) {
+#         notify { 'bar!': }
+#       }
+#       if $baz.is_a(String) {
+#         notify { 'baz!': }
+#       }
+#
+# See the documentation for "The Puppet Type System" for more information about types.
+# See the `assert_type()` function for flexible ways to assert the type of a value.
+#
+Puppet::Functions.create_function(:is_a) do
+  dispatch :is_a do
+    param 'Any', :value
+    param 'Type', :type
+  end
+
+  def is_a(value, type)
+    # See puppet's lib/puppet/pops/evaluator/evaluator_impl.rb eval_MatchExpression
+    Puppet::Pops::Types::TypeCalculator.instance?(type, value)
+  end
+end
diff --git a/spec/acceptance/is_a_spec.rb b/spec/acceptance/is_a_spec.rb
new file mode 100644
index 0000000..533673c
--- /dev/null
+++ b/spec/acceptance/is_a_spec.rb
@@ -0,0 +1,28 @@
+#! /usr/bin/env ruby -S rspec
+require 'spec_helper_acceptance'
+
+describe 'is_a function', :unless => UNSUPPORTED_PLATFORMS.include?(fact('operatingsystem')) do
+  it 'should match a string' do
+    pp = <<-EOS
+    if 'hello world'.is_a(String) {
+      notify { 'output correct': }
+    }
+    EOS
+
+    apply_manifest(pp, :catch_failures => true) do |r|
+      expect(r.stdout).to match(/Notice: output correct/)
+    end
+  end
+
+  it 'should not match a integer as string' do
+    pp = <<-EOS
+    if 5.is_a(String) {
+      notify { 'output wrong': }
+    }
+    EOS
+
+    apply_manifest(pp, :catch_failures => true) do |r|
+      expect(r.stdout).not_to match(/Notice: output wrong/)
+    end
+  end
+end
diff --git a/spec/functions/is_a_spec.rb b/spec/functions/is_a_spec.rb
new file mode 100644
index 0000000..8dec13f
--- /dev/null
+++ b/spec/functions/is_a_spec.rb
@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+if ENV["FUTURE_PARSER"] == 'yes'
+  describe 'type_of' do
+    pending 'teach rspec-puppet to load future-only functions under 3.7.5' do
+      it { is_expected.not_to eq(nil) }
+    end
+  end
+end
+
+if Puppet.version.to_f >= 4.0
+  describe 'is_a' do
+    it { is_expected.not_to eq(nil) }
+    it { is_expected.to run.with_params().and_raise_error(ArgumentError) }
+    it { is_expected.to run.with_params('', '').and_raise_error(ArgumentError) }
+
+    it 'succeeds when comparing a string and a string' do
+      is_expected.to run.with_params('hello world', String).and_return(true)
+    end
+
+    it 'fails when comparing an integer and a string' do
+      is_expected.to run.with_params(5, String).and_return(false)
+    end
+  end
+end
diff --git a/spec/functions/type_of_spec.rb b/spec/functions/type_of_spec.rb
index f770990..cc9ef78 100644
--- a/spec/functions/type_of_spec.rb
+++ b/spec/functions/type_of_spec.rb
@@ -2,7 +2,9 @@ require 'spec_helper'
 
 if ENV["FUTURE_PARSER"] == 'yes'
   describe 'type_of' do
-    pending 'teach rspec-puppet to load future-only functions under 3.7.5'
+    pending 'teach rspec-puppet to load future-only functions under 3.7.5' do
+      it { is_expected.not_to eq(nil) }
+    end
   end
 end