From a1cae426f1d6b8f2c19184ec8aac3ebc47d97744 Mon Sep 17 00:00:00 2001
From: Ken Barber <ken@bob.sh>
Date: Fri, 29 Jul 2011 23:09:30 +0100
Subject: (#3) Provide documentation for remaining functions.

---
 lib/puppet/parser/functions/delete.rb               |  9 ++++++++-
 lib/puppet/parser/functions/delete_at.rb            |  7 +++++++
 lib/puppet/parser/functions/downcase.rb             |  1 +
 lib/puppet/parser/functions/empty.rb                |  1 +
 lib/puppet/parser/functions/flatten.rb              |  8 ++++++++
 lib/puppet/parser/functions/grep.rb                 | 10 ++++++++++
 lib/puppet/parser/functions/hash.rb                 |  7 +++++++
 lib/puppet/parser/functions/is_array.rb             |  1 +
 lib/puppet/parser/functions/is_float.rb             |  1 +
 lib/puppet/parser/functions/is_hash.rb              |  1 +
 lib/puppet/parser/functions/is_integer.rb           |  1 +
 lib/puppet/parser/functions/is_numeric.rb           |  1 +
 lib/puppet/parser/functions/is_string.rb            |  1 +
 lib/puppet/parser/functions/is_valid_domain_name.rb |  1 +
 lib/puppet/parser/functions/is_valid_ip_address.rb  |  1 +
 lib/puppet/parser/functions/is_valid_mac_address.rb |  1 +
 lib/puppet/parser/functions/join.rb                 |  7 +++++++
 lib/puppet/parser/functions/keys.rb                 |  1 +
 lib/puppet/parser/functions/load_json.rb            |  2 ++
 lib/puppet/parser/functions/load_yaml.rb            |  2 ++
 lib/puppet/parser/functions/lstrip.rb               |  1 +
 lib/puppet/parser/functions/member.rb               | 11 +++++++++++
 lib/puppet/parser/functions/type.rb                 |  4 +++-
 23 files changed, 78 insertions(+), 2 deletions(-)

(limited to 'lib')

diff --git a/lib/puppet/parser/functions/delete.rb b/lib/puppet/parser/functions/delete.rb
index 0d208b5..ab8f75b 100644
--- a/lib/puppet/parser/functions/delete.rb
+++ b/lib/puppet/parser/functions/delete.rb
@@ -7,11 +7,18 @@
 
 module Puppet::Parser::Functions
   newfunction(:delete, :type => :rvalue, :doc => <<-EOS
+Deletes a selected element from an array.
+
+*Examples:*
+
+    delete(['a','b','c'], 'b')
+
+Would return: ['a','c']
     EOS
   ) do |arguments|
 
     if (arguments.size != 2) then
-      raise(Puppet::ParseError, "is_valid_netmask(): Wrong number of arguments "+
+      raise(Puppet::ParseError, "delete(): Wrong number of arguments "+
         "given #{arguments.size} for 2")
     end
 
diff --git a/lib/puppet/parser/functions/delete_at.rb b/lib/puppet/parser/functions/delete_at.rb
index 10190ba..3eb4b53 100644
--- a/lib/puppet/parser/functions/delete_at.rb
+++ b/lib/puppet/parser/functions/delete_at.rb
@@ -4,6 +4,13 @@
 
 module Puppet::Parser::Functions
   newfunction(:delete_at, :type => :rvalue, :doc => <<-EOS
+Deletes a determined indexed value from an array.
+
+*Examples:*
+
+    delete_at(['a','b','c'], 1)
+
+Would return: ['a','c']
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/downcase.rb b/lib/puppet/parser/functions/downcase.rb
index 71f8480..4066d21 100644
--- a/lib/puppet/parser/functions/downcase.rb
+++ b/lib/puppet/parser/functions/downcase.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:downcase, :type => :rvalue, :doc => <<-EOS
+Converts the case of a string or all strings in an array to lower case.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/empty.rb b/lib/puppet/parser/functions/empty.rb
index e78ebf0..80ebb86 100644
--- a/lib/puppet/parser/functions/empty.rb
+++ b/lib/puppet/parser/functions/empty.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:empty, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable is empty.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/flatten.rb b/lib/puppet/parser/functions/flatten.rb
index 6036f72..781da78 100644
--- a/lib/puppet/parser/functions/flatten.rb
+++ b/lib/puppet/parser/functions/flatten.rb
@@ -4,6 +4,14 @@
 
 module Puppet::Parser::Functions
   newfunction(:flatten, :type => :rvalue, :doc => <<-EOS
+This function flattens any deeply nested arrays and returns a single flat array
+as a result.
+
+*Examples:*
+
+    flatten(['a', ['b', ['c']]])
+
+Would return: ['a','b','c']
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/grep.rb b/lib/puppet/parser/functions/grep.rb
index 2caaa6f..ceba9ec 100644
--- a/lib/puppet/parser/functions/grep.rb
+++ b/lib/puppet/parser/functions/grep.rb
@@ -4,6 +4,16 @@
 
 module Puppet::Parser::Functions
   newfunction(:grep, :type => :rvalue, :doc => <<-EOS
+This function searches through an array and returns any elements that match
+the provided regular expression.
+
+*Examples:*
+
+    grep(['aaa','bbb','ccc','aaaddd'], 'aaa')
+
+Would return:
+
+    ['aaa','aaaddd']
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/hash.rb b/lib/puppet/parser/functions/hash.rb
index f0c01d4..453ba1e 100644
--- a/lib/puppet/parser/functions/hash.rb
+++ b/lib/puppet/parser/functions/hash.rb
@@ -4,6 +4,13 @@
 
 module Puppet::Parser::Functions
   newfunction(:hash, :type => :rvalue, :doc => <<-EOS
+This function converts and array into a hash.
+
+*Examples:*
+
+    hash(['a',1,'b',2,'c',3])
+
+Would return: {'a'=>1,'b'=>2,'c'=>3}
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_array.rb b/lib/puppet/parser/functions/is_array.rb
index 0b508fd..b39e184 100644
--- a/lib/puppet/parser/functions/is_array.rb
+++ b/lib/puppet/parser/functions/is_array.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_array, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable passed to this function is an array.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_float.rb b/lib/puppet/parser/functions/is_float.rb
index 8aed848..2fc05ba 100644
--- a/lib/puppet/parser/functions/is_float.rb
+++ b/lib/puppet/parser/functions/is_float.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_float, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable passed to this function is a float.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_hash.rb b/lib/puppet/parser/functions/is_hash.rb
index 000306e..ad907f0 100644
--- a/lib/puppet/parser/functions/is_hash.rb
+++ b/lib/puppet/parser/functions/is_hash.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_hash, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable passed to this function is a hash.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_integer.rb b/lib/puppet/parser/functions/is_integer.rb
index 9dd1cee..8ee34f6 100644
--- a/lib/puppet/parser/functions/is_integer.rb
+++ b/lib/puppet/parser/functions/is_integer.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_integer, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable returned to this string is an integer.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_numeric.rb b/lib/puppet/parser/functions/is_numeric.rb
index c2c0fb5..ce13ece 100644
--- a/lib/puppet/parser/functions/is_numeric.rb
+++ b/lib/puppet/parser/functions/is_numeric.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_numeric, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable passed to this function is a number.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_string.rb b/lib/puppet/parser/functions/is_string.rb
index 8a02a10..f5bef04 100644
--- a/lib/puppet/parser/functions/is_string.rb
+++ b/lib/puppet/parser/functions/is_string.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_string, :type => :rvalue, :doc => <<-EOS
+Returns true if the variable passed to this function is a string.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_valid_domain_name.rb b/lib/puppet/parser/functions/is_valid_domain_name.rb
index 99d6f86..7dd9c0b 100644
--- a/lib/puppet/parser/functions/is_valid_domain_name.rb
+++ b/lib/puppet/parser/functions/is_valid_domain_name.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_valid_domain_name, :type => :rvalue, :doc => <<-EOS
+Returns true if the string passed to this function is a valid IP address. Support for IPv4 and IPv6 address types is included.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_valid_ip_address.rb b/lib/puppet/parser/functions/is_valid_ip_address.rb
index 4f45890..604d938 100644
--- a/lib/puppet/parser/functions/is_valid_ip_address.rb
+++ b/lib/puppet/parser/functions/is_valid_ip_address.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_valid_ip_address, :type => :rvalue, :doc => <<-EOS
+Returns true if the string passed to this function is a valid IP address.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/is_valid_mac_address.rb b/lib/puppet/parser/functions/is_valid_mac_address.rb
index a00d874..53199b6 100644
--- a/lib/puppet/parser/functions/is_valid_mac_address.rb
+++ b/lib/puppet/parser/functions/is_valid_mac_address.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:is_valid_mac_address, :type => :rvalue, :doc => <<-EOS
+Returns true if the string passed to this function is a valid mac address.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/join.rb b/lib/puppet/parser/functions/join.rb
index 945556a..005a46e 100644
--- a/lib/puppet/parser/functions/join.rb
+++ b/lib/puppet/parser/functions/join.rb
@@ -4,6 +4,13 @@
 
 module Puppet::Parser::Functions
   newfunction(:join, :type => :rvalue, :doc => <<-EOS
+This function joins an array into a string using a seperator.
+
+*Examples:*
+
+    join(['a','b','c'], ",")
+
+Would result in: "a,b,c"
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/keys.rb b/lib/puppet/parser/functions/keys.rb
index 3a92a47..f0d13b6 100644
--- a/lib/puppet/parser/functions/keys.rb
+++ b/lib/puppet/parser/functions/keys.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:keys, :type => :rvalue, :doc => <<-EOS
+Returns the keys of a hash as an array.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/load_json.rb b/lib/puppet/parser/functions/load_json.rb
index 7c3f187..333cf11 100644
--- a/lib/puppet/parser/functions/load_json.rb
+++ b/lib/puppet/parser/functions/load_json.rb
@@ -4,6 +4,8 @@
 
 module Puppet::Parser::Functions
   newfunction(:load_json, :type => :rvalue, :doc => <<-EOS
+This function accepts JSON as a string and converts into the correct Puppet
+structure.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/load_yaml.rb b/lib/puppet/parser/functions/load_yaml.rb
index 1bc2f36..2683277 100644
--- a/lib/puppet/parser/functions/load_yaml.rb
+++ b/lib/puppet/parser/functions/load_yaml.rb
@@ -4,6 +4,8 @@
 
 module Puppet::Parser::Functions
   newfunction(:load_yaml, :type => :rvalue, :doc => <<-EOS
+This function accepts YAML as a string and converts it into the correct 
+Puppet structure.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/lstrip.rb b/lib/puppet/parser/functions/lstrip.rb
index a7b2656..3a64de3 100644
--- a/lib/puppet/parser/functions/lstrip.rb
+++ b/lib/puppet/parser/functions/lstrip.rb
@@ -4,6 +4,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:lstrip, :type => :rvalue, :doc => <<-EOS
+Strips leading spaces to the left of a string.
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/member.rb b/lib/puppet/parser/functions/member.rb
index bb43a37..43d76af 100644
--- a/lib/puppet/parser/functions/member.rb
+++ b/lib/puppet/parser/functions/member.rb
@@ -7,6 +7,17 @@
 
 module Puppet::Parser::Functions
   newfunction(:member, :type => :rvalue, :doc => <<-EOS
+This function determines if a variable is a member of an array.
+
+*Examples:*
+
+    member(['a','b'], 'b')
+
+Would return: true
+
+    member(['a','b'], 'c')
+
+Would return: false
     EOS
   ) do |arguments|
 
diff --git a/lib/puppet/parser/functions/type.rb b/lib/puppet/parser/functions/type.rb
index de6087e..8d85f11 100644
--- a/lib/puppet/parser/functions/type.rb
+++ b/lib/puppet/parser/functions/type.rb
@@ -11,6 +11,7 @@ Returns the type when passed a variable. Type can be one of:
 * hash
 * float
 * integer
+* boolean
     EOS
   ) do |arguments|
 
@@ -21,7 +22,7 @@ Returns the type when passed a variable. Type can be one of:
 
     klass = value.class
 
-    if not [Array, Bignum, Fixnum, Float, Hash, String].include?(klass)
+    if not [TrueClass, FalseClass, Array, Bignum, Fixnum, Float, Hash, String].include?(klass)
       raise(Puppet::ParseError, 'type(): Unknown type')
     end
 
@@ -30,6 +31,7 @@ Returns the type when passed a variable. Type can be one of:
     # We note that Integer is the parent to Bignum and Fixnum ...
     result = case klass
       when /^(?:Big|Fix)num$/ then 'integer'
+      when /^(?:True|False)Class$/ then 'boolean'
       else klass
     end
 
-- 
cgit v1.2.3