summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorJeff McCune <jeff@puppetlabs.com>2011-12-30 11:48:21 -0800
committerJeff McCune <jeff@puppetlabs.com>2011-12-30 11:48:21 -0800
commit80c9a8feeae6203026f61215e100e95078c61a04 (patch)
treee70920f96b88bdc9e985e2439f395371d5ffe2be /lib
parent1434f3cea6f6e2a1b939d91cb5ff66338cc87d32 (diff)
parenta8d4bbd9e234ea577e27d83df95a61b374ac484b (diff)
Merge branch 'v2.1.x' into v2.2.x
* v2.1.x: (maint) Add semantic versioning info to README Docs: Clarify the use case for the anchor type Docs: Remove author emails from stdlib functions Docs: Copyedit function doc strings Docs: Correct indentation of markdown code examples Docs: Update documentation of stdlib classes Docs: Update file_line documentation Docs: Improve example in merge function
Diffstat (limited to 'lib')
-rw-r--r--lib/puppet/parser/functions/getvar.rb7
-rw-r--r--lib/puppet/parser/functions/has_key.rb17
-rw-r--r--lib/puppet/parser/functions/loadyaml.rb6
-rw-r--r--lib/puppet/parser/functions/merge.rb11
-rw-r--r--lib/puppet/parser/functions/validate_array.rb10
-rw-r--r--lib/puppet/parser/functions/validate_bool.rb13
-rw-r--r--lib/puppet/parser/functions/validate_hash.rb12
-rw-r--r--lib/puppet/parser/functions/validate_re.rb18
-rw-r--r--lib/puppet/parser/functions/validate_string.rb12
-rw-r--r--lib/puppet/type/anchor.rb27
-rw-r--r--lib/puppet/type/file_line.rb27
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