aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Schmitt <david@dasz.at>2009-06-09 17:51:10 +0200
committerDavid Schmitt <david@dasz.at>2009-06-09 17:51:10 +0200
commitde7690c4e76ddd7c1f01d81fe92c75771da47c51 (patch)
tree1cba3866aa6db7beb2ba59bddefb508b5d0ddbb7
parentc65920d6b8d017c951838c72f4bbcb75d5b27234 (diff)
downloadpuppet-common-de7690c4e76ddd7c1f01d81fe92c75771da47c51.tar.gz
puppet-common-de7690c4e76ddd7c1f01d81fe92c75771da47c51.tar.bz2
RDoc-ify documentation
See http://club.black.co.at/david/puppet/doc/ for a current version of the RDoc output.
-rw-r--r--README17
-rw-r--r--manifests/classes/lsb_release.pp2
-rw-r--r--manifests/defines/concatenated_file.pp6
-rw-r--r--manifests/defines/config_file.pp27
-rw-r--r--manifests/defines/line.pp40
-rw-r--r--manifests/defines/module_dir.pp11
-rw-r--r--manifests/defines/module_file.pp10
-rw-r--r--manifests/defines/replace.pp15
-rw-r--r--plugins/puppet/parser/functions/basename.rb12
-rw-r--r--plugins/puppet/parser/functions/dirname.rb10
-rw-r--r--plugins/puppet/parser/functions/gsub.rb14
-rw-r--r--plugins/puppet/parser/functions/prefix_with.rb14
-rw-r--r--plugins/puppet/parser/functions/re_escape.rb2
-rw-r--r--plugins/puppet/parser/functions/split.rb12
14 files changed, 117 insertions, 75 deletions
diff --git a/README b/README
index d34d11f..45b0106 100644
--- a/README
+++ b/README
@@ -1,17 +1,22 @@
-The common module installs various functions that are required by other modules. This
-module should be installed before any of the other module.
+The common module installs various functions that are required by other
+modules. This module should be installed before any of the other module.
To use this module, follow these directions:
-1. Your modules directory will need all the files included in this repository placed
- under a directory called "common"
+1. Your modules directory will need all the files included in this
+ repository placed under a directory called "common"
2. Add the following line to manifests/site.pp:
- import "modules.pp"
+ import "modules.pp"
3. Add the following line to manifests/modules.pp:
- import "common"
+ import "common"
+
+
+Author:: David Schmitt (mailto:david@dasz.at)
+Copyright:: Copyright (c) 2007-2009 dasz.at OG
+License:: 3-clause BSD
diff --git a/manifests/classes/lsb_release.pp b/manifests/classes/lsb_release.pp
index bf9baeb..5745072 100644
--- a/manifests/classes/lsb_release.pp
+++ b/manifests/classes/lsb_release.pp
@@ -43,7 +43,7 @@ class assert_lsbdistcodename {
}
-# To fail the complete compilation, include this class
+# To fail the complete compilation on a missing $lsbdistcodename, include this class
class require_lsbdistcodename inherits assert_lsbdistcodename {
exec { "false # require_lsbdistcodename": require => Exec[require_lsbdistcodename], loglevel => err }
}
diff --git a/manifests/defines/concatenated_file.pp b/manifests/defines/concatenated_file.pp
index c7e1f21..8ae855c 100644
--- a/manifests/defines/concatenated_file.pp
+++ b/manifests/defines/concatenated_file.pp
@@ -26,9 +26,9 @@ module_dir { "common/cf": }
# Exec["concat_${name}"] if you want to force an update.
#
# Usage:
-# concatenated_file { "/etc/some.conf":
-# dir => "/etc/some.conf.d",
-# }
+# concatenated_file { "/etc/some.conf":
+# dir => "/etc/some.conf.d",
+# }
define concatenated_file (
# where the snippets are located
$dir = '',
diff --git a/manifests/defines/config_file.pp b/manifests/defines/config_file.pp
index 8d93e0a..59208ac 100644
--- a/manifests/defines/config_file.pp
+++ b/manifests/defines/config_file.pp
@@ -5,30 +5,31 @@
# A simple wrapper to give all configuration files common defaults.
#
# Usage:
-# config_file { filename:
-# content => "....\n",
-# }
+# config_file { filename:
+# content => "....\n",
+# }
#
# Examples:
#
# To create the file /etc/vservers/${vs_name}/context with specific
# content:
#
-# config_file { "/etc/vservers/${vs_name}/context":
-# content => "${context}\n",
-# notify => Exec["vs_restart_${vs_name}"],
-# require => Exec["vs_create_${vs_name}"];
+# config_file {
+# "/etc/vservers/${vs_name}/context":
+# content => "${context}\n",
+# notify => Exec["vs_restart_${vs_name}"],
+# require => Exec["vs_create_${vs_name}"];
# }
#
# To create the file /etc/apache2/sites-available/munin-stats with the
# content pulled from a template:
#
-# config_file { "/etc/apache2/sites-available/munin-stats":
-# content => template("apache/munin-stats"),
-# require => Package["apache2"],
-# notify => Exec["reload-apache2"]
-# }
-
+# config_file {
+# "/etc/apache2/sites-available/munin-stats":
+# content => template("apache/munin-stats"),
+# require => Package["apache2"],
+# notify => Exec["reload-apache2"];
+# }
define config_file (
$content = '',
$source = '',
diff --git a/manifests/defines/line.pp b/manifests/defines/line.pp
index fe2124d..be5ec31 100644
--- a/manifests/defines/line.pp
+++ b/manifests/defines/line.pp
@@ -2,36 +2,38 @@
# Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
# See LICENSE for the full license granted to you.
-# Ensures that a specific line is present or absent in a file. This can be very
-# brittle, since even small changes can throw this off.
+# Ensures that a specific line is present or absent in a file. This can
+# be very brittle, since even small changes can throw this off.
#
# If the line is not present yet, it will be appended to the file.
#
# The name of the define is not used. Just keep it (globally) unique and
# descriptive.
#
-# Use this only for very trivial stuff.
+# Use this only for very trivial stuff. Usually replacing the whole file
+# is a more stable solution with less maintenance headaches afterwards.
#
# Usage:
-# line { description:
-# file => "filename",
-# line => "content",
-# ensure => {absent,*present*}
-# }
+# line {
+# description:
+# file => "filename",
+# line => "content",
+# ensure => {absent,*present*}
+# }
#
# Example:
-# The following ensures that the line "allow ^$munin_host$" exists
-# in /etc/munin/munin-node.conf, and if there are any changes notify the service for
-# a restart
-#
-# line { allow_munin_host:
-# file => "/etc/munin/munin-node.conf",
-# line => "allow ^$munin_host$",
-# ensure => present,
-# notify => Service[munin-node],
-# require => Package[munin-node],
-# }
+# The following ensures that the line "allow ^$munin_host$" exists in
+# /etc/munin/munin-node.conf, and if there are any changes notify the
+# service for a restart
#
+# line {
+# allow_munin_host:
+# file => "/etc/munin/munin-node.conf",
+# line => "allow ^$munin_host$",
+# ensure => present,
+# notify => Service[munin-node],
+# require => Package[munin-node];
+# }
define line(
$file,
$line,
diff --git a/manifests/defines/module_dir.pp b/manifests/defines/module_dir.pp
index 712e611..5b2d340 100644
--- a/manifests/defines/module_dir.pp
+++ b/manifests/defines/module_dir.pp
@@ -4,21 +4,17 @@
# Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
# See LICENSE for the full license granted to you.
-# Use this variable to reference the base path. Thus you are safe from any
-# changes.
-$module_dir_path = '/var/lib/puppet/modules'
-
# A module_dir is a storage place for all the stuff a module might want to
# store. According to the FHS, this should go to /var/lib. Since this is a part
# of puppet, the full path is /var/lib/puppet/modules/${name}. Every module
# should # prefix its module_dirs with its name.
#
# By default, the module_dir is loaded from "puppet:///${name}/module_dir". If
-# that doesn't exist an empty directory is taken as template. The directory is
+# that doesn't exist an empty directory is taken as source. The directory is
# purged so that modules do not have to worry about removing cruft.
#
# Usage:
-# module_dir { ["common", "common/dir1", "common/dir2" ]: }
+# module_dir { ["common", "common/dir1", "common/dir2" ]: }
define module_dir (
$mode = 0644,
$owner = root,
@@ -41,3 +37,6 @@ define module_dir (
}
}
+# Use this variable to reference the base path. Thus you are safe from any
+# changes.
+$module_dir_path = '/var/lib/puppet/modules'
diff --git a/manifests/defines/module_file.pp b/manifests/defines/module_file.pp
index 6082eff..9074589 100644
--- a/manifests/defines/module_file.pp
+++ b/manifests/defines/module_file.pp
@@ -4,12 +4,12 @@
# Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
# See LICENSE for the full license granted to you.
+# Put a file into module-local storage.
+#
# Usage:
-# module_file { "module/file":
-# source => "puppet://..",
-# mode => 644, # default
-# owner => root, # default
-# group => root, # default
+# module_file {
+# "module/file":
+# source => "puppet://..",
# }
define module_file (
$source,
diff --git a/manifests/defines/replace.pp b/manifests/defines/replace.pp
index a7a59b8..c9a98bd 100644
--- a/manifests/defines/replace.pp
+++ b/manifests/defines/replace.pp
@@ -8,6 +8,9 @@
# creating a template is often better than this hack.
#
# This define uses perl regular expressions.
+#
+# Use this only for very trivial stuff. Usually replacing the whole file is a
+# more stable solution with less maintenance headaches afterwards.
#
# Usage:
#
@@ -20,12 +23,12 @@
# To replace the current port in /etc/munin/munin-node.conf
# with a new port, but only disturbing the file when needed:
#
-# replace { set_munin_node_port:
-# file => "/etc/munin/munin-node.conf",
-# pattern => "^port (?!$port)[0-9]*",
-# replacement => "port $port"
-# }
-
+# replace {
+# set_munin_node_port:
+# file => "/etc/munin/munin-node.conf",
+# pattern => "^port (?!$port)[0-9]*",
+# replacement => "port $port"
+# }
define replace($file, $pattern, $replacement) {
$pattern_no_slashes = regsubst($pattern, '/', '\\/', 'G', 'U')
$replacement_no_slashes = regsubst($replacement, '/', '\\/', 'G', 'U')
diff --git a/plugins/puppet/parser/functions/basename.rb b/plugins/puppet/parser/functions/basename.rb
index 226d6e5..dc72537 100644
--- a/plugins/puppet/parser/functions/basename.rb
+++ b/plugins/puppet/parser/functions/basename.rb
@@ -1,9 +1,15 @@
-# basename(string) : string
-# basename(string[]) : string[]
+# This function has two modes of operation:
+#
+# 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
+# formed using forward slashes ("/") regardless of the separator used on the
# local file system.
+#
+# basename(string[]) : string[]
+#
+# Returns an array of strings with the basename of each item from the argument.
+#
module Puppet::Parser::Functions
newfunction(:basename, :type => :rvalue) do |args|
if args[0].is_a?(Array)
diff --git a/plugins/puppet/parser/functions/dirname.rb b/plugins/puppet/parser/functions/dirname.rb
index 44b4a00..ea0d50b 100644
--- a/plugins/puppet/parser/functions/dirname.rb
+++ b/plugins/puppet/parser/functions/dirname.rb
@@ -1,9 +1,15 @@
-# dirname(string) : string
-# dirname(string[]) : string[]
+# This function has two modes of operation:
+#
+# 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.
+#
+# dirname(string[]) : string[]
+#
+# Returns an array of strings with the basename of each item from the argument.
+#
module Puppet::Parser::Functions
newfunction(:dirname, :type => :rvalue) do |args|
if args[0].is_a?(Array)
diff --git a/plugins/puppet/parser/functions/gsub.rb b/plugins/puppet/parser/functions/gsub.rb
index e2410ff..27e6192 100644
--- a/plugins/puppet/parser/functions/gsub.rb
+++ b/plugins/puppet/parser/functions/gsub.rb
@@ -1,9 +1,13 @@
+#
+# A thin wrapper around the ruby gsub function.
+#
+# gsub($string, $pattern, $replacement)
+#
+# will replace all occurrences of $pattern in $string with $replacement.
+# $string can be either a single value or an array. In the latter case, each
+# element of the array will be processed in turn.
+#
module Puppet::Parser::Functions
- # thin wrapper around the ruby gsub function
- # gsub($string, $pattern, $replacement) will replace all occurrences of
- # $pattern in $string with $replacement. $string can be either a singel
- # value or an array. In the latter case, each element of the array will
- # be processed in turn.
newfunction(:gsub, :type => :rvalue) do |args|
if args[0].is_a?(Array)
args[0].collect do |val|
diff --git a/plugins/puppet/parser/functions/prefix_with.rb b/plugins/puppet/parser/functions/prefix_with.rb
index 6e64a4a..5a12986 100644
--- a/plugins/puppet/parser/functions/prefix_with.rb
+++ b/plugins/puppet/parser/functions/prefix_with.rb
@@ -1,5 +1,15 @@
-# prefix arguments 2..n with first argument
-
+# Prefixes arguments 2..n with first argument.
+#
+# prefix_with(string prefix, string[] arguments) : string[]
+#
+# Example:
+#
+# prefix_with("php-", [ "blah", "foo" ])
+#
+# will result in this array:
+#
+# [ "php-blah", "php-foo" ]
+#
module Puppet::Parser::Functions
newfunction(:prefix_with, :type => :rvalue) do |args|
prefix = args.shift
diff --git a/plugins/puppet/parser/functions/re_escape.rb b/plugins/puppet/parser/functions/re_escape.rb
index 6e5904b..7bee90a 100644
--- a/plugins/puppet/parser/functions/re_escape.rb
+++ b/plugins/puppet/parser/functions/re_escape.rb
@@ -1,4 +1,4 @@
-# apply regexp escaping to a string
+# apply ruby regexp escaping to a string
module Puppet::Parser::Functions
newfunction(:re_escape, :type => :rvalue) do |args|
Regexp.escape(args[0])
diff --git a/plugins/puppet/parser/functions/split.rb b/plugins/puppet/parser/functions/split.rb
index 5237c92..bffecc1 100644
--- a/plugins/puppet/parser/functions/split.rb
+++ b/plugins/puppet/parser/functions/split.rb
@@ -1,9 +1,15 @@
-# split($string, $delimiter) : $string
-# split($string[], $delimiter) : $string[][]
+# This function has two modes of operation:
#
-# Split the first argument(s) on every $delimiter. $delimiter is interpreted as
+# split($string, $delimiter) : $string
+#
+# Split the first argument on every $delimiter. $delimiter is interpreted as
# Ruby regular expression.
#
+# split($string[], $delimiter) : $string[][]
+#
+# Returns an array of split results with the result of applying split to each
+# item from the first argument.
+#
# For long-term portability it is recommended to refrain from using Ruby's
# extended RE features.
module Puppet::Parser::Functions