modules/stdlib/README.markdown

   1 # Puppet Labs Standard Library #
   2
   3 This module provides a "standard library" of resources for developing Puppet
   4 Modules.  This modules will include the following additions to Puppet
   5
   6  * Stages
   7  * Facts
   8  * Functions
   9  * Defined resource types
  10  * Types
  11  * Providers
  12
  13 This module is officially curated and provided by Puppet Labs.  The modules
  14 Puppet Labs writes and distributes will make heavy use of this standard
  15 library.
  16
  17 # Versions #
  18
  19 This module follows semver.org (v1.0.0) versioning guidelines.  The standard
  20 library module is released as part of [Puppet
  21 Enterprise](http://puppetlabs.com/puppet/puppet-enterprise/) and as a result
  22 older versions of Puppet Enterprise that Puppet Labs still supports will have
  23 bugfix maintenance branches periodically "merged up" into master.  The current
  24 list of integration branches are:
  25
  26  * v2.1.x (v2.1.1 released in PE 1.2, 1.2.1, 1.2.3, 1.2.4)
  27  * v2.2.x (Never released as part of PE, only to the Forge)
  28  * v2.3.x (Scheduled for next PE feature release)
  29  * master (mainline development branch)
  30
  31 The first Puppet Enterprise version including the stdlib module is Puppet
  32 Enterprise 1.2.
  33
  34 # Compatibility #
  35
  36 ## stdlib v2.1.x, v2.2.x ##
  37
  38 v2.1.x and v2.2.x of this module are designed to work with Puppet versions
  39 2.6.x and 2.7.x.  There are currently no plans for a Puppet 0.25 standard
  40 library module.
  41
  42 ## stdlib v2.3.x ##
  43
  44 While not yet released, the standard library may only work with Puppet 2.7.x.
  45
  46 # Functions #
  47
  48   Please see `puppet doc -r function` for documentation on each function.  The
  49   current list of functions is:
  50
  51  * getvar
  52  * has\_key
  53  * loadyaml
  54  * merge.rb
  55  * validate\_array
  56  * validate\_bool
  57  * validate\_hash
  58  * validate\_re
  59  * validate\_string
  60
  61 ## validate\_hash ##
  62
  63     $somehash = { 'one' => 'two' }
  64     validate\_hash($somehash)
  65
  66 ## getvar() ##
  67
  68 This function aims to look up variables in user-defined namespaces within
  69 puppet.  Note, if the namespace is a class, it should already be evaluated
  70 before the function is used.
  71
  72     $namespace = 'site::data'
  73     include "${namespace}"
  74     $myvar = getvar("${namespace}::myvar")
  75
  76 ## Facts ##
  77
  78 Facts in `/etc/facter/facts.d` and `/etc/puppetlabs/facter/facts.d` are now loaded
  79 automatically.  This is a direct copy of R.I. Pienaar's custom facter fact
  80 located at:
  81 [https://github.com/ripienaar/facter-facts/tree/master/facts-dot-d](https://github.com/ripienaar/facter-facts/tree/master/facts-dot-d)
  82