improve documentation and function naming

4 files changed, 55 insertions, 7 deletions

diff --git a/plugins/puppet/parser/functions/basename.rb b/plugins/puppet/parser/functions/basename.rb
index 14f0ca0..226d6e5 100644
--- a/plugins/puppet/parser/functions/basename.rb
+++ b/plugins/puppet/parser/functions/basename.rb
@@ -1,7 +1,16 @@
-# get the basename of the given filename
+# basename(string) : string
+# basename(string[]) : string[]
+#
+# Returns the last component of the filename given as argument, which must be
+# formed using forward slashes (``/..) regardless of the separator used on the
+# local file system.
 module Puppet::Parser::Functions
 	newfunction(:basename, :type => :rvalue) do |args|
-		File.basename(args[0])
+		if args[0].is_a?(Array)
+			args.collect do |a| File.basename(a) end
+		else
+			File.basename(args[0])
+		end
 	end
 end
 
diff --git a/plugins/puppet/parser/functions/dirname.rb b/plugins/puppet/parser/functions/dirname.rb
index 3f784ac..44b4a00 100644
--- a/plugins/puppet/parser/functions/dirname.rb
+++ b/plugins/puppet/parser/functions/dirname.rb
@@ -1,7 +1,16 @@
-# get the directory corresponding to this filename
+# dirname(string) : string
+# dirname(string[]) : string[]
+#
+# Returns all components of the filename given as argument except the last
+# one. The filename must be formed using forward slashes (``/..) regardless of
+# the separator used on the local file system.
 module Puppet::Parser::Functions
 	newfunction(:dirname, :type => :rvalue) do |args|
-		File.dirname(args[0])
+		if args[0].is_a?(Array)
+			args.collect do |a| File.dirname(a) end
+		else
+			File.dirname(args[0])
+		end
 	end
 end
 
diff --git a/plugins/puppet/parser/functions/split.rb b/plugins/puppet/parser/functions/split.rb
index d08a40b..5237c92 100644
--- a/plugins/puppet/parser/functions/split.rb
+++ b/plugins/puppet/parser/functions/split.rb
@@ -1,7 +1,17 @@
-# generic split call
+# split($string, $delimiter) : $string
+# split($string[], $delimiter) : $string[][]
+#
+# Split the first argument(s) on every $delimiter. $delimiter is interpreted as
+# Ruby regular expression.
+#
+# For long-term portability it is recommended to refrain from using Ruby's
+# extended RE features.
 module Puppet::Parser::Functions
 	newfunction(:split, :type => :rvalue) do |args|
-		args[0].split(/#{args[1]}/)
+		if args[0].is_a?(Array)
+			args.collect do |a| a.split(/#{args[1]}/) end
+		else
+			args[0].split(/#{args[1]}/)
+		end
 	end
 end
-
diff --git a/plugins/puppet/parser/functions/substitute.rb b/plugins/puppet/parser/functions/substitute.rb
new file mode 100644
index 0000000..4c97def
--- /dev/null
+++ b/plugins/puppet/parser/functions/substitute.rb
@@ -0,0 +1,20 @@
+# subsititute($string, $regex, $replacement) : $string
+# subsititute($string[], $regex, $replacement) : $string[]
+#
+# Replace all ocurrences of $regex in $string by $replacement.
+# $regex is interpreted as Ruby regular expression.
+#
+# For long-term portability it is recommended to refrain from using Ruby's
+# extended RE features.
+module Puppet::Parser::Functions
+	newfunction(:substitute, :type => :rvalue) do |args|
+		if args[0].is_a?(Array)
+			args[0].collect do |val|
+				val.gsub(/#{args[1]}/, args[2])
+			end
+		else
+			args[0].gsub(/#{args[1]}/, args[2])
+		end
+	end
+end
+