diff options
author | Jeff McCune <jeff@puppetlabs.com> | 2011-08-18 13:45:28 -0700 |
---|---|---|
committer | Jeff McCune <jeff@puppetlabs.com> | 2011-08-18 13:45:28 -0700 |
commit | bdba42dbb6328ccc5bb13f0777240fdb85e538ca (patch) | |
tree | de11ef579d7ffec6c7161945da5e84b75287d629 /lib/puppet | |
parent | ad5316f561475157e425a7fddf1365e8e89b2b9d (diff) | |
parent | 8e770b04234aacfc09c7b8ad45ffa304cb83f723 (diff) | |
download | puppet-stdlib-bdba42dbb6328ccc5bb13f0777240fdb85e538ca.tar.gz puppet-stdlib-bdba42dbb6328ccc5bb13f0777240fdb85e538ca.tar.bz2 |
Merge pull request #16 from nfagerlund/docs/v2.0.0/XXXX_function_doc_updates
Docs/v2.0.0/xxxx function doc updates
Diffstat (limited to 'lib/puppet')
-rw-r--r-- | lib/puppet/parser/functions/getvar.rb | 7 | ||||
-rw-r--r-- | lib/puppet/parser/functions/has_key.rb | 17 | ||||
-rw-r--r-- | lib/puppet/parser/functions/loadyaml.rb | 6 | ||||
-rw-r--r-- | lib/puppet/parser/functions/merge.rb | 11 | ||||
-rw-r--r-- | lib/puppet/parser/functions/validate_array.rb | 10 | ||||
-rw-r--r-- | lib/puppet/parser/functions/validate_bool.rb | 13 | ||||
-rw-r--r-- | lib/puppet/parser/functions/validate_hash.rb | 12 | ||||
-rw-r--r-- | lib/puppet/parser/functions/validate_re.rb | 18 | ||||
-rw-r--r-- | lib/puppet/parser/functions/validate_string.rb | 12 | ||||
-rw-r--r-- | lib/puppet/type/anchor.rb | 27 | ||||
-rw-r--r-- | lib/puppet/type/file_line.rb | 27 |
11 files changed, 86 insertions, 74 deletions
diff --git a/lib/puppet/parser/functions/getvar.rb b/lib/puppet/parser/functions/getvar.rb index ffd774d..1621149 100644 --- a/lib/puppet/parser/functions/getvar.rb +++ b/lib/puppet/parser/functions/getvar.rb @@ -5,11 +5,14 @@ module Puppet::Parser::Functions For example: - $foo = getvar('site::data::foo') + $foo = getvar('site::data::foo') + # Equivalent to $foo = $site::data::foo This is useful if the namespace itself is stored in a string: - $bar = getvar("${datalocation}::bar") + $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/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..10c4005 100644 --- a/lib/puppet/parser/functions/loadyaml.rb +++ b/lib/puppet/parser/functions/loadyaml.rb @@ -1,12 +1,12 @@ 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: - $myhash = loadyaml('/etc/puppet/data/myhash.yaml') + $myhash = loadyaml('/etc/puppet/data/myhash.yaml') ENDHEREDOC unless args.length == 1 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 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..62c1d88 100644 --- a/lib/puppet/parser/functions/validate_bool.rb +++ b/lib/puppet/parser/functions/validate_bool.rb @@ -1,27 +1,22 @@ 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") validate_bool("true") validate_bool($some_array) - * Jeff McCune <jeff@puppetlabs.com> - * Dan Bode <dan@puppetlabs.com> - 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 1443318..9bdd543 100644 --- a/lib/puppet/parser/functions/validate_hash.rb +++ b/lib/puppet/parser/functions/validate_hash.rb @@ -1,25 +1,21 @@ 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') $undefined = undef validate_hash($undefined) - * Jeff McCune <jeff@puppetlabs.com> - 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 583f26a..8033ca3 100644 --- a/lib/puppet/parser/functions/validate_re.rb +++ b/lib/puppet/parser/functions/validate_re.rb @@ -1,24 +1,22 @@ 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' ]) - Jeff McCune <jeff@puppetlabs.com> - ENDHEREDOC if args.length != 2 then raise Puppet::ParseError, ("validate_re(): wrong number of arguments (#{args.length}; must be 2)") 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' ]) diff --git a/lib/puppet/type/anchor.rb b/lib/puppet/type/anchor.rb index 0c28b1c..6b81732 100644 --- a/lib/puppet/type/anchor.rb +++ b/lib/puppet/type/anchor.rb @@ -2,23 +2,32 @@ Puppet::Type.newtype(:anchor) do desc <<-'ENDOFDESC' A simple resource type intended to be used as an anchor in a composite class. + In Puppet 2.6, when a class declares another class, the resources in the + interior class are not contained by the exterior class. This interacts badly + with the pattern of composing complex modules from smaller classes, as it + makes it impossible for end users to specify order relationships between the + exterior class and other modules. + + The anchor type lets you work around this. By sandwiching any interior + classes between two no-op resources that _are_ contained by the exterior + class, you can ensure that all resources in the module are contained. + class ntp { + # These classes will have the correct order relationship with each + # other. However, without anchors, they won't have any order + # relationship to Class['ntp']. class { 'ntp::package': } -> class { 'ntp::config': } -> class { 'ntp::service': } - # These two resources "anchor" the composed classes - # such that the end user may use "require" and "before" - # relationships with Class['ntp'] - anchor { 'ntp::begin': } -> class { 'ntp::package': } - class { 'ntp::service': } -> anchor { 'ntp::end': } + # These two resources "anchor" the composed classes within the ntp + # class. + anchor { 'ntp::begin': } -> Class['ntp::package'] + Class['ntp::service'] -> anchor { 'ntp::end': } } - This resource allows all of the classes in the ntp module to be contained - within the ntp class from a dependency management point of view. - This allows the end user of the ntp module to establish require and before - relationships easily: + relationships with Class['ntp']: class { 'ntp': } -> class { 'mcollective': } class { 'mcollective': } -> class { 'ntp': } diff --git a/lib/puppet/type/file_line.rb b/lib/puppet/type/file_line.rb index aacd6d9..8b45897 100644 --- a/lib/puppet/type/file_line.rb +++ b/lib/puppet/type/file_line.rb @@ -1,14 +1,25 @@ Puppet::Type.newtype(:file_line) do desc <<-EOT - Type that can append whole a line to a file if it does not already contain it. - - Example: - - file_line { 'sudo_rule': - path => '/etc/sudoers', - line => '%admin ALL=(ALL) ALL', - } + Ensures that a given line is contained within a file. The implementation + matches the full line, including whitespace at the beginning and end. If + the line is not contained in the given file, Puppet will add the line to + ensure the desired state. Multiple resources may be declared to manage + multiple lines in the same file. + + Example: + + file_line { 'sudo_rule': + path => '/etc/sudoers', + line => '%sudo ALL=(ALL) ALL', + } + file_line { 'sudo_rule_nopw': + path => '/etc/sudoers', + line => '%sudonopw ALL=(ALL) NOPASSWD: ALL', + } + + In this example, Puppet will ensure both of the specified lines are + contained in the file /etc/sudoers. EOT |