From de7690c4e76ddd7c1f01d81fe92c75771da47c51 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Tue, 9 Jun 2009 17:51:10 +0200 Subject: RDoc-ify documentation See http://club.black.co.at/david/puppet/doc/ for a current version of the RDoc output. --- README | 17 +++++++---- manifests/classes/lsb_release.pp | 2 +- manifests/defines/concatenated_file.pp | 6 ++-- manifests/defines/config_file.pp | 27 ++++++++--------- manifests/defines/line.pp | 40 ++++++++++++++------------ manifests/defines/module_dir.pp | 11 ++++--- manifests/defines/module_file.pp | 10 +++---- manifests/defines/replace.pp | 15 ++++++---- plugins/puppet/parser/functions/basename.rb | 12 ++++++-- plugins/puppet/parser/functions/dirname.rb | 10 +++++-- plugins/puppet/parser/functions/gsub.rb | 14 +++++---- plugins/puppet/parser/functions/prefix_with.rb | 14 +++++++-- plugins/puppet/parser/functions/re_escape.rb | 2 +- plugins/puppet/parser/functions/split.rb | 12 ++++++-- 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 # 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 # 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 # 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 -- cgit v1.2.3