From 5d108e8007b76ce62f13c99ed1caedcc0f69c37c Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Fri, 21 Jan 2011 17:21:03 -0800 Subject: (#5944) Improve documentation of defined() function The differences in the way defined() handles different types of entities weren't well-explained. Documentation was also added for the behavior of defined(Node["somenode.domain.com"]). --- lib/puppet/parser/functions/defined.rb | 47 +++++++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 6 deletions(-) (limited to 'lib/puppet/parser') diff --git a/lib/puppet/parser/functions/defined.rb b/lib/puppet/parser/functions/defined.rb index 90632af2f..c3efc5f76 100644 --- a/lib/puppet/parser/functions/defined.rb +++ b/lib/puppet/parser/functions/defined.rb @@ -1,10 +1,45 @@ # Test whether a given class or definition is defined -Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Determine whether a given - type is defined, either as a native type or a defined type, or whether a class is defined. - This is useful for checking whether a class is defined and only including it if it is. - This function can also test whether a resource has been defined, using resource references - (e.g., `if defined(File['/tmp/myfile']) { ... }`). This function is unfortunately - dependent on the parse order of the configuration when testing whether a resource is defined.") do |vals| +Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Determine whether + a given type, class, resource, or node is defined, and return + true or false. Accepts class names, type names, resource references, and node + references. + + The `defined` function checks both native and defined types, including types + provided as plugins via modules. Types are checked using their names: + + defined(\"file\") + defined(\"customtype\") + + Classes are also checked using their names: + + defined(\"foo\") + defined(\"foo::bar\") + + Unlike classes and types, resource definitions are checked using resource + references, e.g. `defined( File['/tmp/myfile'] )`. Checking whether a given + resource defined is, unfortunately, dependent on the parse order of the + configuration, and the following code will not work: + + if defined(File['/tmp/foo']) { + notify(\"This configuration includes the /tmp/foo file.\") + } + file {\"/tmp/foo\": + ensure => present, + } + + However, this order requirement refers to parse order only, and ordering of + resources in the configuration graph (e.g. with `begin` or `require`) does not + affect the behavior of `defined`. + + You can also use `defined` to check whether a node is defined using syntax + resembling a resource reference, like `Node[\"testnode.domain.com\"]`. This usage + is not necessarily recommended, and is included here only in the spirit of + completeness. Checking for node definitions behaves differently from the other + uses of `defined`: it will only return true if a definition for the specified + node (the name of which must match exactly) exists in the manifest **AND** the + specified node matches the node whose configuration is being compiled (either + directly or through node inheritance). The `define` function cannot be used to + introspect information returned by an external node classifier. ") do |vals| result = false vals = [vals] unless vals.is_a?(Array) vals.each do |val| -- cgit From 2b9f6535d46eecd60d8997e93dd2b7533b9e5e71 Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Tue, 25 Jan 2011 17:09:25 -0800 Subject: (#5944) Further edits of inline defined() documentation. Fixing use of define/declare; editing for clarity. --- lib/puppet/parser/functions/defined.rb | 55 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 25 deletions(-) (limited to 'lib/puppet/parser') diff --git a/lib/puppet/parser/functions/defined.rb b/lib/puppet/parser/functions/defined.rb index c3efc5f76..deb57a616 100644 --- a/lib/puppet/parser/functions/defined.rb +++ b/lib/puppet/parser/functions/defined.rb @@ -1,45 +1,50 @@ # Test whether a given class or definition is defined Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Determine whether - a given type, class, resource, or node is defined, and return - true or false. Accepts class names, type names, resource references, and node - references. - + a given type or class is defined. This function can also determine whether a + specific resource has been declared. Returns true or false. Accepts class names, + type names, resource references, and node references. + The `defined` function checks both native and defined types, including types - provided as plugins via modules. Types are checked using their names: - + provided as plugins via modules. Types and classes are both checked using their names: + defined(\"file\") defined(\"customtype\") - - Classes are also checked using their names: - defined(\"foo\") defined(\"foo::bar\") - - Unlike classes and types, resource definitions are checked using resource - references, e.g. `defined( File['/tmp/myfile'] )`. Checking whether a given - resource defined is, unfortunately, dependent on the parse order of the - configuration, and the following code will not work: - + + Resource declarations are checked using resource references, e.g. + `defined( File['/tmp/myfile'] )`. Checking whether a given resource + has been declared is, unfortunately, dependent on the parse order of + the configuration, and the following code will not work: + if defined(File['/tmp/foo']) { notify(\"This configuration includes the /tmp/foo file.\") } file {\"/tmp/foo\": ensure => present, } - + However, this order requirement refers to parse order only, and ordering of - resources in the configuration graph (e.g. with `begin` or `require`) does not + resources in the configuration graph (e.g. with `before` or `require`) does not affect the behavior of `defined`. - - You can also use `defined` to check whether a node is defined using syntax + + You can also use `defined` to check whether a node is declared using syntax resembling a resource reference, like `Node[\"testnode.domain.com\"]`. This usage is not necessarily recommended, and is included here only in the spirit of - completeness. Checking for node definitions behaves differently from the other - uses of `defined`: it will only return true if a definition for the specified - node (the name of which must match exactly) exists in the manifest **AND** the - specified node matches the node whose configuration is being compiled (either - directly or through node inheritance). The `define` function cannot be used to - introspect information returned by an external node classifier. ") do |vals| + completeness. Note that: + + * Only the node whose configuration is being compiled is considered declared; + the `define` function will not return information about definitions not currently + being used. + * Node definitions inherited by the current node are considered declared; + however, the default node is never considered declared. + * A node is not considered declared simply by virtue of receiving a + configuration; it must have matched a node definition in the manifest. + * The name used in the node reference must match the name used in the node + definition, even if this is not the node's actual certname. + * Regular expression node definitions cannot be checked for declaration using + `define`, nor can `define` be used to introspect information returned by an + external node classifier.") do |vals| result = false vals = [vals] unless vals.is_a?(Array) vals.each do |val| -- cgit From 86a2a0031fdad032003d053244a3baa04c8f2b81 Mon Sep 17 00:00:00 2001 From: nfagerlund Date: Tue, 25 Jan 2011 17:50:17 -0800 Subject: (#5944) Remove documentation of define() when used on nodes, as it is not a supported use of this function. Final patch in this series reviewed by Dan Bode. --- lib/puppet/parser/functions/defined.rb | 24 +++--------------------- 1 file changed, 3 insertions(+), 21 deletions(-) (limited to 'lib/puppet/parser') diff --git a/lib/puppet/parser/functions/defined.rb b/lib/puppet/parser/functions/defined.rb index deb57a616..2aeaa9ba0 100644 --- a/lib/puppet/parser/functions/defined.rb +++ b/lib/puppet/parser/functions/defined.rb @@ -1,8 +1,8 @@ # Test whether a given class or definition is defined Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Determine whether - a given type or class is defined. This function can also determine whether a + a given class or resource type is defined. This function can also determine whether a specific resource has been declared. Returns true or false. Accepts class names, - type names, resource references, and node references. + type names, and resource references. The `defined` function checks both native and defined types, including types provided as plugins via modules. Types and classes are both checked using their names: @@ -26,25 +26,7 @@ Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Dete However, this order requirement refers to parse order only, and ordering of resources in the configuration graph (e.g. with `before` or `require`) does not - affect the behavior of `defined`. - - You can also use `defined` to check whether a node is declared using syntax - resembling a resource reference, like `Node[\"testnode.domain.com\"]`. This usage - is not necessarily recommended, and is included here only in the spirit of - completeness. Note that: - - * Only the node whose configuration is being compiled is considered declared; - the `define` function will not return information about definitions not currently - being used. - * Node definitions inherited by the current node are considered declared; - however, the default node is never considered declared. - * A node is not considered declared simply by virtue of receiving a - configuration; it must have matched a node definition in the manifest. - * The name used in the node reference must match the name used in the node - definition, even if this is not the node's actual certname. - * Regular expression node definitions cannot be checked for declaration using - `define`, nor can `define` be used to introspect information returned by an - external node classifier.") do |vals| + affect the behavior of `defined`.") do |vals| result = false vals = [vals] unless vals.is_a?(Array) vals.each do |val| -- cgit