From 27c3b644b00bb2eca0cb819c55d7d348a1caa01b Mon Sep 17 00:00:00 2001 From: Jeff McCune Date: Tue, 16 Aug 2011 15:57:47 -0700 Subject: Docs: Improve example in merge function This commit replaces the example in the merge function with a much clearer one. It also mentions that the rightmost value wins in the event of duplicated hash keys. --- lib/puppet/parser/functions/merge.rb | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'lib/puppet/parser/functions') diff --git a/lib/puppet/parser/functions/merge.rb b/lib/puppet/parser/functions/merge.rb index d2dc0f9..6ec085e 100644 --- a/lib/puppet/parser/functions/merge.rb +++ b/lib/puppet/parser/functions/merge.rb @@ -4,10 +4,13 @@ module Puppet::Parser::Functions For example: - $hash1 = {'one' => 1, 'two', => 2} - $hash1 = {'two' => 2, 'three', => 2} - $merged_hash = merge($hash1, $hash2) - # merged_hash = {'one' => 1, 'two' => 2, 'three' => 2} + $hash1 = {'one' => 1, 'two', => 2} + $hash2 = {'two' => 'dos', 'three', => 'tres'} + $merged_hash = merge($hash1, $hash2) + # The resulting hash is equivalent to: + # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} + + When there is a duplicate key, the key in the rightmost hash will "win." ENDHEREDOC -- cgit v1.2.3 From 400b91ab02428c6a51886f31cbb12b9d4852b6e9 Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Wed, 17 Aug 2011 15:20:26 -0700 Subject: Docs: Correct indentation of markdown code examples Code examples in several function doc strings were only indented by two spaces, which would not result in proper display when rendered as HTML. This commit corrects the indentation to four spaces. --- lib/puppet/parser/functions/getvar.rb | 4 ++-- lib/puppet/parser/functions/has_key.rb | 17 +++++++++-------- lib/puppet/parser/functions/loadyaml.rb | 2 +- 3 files changed, 12 insertions(+), 11 deletions(-) (limited to 'lib/puppet/parser/functions') diff --git a/lib/puppet/parser/functions/getvar.rb b/lib/puppet/parser/functions/getvar.rb index ffd774d..3ca179f 100644 --- a/lib/puppet/parser/functions/getvar.rb +++ b/lib/puppet/parser/functions/getvar.rb @@ -5,11 +5,11 @@ module Puppet::Parser::Functions For example: - $foo = getvar('site::data::foo') + $foo = getvar('site::data::foo') This is useful if the namespace itself is stored in a string: - $bar = getvar("${datalocation}::bar") + $bar = getvar("${datalocation}::bar") ENDHEREDOC unless args.length == 1 diff --git a/lib/puppet/parser/functions/has_key.rb b/lib/puppet/parser/functions/has_key.rb index 9c1c4c3..4657cc2 100644 --- a/lib/puppet/parser/functions/has_key.rb +++ b/lib/puppet/parser/functions/has_key.rb @@ -1,16 +1,17 @@ module Puppet::Parser::Functions newfunction(:has_key, :type => :rvalue, :doc => <<-'ENDHEREDOC') do |args| - determine if a hash has a certain key value. + Determine if a hash has a certain key value. Example: - $my_hash = {'key_one' => 'value_one'} - if has_key($my_hash, 'key_two') { - notice('we will not reach here') - } - if has_key($my_hash, 'key_one') { - notice('this will be printed') - } + + $my_hash = {'key_one' => 'value_one'} + if has_key($my_hash, 'key_two') { + notice('we will not reach here') + } + if has_key($my_hash, 'key_one') { + notice('this will be printed') + } ENDHEREDOC diff --git a/lib/puppet/parser/functions/loadyaml.rb b/lib/puppet/parser/functions/loadyaml.rb index 0f16f69..4ccc95b 100644 --- a/lib/puppet/parser/functions/loadyaml.rb +++ b/lib/puppet/parser/functions/loadyaml.rb @@ -6,7 +6,7 @@ module Puppet::Parser::Functions For example: - $myhash = loadyaml('/etc/puppet/data/myhash.yaml') + $myhash = loadyaml('/etc/puppet/data/myhash.yaml') ENDHEREDOC unless args.length == 1 -- cgit v1.2.3 From 4b5dfcc733cf5c56095313fcb16e155886ac9b4d Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Wed, 17 Aug 2011 15:53:27 -0700 Subject: Docs: Copyedit function doc strings This commit makes several minor consistency and wording edits to the doc strings of the stdlib functions. --- lib/puppet/parser/functions/getvar.rb | 3 +++ lib/puppet/parser/functions/loadyaml.rb | 4 ++-- lib/puppet/parser/functions/validate_array.rb | 10 ++++------ lib/puppet/parser/functions/validate_bool.rb | 10 ++++------ lib/puppet/parser/functions/validate_hash.rb | 10 ++++------ lib/puppet/parser/functions/validate_re.rb | 16 ++++++++-------- lib/puppet/parser/functions/validate_string.rb | 12 +++++------- 7 files changed, 30 insertions(+), 35 deletions(-) (limited to 'lib/puppet/parser/functions') diff --git a/lib/puppet/parser/functions/getvar.rb b/lib/puppet/parser/functions/getvar.rb index 3ca179f..1621149 100644 --- a/lib/puppet/parser/functions/getvar.rb +++ b/lib/puppet/parser/functions/getvar.rb @@ -6,10 +6,13 @@ module Puppet::Parser::Functions For example: $foo = getvar('site::data::foo') + # Equivalent to $foo = $site::data::foo This is useful if the namespace itself is stored in a string: + $datalocation = 'site::data' $bar = getvar("${datalocation}::bar") + # Equivalent to $bar = $site::data::bar ENDHEREDOC unless args.length == 1 diff --git a/lib/puppet/parser/functions/loadyaml.rb b/lib/puppet/parser/functions/loadyaml.rb index 4ccc95b..10c4005 100644 --- a/lib/puppet/parser/functions/loadyaml.rb +++ b/lib/puppet/parser/functions/loadyaml.rb @@ -1,8 +1,8 @@ module Puppet::Parser::Functions newfunction(:loadyaml, :type => :rvalue, :doc => <<-'ENDHEREDOC') do |args| - Load a YAML file and return the data if it contains an Array, String, or Hash - as a Puppet variable. + Load a YAML file containing an array, string, or hash, and return the data + in the corresponding native data type. For example: diff --git a/lib/puppet/parser/functions/validate_array.rb b/lib/puppet/parser/functions/validate_array.rb index a7a7165..34b5118 100644 --- a/lib/puppet/parser/functions/validate_array.rb +++ b/lib/puppet/parser/functions/validate_array.rb @@ -1,17 +1,15 @@ module Puppet::Parser::Functions newfunction(:validate_array, :doc => <<-'ENDHEREDOC') do |args| - Validate all passed values are a Array data structure - value does not pass the check. + Validate that all passed values are array data structures. Abort catalog + compilation if any value fails this check. - Example: - - These values validate + The following values will pass: $my_array = [ 'one', 'two' ] validate_array($my_array) - These values do NOT validate + The following values will fail, causing compilation to abort: validate_array(true) validate_array('some_string') diff --git a/lib/puppet/parser/functions/validate_bool.rb b/lib/puppet/parser/functions/validate_bool.rb index 49e6378..82a45fb 100644 --- a/lib/puppet/parser/functions/validate_bool.rb +++ b/lib/puppet/parser/functions/validate_bool.rb @@ -1,18 +1,16 @@ module Puppet::Parser::Functions newfunction(:validate_bool, :doc => <<-'ENDHEREDOC') do |args| - Validate all passed values are true or false. Abort catalog compilation if the - value does not pass the check. + Validate that all passed values are either true or false. Abort catalog + compilation if any value fails this check. - Example: - - These booleans validate + The following values will pass: $iamtrue = true validate_bool(true) validate_bool(true, true, false, $iamtrue) - These strings do NOT validate and will abort catalog compilation + The following values will fail, causing compilation to abort: $some_array = [ true ] validate_bool("false") diff --git a/lib/puppet/parser/functions/validate_hash.rb b/lib/puppet/parser/functions/validate_hash.rb index 1443318..1b1c854 100644 --- a/lib/puppet/parser/functions/validate_hash.rb +++ b/lib/puppet/parser/functions/validate_hash.rb @@ -1,17 +1,15 @@ module Puppet::Parser::Functions newfunction(:validate_hash, :doc => <<-'ENDHEREDOC') do |args| - Validate all passed values are a Hash data structure - value does not pass the check. + Validate that all passed values are hash data structures. Abort catalog + compilation if any value fails this check. - Example: - - These values validate + The following values will pass: $my_hash = { 'one' => 'two' } validate_hash($my_hash) - These values do NOT validate + The following values will fail, causing compilation to abort: validate_hash(true) validate_hash('some_string') diff --git a/lib/puppet/parser/functions/validate_re.rb b/lib/puppet/parser/functions/validate_re.rb index 583f26a..9e61ef5 100644 --- a/lib/puppet/parser/functions/validate_re.rb +++ b/lib/puppet/parser/functions/validate_re.rb @@ -1,19 +1,19 @@ module Puppet::Parser::Functions newfunction(:validate_re, :doc => <<-'ENDHEREDOC') do |args| - Perform simple validation of a string against a regular expression. The second - argument of the function should be a string regular expression (without the //'s) - or an array of regular expressions. If none of the regular expressions in the array - match the string passed in, then an exception will be raised. + Perform simple validation of a string against one or more regular + expressions. The first argument of this function should be a string to + test, and the second argument should be a stringified regular expression + (without the // delimiters) or an array of regular expressions. If none + of the regular expressions match the string passed in, compilation will + abort with a parse error. - Example: - - These strings validate against the regular expressions + The following strings will validate against the regular expressions: validate_re('one', '^one$') validate_re('one', [ '^one', '^two' ]) - These strings do NOT validate + The following strings will fail to validate, causing compilation to abort: validate_re('one', [ '^two', '^three' ]) diff --git a/lib/puppet/parser/functions/validate_string.rb b/lib/puppet/parser/functions/validate_string.rb index d0e1376..e667794 100644 --- a/lib/puppet/parser/functions/validate_string.rb +++ b/lib/puppet/parser/functions/validate_string.rb @@ -1,17 +1,15 @@ module Puppet::Parser::Functions newfunction(:validate_string, :doc => <<-'ENDHEREDOC') do |args| - Validate all passed values are a string data structure - value does not pass the check. + Validate that all passed values are string data structures. Abort catalog + compilation if any value fails this check. - Example: - - These values validate + The following values will pass: $my_string = "one two" - validate_string($my_string) + validate_string($my_string, 'three') - These values do NOT validate + The following values will fail, causing compilation to abort: validate_string(true) validate_string([ 'some', 'array' ]) -- cgit v1.2.3 From 9e87fd14571ba3a75789417e7aa4df05d4a7345c Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Wed, 17 Aug 2011 15:55:07 -0700 Subject: Docs: Remove author emails from stdlib functions Author email addresses were included in the doc strings for some (but not all) stdlib functions. This commit removes them in the interest of consistency. --- lib/puppet/parser/functions/validate_bool.rb | 3 --- lib/puppet/parser/functions/validate_hash.rb | 2 -- lib/puppet/parser/functions/validate_re.rb | 2 -- 3 files changed, 7 deletions(-) (limited to 'lib/puppet/parser/functions') diff --git a/lib/puppet/parser/functions/validate_bool.rb b/lib/puppet/parser/functions/validate_bool.rb index 82a45fb..62c1d88 100644 --- a/lib/puppet/parser/functions/validate_bool.rb +++ b/lib/puppet/parser/functions/validate_bool.rb @@ -17,9 +17,6 @@ module Puppet::Parser::Functions validate_bool("true") validate_bool($some_array) - * Jeff McCune - * Dan Bode - ENDHEREDOC unless args.length > 0 then diff --git a/lib/puppet/parser/functions/validate_hash.rb b/lib/puppet/parser/functions/validate_hash.rb index 1b1c854..9bdd543 100644 --- a/lib/puppet/parser/functions/validate_hash.rb +++ b/lib/puppet/parser/functions/validate_hash.rb @@ -16,8 +16,6 @@ module Puppet::Parser::Functions $undefined = undef validate_hash($undefined) - * Jeff McCune - ENDHEREDOC unless args.length > 0 then diff --git a/lib/puppet/parser/functions/validate_re.rb b/lib/puppet/parser/functions/validate_re.rb index 9e61ef5..8033ca3 100644 --- a/lib/puppet/parser/functions/validate_re.rb +++ b/lib/puppet/parser/functions/validate_re.rb @@ -17,8 +17,6 @@ module Puppet::Parser::Functions validate_re('one', [ '^two', '^three' ]) - Jeff McCune - ENDHEREDOC if args.length != 2 then raise Puppet::ParseError, ("validate_re(): wrong number of arguments (#{args.length}; must be 2)") -- cgit v1.2.3