3rdparty/modules/stdlib/README.markdown

   1 #stdlib
   2
   3 ####Table of Contents
   4
   5 1. [Overview](#overview)
   6 2. [Module Description - What the module does and why it is useful](#module-description)
   7 3. [Setup - The basics of getting started with stdlib](#setup)
   8 4. [Usage - Configuration options and additional functionality](#usage)
   9 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
  10 5. [Limitations - OS compatibility, etc.](#limitations)
  11 6. [Development - Guide for contributing to the module](#development)
  12
  13 ##Overview
  14
  15 Adds a standard library of resources for Puppet modules.
  16
  17 ##Module Description
  18
  19 This module provides a standard library of resources for the development of Puppet
  20 modules. Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet:
  21
  22  * Stages
  23  * Facts
  24  * Functions
  25  * Defined resource types
  26  * Types
  27  * Providers
  28
  29 > *Note:* As of version 3.7, Puppet Enterprise no longer includes the stdlib module. If you're running Puppet Enterprise, you should install the most recent release of stdlib for compatibility with Puppet modules.
  30
  31 ##Setup
  32
  33 Installing the stdlib module adds the functions, facts, and resources of this standard library to Puppet.
  34
  35 ##Usage
  36
  37 After you've installed stdlib, all of its functions, facts, and resources are available for module use or development.
  38
  39 If you want to use a standardized set of run stages for Puppet, `include stdlib` in your manifest.
  40
  41 ## Reference
  42
  43 ### Classes
  44
  45 #### Public Classes
  46
  47 * `stdlib`: Most of stdlib's features are automatically loaded by Puppet. To use standardized run stages in Puppet, declare this class in your manifest with `include stdlib`.
  48
  49   When declared, stdlib declares all other classes in the module. The only other class currently included in the module is `stdlib::stages`.
  50
  51   The stdlib class has no parameters.
  52
  53 #### Private Classes
  54
  55 * `stdlib::stages`: This class manages a standard set of run stages for Puppet. It is managed by the stdlib class and should not be declared independently.
  56
  57   The `stdlib::stages` class declares various run stages for deploying infrastructure, language runtimes, and application layers. The high level stages are (in order):
  58
  59   * setup
  60   * main
  61   * runtime
  62   * setup_infra
  63   * deploy_infra
  64   * setup_app
  65   * deploy_app
  66   * deploy
  67
  68   Sample usage:
  69
  70   ```
  71   node default {
  72     include stdlib
  73     class { java: stage => 'runtime' }
  74   }
  75   ```
  76
  77 ### Resources
  78
  79 * `file_line`: This resource ensures that a given line, including whitespace at the beginning and end, is contained within a file. If the line is not contained in the given file, Puppet will add the line. Multiple resources can be declared to manage multiple lines in the same file. You can also use match to replace existing lines.
  80
  81   ```
  82   file_line { 'sudo_rule':
  83     path => '/etc/sudoers',
  84     line => '%sudo ALL=(ALL) ALL',
  85   }
  86   file_line { 'sudo_rule_nopw':
  87     path => '/etc/sudoers',
  88     line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
  89   }
  90   ```
  91
  92   * `after`: Specify the line after which Puppet will add any new lines. (Existing lines are added in place.) Optional.
  93   * `ensure`: Ensures whether the resource is present. Valid values are 'present', 'absent'.
  94  * `line`: The line to be added to the file located by the `path` parameter.
  95  * `match`: A regular expression to run against existing lines in the file; if a match is found, we replace that line rather than adding a new line. Optional.
  96  * `multiple`: Determine if match can change multiple lines. Valid values are 'true', 'false'. Optional.
  97  * `name`: An arbitrary name used as the identity of the resource.
  98  * `path`: The file in which Puppet will ensure the line specified by the line parameter.
  99
 100 ### Functions
 101
 102 #### `abs`
 103
 104 Returns the absolute value of a number; for example, '-34.56' becomes '34.56'. Takes a single integer and float value as an argument. *Type*: rvalue
 105
 106 #### `any2array`
 107
 108 This converts any object to an array containing that object. Empty argument lists are converted to an empty array. Arrays are left untouched. Hashes are converted to arrays of alternating keys and values. *Type*: rvalue
 109
 110 #### `base64`
 111
 112 Converts a string to and from base64 encoding.
 113 Requires an action ('encode', 'decode') and either a plain or base64-encoded
 114 string. *Type*: rvalue
 115
 116 #### `basename`
 117
 118 Returns the `basename` of a path (optionally stripping an extension). For example:
 119   * ('/path/to/a/file.ext') returns 'file.ext'
 120   * ('relative/path/file.ext') returns 'file.ext'
 121   * ('/path/to/a/file.ext', '.ext') returns 'file'
 122
 123   *Type*: rvalue
 124
 125 #### `bool2num`
 126
 127 Converts a boolean to a number. Converts values:
 128   * 'false', 'f', '0', 'n', and 'no' to 0.
 129   * 'true', 't', '1', 'y', and 'yes' to 1.
 130   Requires a single boolean or string as an input. *Type*: rvalue
 131
 132 #### `capitalize`
 133
 134 Capitalizes the first letter of a string or array of strings.
 135 Requires either a single string or an array as an input. *Type*: rvalue
 136
 137 #### `ceiling`
 138
 139 Returns the smallest integer greater than or equal to the argument.
 140 Takes a single numeric value as an argument. *Type*: rvalue
 141
 142 #### `chomp`
 143
 144 Removes the record separator from the end of a string or an array of
 145 strings; for example, 'hello\n' becomes 'hello'. Requires a single string or array as an input. *Type*: rvalue
 146
 147 #### `chop`
 148
 149 Returns a new string with the last character removed. If the string ends with '\r\n', both characters are removed. Applying `chop` to an empty string returns an empty string. If you want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as input. *Type*: rvalue
 150
 151 #### `concat`
 152
 153 Appends the contents of multiple arrays onto array 1. For example:
 154   * `concat(['1','2','3'],'4')` results in: ['1','2','3','4'].
 155   * `concat(['1','2','3'],'4',['5','6','7'])` results in: ['1','2','3','4','5','6','7'].
 156
 157 #### `count`
 158
 159 Takes an array as first argument and an optional second argument. Count the number of elements in array that matches second argument. If called with only an array, it counts the number of elements that are **not** nil/undef. *Type*: rvalue
 160
 161 #### `defined_with_params`
 162
 163 Takes a resource reference and an optional hash of attributes. Returns 'true' if a resource with the specified attributes has already been added to the catalog. Returns 'false' otherwise.
 164
 165   ```
 166   user { 'dan':
 167     ensure => present,
 168   }
 169
 170   if ! defined_with_params(User[dan], {'ensure' => 'present' }) {
 171     user { 'dan': ensure => present, }
 172   }
 173   ```
 174
 175   *Type*: rvalue
 176
 177 #### `delete`
 178
 179 Deletes all instances of a given element from an array, substring from a
 180 string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1} *Type*: rvalue
 181
 182 #### `delete_at`
 183
 184 Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue
 185
 186 #### `delete_values`
 187
 188 Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue
 189
 190 #### `delete_undef_values`
 191
 192 Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue
 193
 194 #### `difference`
 195
 196 Returns the difference between two arrays.
 197 The returned array is a copy of the original array, removing any items that
 198 also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"].
 199
 200 #### `dirname`
 201
 202 Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'.
 203
 204 #### `downcase`
 205
 206 Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue
 207
 208 #### `empty`
 209
 210 Returns 'true' if the variable is empty. *Type*: rvalue
 211
 212 #### `ensure_packages`
 213
 214 Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement
 215
 216 #### `ensure_resource`
 217
 218 Takes a resource type, title, and a list of attributes that describe a resource.
 219
 220   ```
 221   user { 'dan':
 222     ensure => present,
 223   }
 224   ```
 225
 226   This example only creates the resource if it does not already exist:
 227
 228     `ensure_resource('user', 'dan', {'ensure' => 'present' })`
 229
 230   If the resource already exists, but does not match the specified parameters, this function attempts to recreate the resource, leading to a duplicate resource definition error.
 231
 232   An array of resources can also be passed in, and each will be created with the type and parameters specified if it doesn't already exist.
 233
 234   `ensure_resource('user', ['dan','alex'], {'ensure' => 'present'})`
 235
 236   *Type*: statement
 237
 238 #### `flatten`
 239
 240 This function flattens any deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue
 241
 242 #### `floor`
 243
 244 Returns the largest integer less than or equal to the argument.
 245 Takes a single numeric value as an argument. *Type*: rvalue
 246
 247 #### `fqdn_rand_string`
 248
 249 Generates a random alphanumeric string using an optionally-specified character set (default is alphanumeric), combining the `$fqdn` fact and an optional seed for repeatable randomness.
 250
 251 *Usage:*
 252 ```
 253 fqdn_rand_string(LENGTH, [CHARSET], [SEED])
 254 ```
 255 *Examples:*
 256 ```
 257 fqdn_rand_string(10)
 258 fqdn_rand_string(10, 'ABCDEF!@#$%^')
 259 fqdn_rand_string(10, '', 'custom seed')
 260 ```
 261
 262 *Type*: rvalue
 263
 264 #### `fqdn_rotate`
 265
 266 Rotates an array a random number of times based on a node's fqdn. *Type*: rvalue
 267
 268 #### `get_module_path`
 269
 270 Returns the absolute path of the specified module for the current environment.
 271
 272   `$module_path = get_module_path('stdlib')`
 273
 274   *Type*: rvalue
 275
 276 #### `getparam`
 277
 278 Takes a resource reference and the name of the parameter and
 279 returns the value of the resource's parameter. For example, the following code returns 'param_value'.
 280
 281   *Example:*
 282
 283   ```
 284   define example_resource($param) {
 285   }
 286
 287   example_resource { "example_resource_instance":
 288     param => "param_value"
 289   }
 290
 291   getparam(Example_resource["example_resource_instance"], "param")
 292   ```
 293
 294   *Type*: rvalue
 295
 296 #### `getvar`
 297
 298 Lookup a variable in a remote namespace.
 299
 300   For example:
 301
 302   ```
 303   $foo = getvar('site::data::foo')
 304   # Equivalent to $foo = $site::data::foo
 305   ```
 306
 307   This is useful if the namespace itself is stored in a string:
 308
 309   ```
 310   $datalocation = 'site::data'
 311   $bar = getvar("${datalocation}::bar")
 312   # Equivalent to $bar = $site::data::bar
 313   ```
 314
 315   *Type*: rvalue
 316
 317 #### `grep`
 318
 319 This function searches through an array and returns any elements that match the provided regular expression. For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd']. *Type*: rvalue
 320
 321 #### `has_interface_with`
 322
 323 Returns boolean based on kind and value:
 324   * macaddress
 325   * netmask
 326   * ipaddress
 327   * network
 328
 329   *Examples:*
 330
 331   ```
 332   has_interface_with("macaddress", "x:x:x:x:x:x")
 333   has_interface_with("ipaddress", "127.0.0.1")    => true
 334   ```
 335
 336   If no kind is given, then the presence of the interface is checked:
 337
 338   ```
 339   has_interface_with("lo")                        => true
 340   ```
 341
 342   *Type*: rvalue
 343
 344 #### `has_ip_address`
 345
 346 Returns true if the client has the requested IP address on some interface. This function iterates through the `interfaces` fact and checks the `ipaddress_IFACE` facts, performing a simple string comparison. *Type*: rvalue
 347
 348 #### `has_ip_network`
 349
 350 Returns true if the client has an IP address within the requested network. This function iterates through the 'interfaces' fact and checks the 'network_IFACE' facts, performing a simple string comparision. *Type*: rvalue
 351
 352 #### `has_key`
 353
 354 Determine if a hash has a certain key value.
 355
 356   *Example*:
 357
 358   ```
 359   $my_hash = {'key_one' => 'value_one'}
 360   if has_key($my_hash, 'key_two') {
 361     notice('we will not reach here')
 362   }
 363   if has_key($my_hash, 'key_one') {
 364     notice('this will be printed')
 365   }
 366   ```
 367
 368   *Type*: rvalue
 369
 370 #### `hash`
 371
 372 This function converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}. *Type*: rvalue
 373
 374 #### `intersection`
 375
 376 This function returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"].
 377
 378 #### `is_array`
 379
 380 Returns 'true' if the variable passed to this function is an array. *Type*: rvalue
 381
 382 #### `is_bool`
 383
 384 Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue
 385
 386 #### `is_domain_name`
 387
 388 Returns 'true' if the string passed to this function is a syntactically correct domain name. *Type*: rvalue
 389
 390 #### `is_float`
 391
 392 Returns 'true' if the variable passed to this function is a float. *Type*: rvalue
 393
 394 #### `is_function_available`
 395
 396 This function accepts a string as an argument and determines whether the Puppet runtime has access to a function by that name. It returns 'true' if the function exists, 'false' if not. *Type*: rvalue
 397
 398 #### `is_hash`
 399
 400 Returns 'true' if the variable passed to this function is a hash. *Type*: rvalue
 401
 402 #### `is_integer`
 403
 404 Returns 'true' if the variable returned to this string is an integer. *Type*: rvalue
 405
 406 #### `is_ip_address`
 407
 408 Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue
 409
 410 #### `is_mac_address`
 411
 412 Returns 'true' if the string passed to this function is a valid MAC address. *Type*: rvalue
 413
 414 #### `is_numeric`
 415
 416 Returns 'true' if the variable passed to this function is a number. *Type*: rvalue
 417
 418 #### `is_string`
 419
 420 Returns 'true' if the variable passed to this function is a string. *Type*: rvalue
 421
 422 #### `join`
 423
 424 This function joins an array into a string using a separator. For example, `join(['a','b','c'], ",")` results in: "a,b,c". *Type*: rvalue
 425
 426 #### `join_keys_to_values`
 427
 428 This function joins each key of a hash to that key's corresponding value with a separator. Keys and values are cast to strings. The return value is an array in which each element is one joined key/value pair. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *Type*: rvalue
 429
 430 #### `keys`
 431
 432 Returns the keys of a hash as an array. *Type*: rvalue
 433
 434 #### `loadyaml`
 435
 436 Load a YAML file containing an array, string, or hash, and return the data in the corresponding native data type. For example:
 437
 438   ```
 439   $myhash = loadyaml('/etc/puppet/data/myhash.yaml')
 440   ```
 441
 442   *Type*: rvalue
 443
 444 #### `lstrip`
 445
 446 Strips leading spaces to the left of a string. *Type*: rvalue
 447
 448 #### `max`
 449
 450 Returns the highest value of all arguments. Requires at least one argument. *Type*: rvalue
 451
 452 #### `member`
 453
 454 This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')`  and `member(['a','b','c'], ['c','d'])` return 'false'. *Type*: rvalue
 455
 456 #### `merge`
 457
 458 Merges two or more hashes together and returns the resulting hash.
 459
 460   *Example*:
 461
 462   ```
 463   $hash1 = {'one' => 1, 'two' => 2}
 464   $hash2 = {'two' => 'dos', 'three' => 'tres'}
 465   $merged_hash = merge($hash1, $hash2)
 466   # The resulting hash is equivalent to:
 467   # $merged_hash =  {'one' => 1, 'two' => 'dos', 'three' => 'tres'}
 468   ```
 469
 470   When there is a duplicate key, the key in the rightmost hash "wins." *Type*: rvalue
 471
 472 #### `min`
 473
 474 Returns the lowest value of all arguments. Requires at least one argument. *Type*: rvalue
 475
 476 #### `num2bool`
 477
 478 This function converts a number or a string representation of a number into a true boolean. Zero or anything non-numeric becomes 'false'. Numbers greater than 0 become 'true'. *Type*: rvalue
 479
 480 #### `parsejson`
 481
 482 This function accepts JSON as a string and converts into the correct Puppet structure. *Type*: rvalue
 483
 484 #### `parseyaml`
 485
 486 This function accepts YAML as a string and converts it into the correct Puppet structure. *Type*: rvalue
 487
 488 #### `pick`
 489
 490 From a list of values, returns the first value that is not undefined or an empty string. Takes any number of arguments, and raises an error if all values are undefined or empty.
 491
 492   ```
 493   $real_jenkins_version = pick($::jenkins_version, '1.449')
 494   ```
 495
 496  *Type*: rvalue
 497
 498 #### `prefix`
 499
 500 This function applies a prefix to all elements in an array or to the keys in a hash. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'], and `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue
 501
 502
 503 #### `assert_private`
 504
 505 This function sets the current class or definition as private.
 506 Calling the class or definition from outside the current module will fail. For example, `assert_private()` called in class `foo::bar` outputs the following message if class is called from outside module `foo`:
 507
 508   ```
 509   Class foo::bar is private
 510   ```
 511
 512   You can specify the error message you want to use:
 513
 514   ```
 515   assert_private("You're not supposed to do that!")
 516   ```
 517
 518   *Type*: statement
 519
 520 #### `pw_hash`
 521
 522 Hashes a password using the crypt function. Provides a hash usable on most POSIX systems.
 523
 524 The first argument to this function is the password to hash. If it is undef or an empty string, this function returns undef.
 525
 526 The second argument to this function is which type of hash to use. It will be converted into the appropriate crypt(3) hash specifier. Valid hash types are:
 527
 528 |Hash type            |Specifier|
 529 |---------------------|---------|
 530 |MD5                  |1        |
 531 |SHA-256              |5        |
 532 |SHA-512 (recommended)|6        |
 533
 534 The third argument to this function is the salt to use.
 535
 536 Note: this uses the Puppet Master's implementation of crypt(3). If your environment contains several different operating systems, ensure that they are compatible before using this function.
 537
 538 #### `range`
 539
 540 When given range in the form of '(start, stop)', `range` extrapolates a range as an array. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9].
 541
 542   Non-integer strings are accepted; `range("a", "c")` returns ["a","b","c"], and `range("host01", "host10")` returns ["host01", "host02", ..., "host09", "host10"].
 543
 544   Passing a third argument will cause the generated range to step by that interval, e.g. `range("0", "9", "2")` returns ["0","2","4","6","8"]
 545
 546   *Type*: rvalue
 547
 548 #### `reject`
 549
 550 This function searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *Type*: rvalue
 551
 552 #### `reverse`
 553
 554 Reverses the order of a string or array. *Type*: rvalue
 555
 556 #### `rstrip`
 557
 558 Strips leading spaces to the right of the string.*Type*: rvalue
 559
 560 #### `shuffle`
 561
 562 Randomizes the order of a string or array elements. *Type*: rvalue
 563
 564 #### `size`
 565
 566 Returns the number of elements in a string or array. *Type*: rvalue
 567
 568 #### `sort`
 569
 570 Sorts strings and arrays lexically. *Type*: rvalue
 571
 572 #### `squeeze`
 573
 574 Returns a new string where runs of the same character that occur in this set are replaced by a single character. *Type*: rvalue
 575
 576 #### `str2bool`
 577
 578 This converts a string to a boolean. This attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue
 579
 580 #### `str2saltedsha512`
 581
 582 This converts a string to a salted-SHA512 password hash, used for OS X versions >= 10.7. Given any string, this function returns a hex version of a salted-SHA512 password hash, which can be inserted into your Puppet
 583 manifests as a valid password attribute. *Type*: rvalue
 584
 585 #### `strftime`
 586
 587 This function returns formatted time. For example,  `strftime("%s")` returns the time since epoch, and `strftime("%Y=%m-%d")` returns the date. *Type*: rvalue
 588
 589   *Format:*
 590
 591     * `%a`: The abbreviated weekday name ('Sun')
 592     * `%A`: The  full  weekday  name ('Sunday')
 593     * `%b`: The abbreviated month name ('Jan')
 594     * `%B`: The  full  month  name ('January')
 595     * `%c`: The preferred local date and time representation
 596     * `%C`: Century (20 in 2009)
 597     * `%d`: Day of the month (01..31)
 598     * `%D`: Date (%m/%d/%y)
 599     * `%e`: Day of the month, blank-padded ( 1..31)
 600     * `%F`: Equivalent to %Y-%m-%d (the ISO 8601 date format)
 601     * `%h`: Equivalent to %b
 602     * `%H`: Hour of the day, 24-hour clock (00..23)
 603     * `%I`: Hour of the day, 12-hour clock (01..12)
 604     * `%j`: Day of the year (001..366)
 605     * `%k`: Hour, 24-hour clock, blank-padded ( 0..23)
 606     * `%l`: Hour, 12-hour clock, blank-padded ( 0..12)
 607     * `%L`: Millisecond of the second (000..999)
 608     * `%m`: Month of the year (01..12)
 609     * `%M`: Minute of the hour (00..59)
 610     * `%n`: Newline (\n)
 611     * `%N`: Fractional seconds digits, default is 9 digits (nanosecond)
 612       * `%3N`: Millisecond (3 digits)
 613       * `%6N`: Microsecond (6 digits)
 614       * `%9N`: Nanosecond (9 digits)
 615     * `%p`: Meridian indicator ('AM'  or  'PM')
 616     * `%P`: Meridian indicator ('am'  or  'pm')
 617     * `%r`: Time, 12-hour (same as %I:%M:%S %p)
 618     * `%R`: Time, 24-hour (%H:%M)
 619     * `%s`: Number of seconds since 1970-01-01 00:00:00 UTC.
 620     * `%S`: Second of the minute (00..60)
 621     * `%t`: Tab character (     )
 622     * `%T`: Time, 24-hour (%H:%M:%S)
 623     * `%u`: Day of the week as a decimal, Monday being 1. (1..7)
 624     * `%U`: Week  number  of the current year, starting with the first Sunday as the first day of the first week (00..53)
 625     * `%v`: VMS date (%e-%b-%Y)
 626     * `%V`: Week number of year according to ISO 8601 (01..53)
 627     * `%W`: Week  number of the current year, starting with the first Monday as the first day of the first week (00..53)
 628     * `%w`: Day of the week (Sunday is 0, 0..6)
 629     * `%x`: Preferred representation for the date alone, no time
 630     * `%X`: Preferred representation for the time alone, no date
 631     * `%y`: Year without a century (00..99)
 632     * `%Y`: Year with century
 633     * `%z`: Time zone as  hour offset from UTC (e.g. +0900)
 634     * `%Z`: Time zone name
 635     * `%%`: Literal '%' character
 636
 637 #### `strip`
 638
 639 This function removes leading and trailing whitespace from a string or from every string inside an array. For example, `strip("    aaa   ")` results in "aaa". *Type*: rvalue
 640
 641 #### `suffix`
 642
 643 This function applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue
 644
 645 #### `swapcase`
 646
 647 This function swaps the existing case of a string. For example, `swapcase("aBcD")` results in "AbCd". *Type*: rvalue
 648
 649 #### `time`
 650
 651 This function returns the current time since epoch as an integer. For example, `time()` returns something like '1311972653'. *Type*: rvalue
 652
 653 #### `to_bytes`
 654
 655 Converts the argument into bytes, for example 4 kB becomes 4096.
 656 Takes a single string value as an argument. *Type*: rvalue
 657
 658 #### `type3x`
 659
 660 Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when puppet 3 support is dropped and the new type system may be used. *Type*: rvalue
 661
 662 #### `type_of`
 663
 664 Returns the literal type when passed a value. Requires the new
 665   parser. Useful for comparison of types with `<=` such as in `if
 666   type_of($some_value) <= Array[String] { ... }` (which is equivalent to `if
 667   $some_value =~ Array[String] { ... }`) *Type*: rvalue
 668
 669 #### `union`
 670
 671 This function returns a union of two arrays. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"].
 672
 673 #### `unique`
 674
 675 This function removes duplicates from strings and arrays. For example, `unique("aabbcc")` returns 'abc'.
 676
 677 You can also use this with arrays. For example, `unique(["a","a","b","b","c","c"])` returns ["a","b","c"]. *Type*: rvalue
 678
 679 #### `upcase`
 680
 681 Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase("abcd")` returns 'ABCD'.  *Type*: rvalue
 682
 683 #### `uriescape`
 684
 685 Urlencodes a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue
 686
 687 #### `validate_absolute_path`
 688
 689 Validate the string represents an absolute path in the filesystem.  This function works for Windows and Unix style paths.
 690
 691     The following values will pass:
 692
 693     ```
 694     $my_path = 'C:/Program Files (x86)/Puppet Labs/Puppet'
 695     validate_absolute_path($my_path)
 696     $my_path2 = '/var/lib/puppet'
 697     validate_absolute_path($my_path2)
 698     $my_path3 = ['C:/Program Files (x86)/Puppet Labs/Puppet','C:/Program Files/Puppet Labs/Puppet']
 699     validate_absolute_path($my_path3)
 700     $my_path4 = ['/var/lib/puppet','/usr/share/puppet']
 701     validate_absolute_path($my_path4)
 702     ```
 703
 704     The following values will fail, causing compilation to abort:
 705
 706     ```
 707     validate_absolute_path(true)
 708     validate_absolute_path('../var/lib/puppet')
 709     validate_absolute_path('var/lib/puppet')
 710     validate_absolute_path([ 'var/lib/puppet', '/var/foo' ])
 711     validate_absolute_path([ '/var/lib/puppet', 'var/foo' ])
 712     $undefined = undef
 713     validate_absolute_path($undefined)
 714     ```
 715
 716     *Type*: statement
 717
 718 #### `validate_array`
 719
 720 Validate that all passed values are array data structures. Abort catalog compilation if any value fails this check.
 721
 722   The following values will pass:
 723
 724   ```
 725   $my_array = [ 'one', 'two' ]
 726   validate_array($my_array)
 727   ```
 728
 729   The following values will fail, causing compilation to abort:
 730
 731   ```
 732   validate_array(true)
 733   validate_array('some_string')
 734   $undefined = undef
 735   validate_array($undefined)
 736   ```
 737
 738   *Type*: statement
 739
 740 #### `validate_augeas`
 741
 742 Performs validation of a string using an Augeas lens.
 743 The first argument of this function should be the string to test, and the second argument should be the name of the Augeas lens to use. If Augeas fails to parse the string with the lens, the compilation aborts with a parse error.
 744
 745   A third optional argument lists paths which should **not** be found in the file. The `$file` variable points to the location of the temporary file being tested in the Augeas tree.
 746
 747   For example, to make sure your passwd content never contains user `foo`:
 748
 749   ```
 750   validate_augeas($passwdcontent, 'Passwd.lns', ['$file/foo'])
 751   ```
 752
 753   To ensure that no users use the '/bin/barsh' shell:
 754
 755   ```
 756   validate_augeas($passwdcontent, 'Passwd.lns', ['$file/*[shell="/bin/barsh"]']
 757   ```
 758
 759   You can pass a fourth argument as the error message raised and shown to the user:
 760
 761   ```
 762   validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas')
 763   ```
 764
 765   *Type*: statement
 766
 767 #### `validate_bool`
 768
 769 Validate that all passed values are either true or false. Abort catalog compilation if any value fails this check.
 770
 771   The following values will pass:
 772
 773   ```
 774   $iamtrue = true
 775   validate_bool(true)
 776   validate_bool(true, true, false, $iamtrue)
 777   ```
 778
 779   The following values will fail, causing compilation to abort:
 780
 781   ```
 782   $some_array = [ true ]
 783   validate_bool("false")
 784   validate_bool("true")
 785   validate_bool($some_array)
 786   ```
 787
 788   *Type*: statement
 789
 790 #### `validate_cmd`
 791
 792 Performs validation of a string with an external command. The first argument of this function should be a string to test, and the second argument should be a path to a test command taking a % as a placeholder for the file path (will default to the end of the command if no % placeholder given). If the command, launched against a tempfile containing the passed string, returns a non-null value, compilation will abort with a parse error.
 793
 794 If a third argument is specified, this will be the error message raised and seen by the user.
 795
 796   ```
 797   # Defaults to end of path
 798   validate_cmd($sudoerscontent, '/usr/sbin/visudo -c -f', 'Visudo failed to validate sudoers content')
 799   ```
 800   ```
 801   # % as file location
 802   validate_cmd($haproxycontent, '/usr/sbin/haproxy -f % -c', 'Haproxy failed to validate config content')
 803   ```
 804
 805   *Type*: statement
 806
 807 #### `validate_hash`
 808
 809 Validates that all passed values are hash data structures. Abort catalog compilation if any value fails this check.
 810
 811   The following values will pass:
 812
 813   ```
 814   $my_hash = { 'one' => 'two' }
 815   validate_hash($my_hash)
 816   ```
 817
 818   The following values will fail, causing compilation to abort:
 819
 820   ```
 821   validate_hash(true)
 822   validate_hash('some_string')
 823   $undefined = undef
 824   validate_hash($undefined)
 825   ```
 826
 827   *Type*: statement
 828
 829 #### `validate_integer`
 830
 831 Validate that the first argument is an integer (or an array of integers). Abort catalog compilation if any of the checks fail.
 832
 833   The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max.
 834
 835   The third argument is optional and passes a minimum.  (All elements of) the first argument has to be greater or equal to this min.
 836   If, and only if, a minimum is given, the second argument may be an empty string or undef, which will be handled to just check
 837   if (all elements of) the first argument are greater or equal to the given minimum.
 838
 839   It will fail if the first argument is not an integer or array of integers, and if arg 2 and arg 3 are not convertable to an integer.
 840
 841   The following values will pass:
 842
 843   ```
 844   validate_integer(1)
 845   validate_integer(1, 2)
 846   validate_integer(1, 1)
 847   validate_integer(1, 2, 0)
 848   validate_integer(2, 2, 2)
 849   validate_integer(2, '', 0)
 850   validate_integer(2, undef, 0)
 851   $foo = undef
 852   validate_integer(2, $foo, 0)
 853   validate_integer([1,2,3,4,5], 6)
 854   validate_integer([1,2,3,4,5], 6, 0)
 855   ```
 856
 857   * Plus all of the above, but any combination of values passed as strings ('1' or "1").
 858   * Plus all of the above, but with (correct) combinations of negative integer values.
 859
 860   The following values will fail, causing compilation to abort:
 861
 862   ```
 863   validate_integer(true)
 864   validate_integer(false)
 865   validate_integer(7.0)
 866   validate_integer({ 1 => 2 })
 867   $foo = undef
 868   validate_integer($foo)
 869   validate_integer($foobaridontexist)
 870
 871   validate_integer(1, 0)
 872   validate_integer(1, true)
 873   validate_integer(1, '')
 874   validate_integer(1, undef)
 875   validate_integer(1, , 0)
 876   validate_integer(1, 2, 3)
 877   validate_integer(1, 3, 2)
 878   validate_integer(1, 3, true)
 879   ```
 880
 881   * Plus all of the above, but any combination of values passed as strings ('false' or "false").
 882   * Plus all of the above, but with incorrect combinations of negative integer values.
 883   * Plus all of the above, but with non-integer crap in arrays or maximum / minimum argument.
 884
 885   *Type*: statement
 886
 887 #### `validate_numeric`
 888
 889 Validate that the first argument is a numeric value (or an array of numeric values). Abort catalog compilation if any of the checks fail.
 890
 891   The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max.
 892
 893   The third argument is optional and passes a minimum.  (All elements of) the first argument has to be greater or equal to this min.
 894   If, and only if, a minimum is given, the second argument may be an empty string or undef, which will be handled to just check
 895   if (all elements of) the first argument are greater or equal to the given minimum.
 896
 897   It will fail if the first argument is not a numeric (Integer or Float) or array of numerics, and if arg 2 and arg 3 are not convertable to a numeric.
 898
 899   For passing and failing usage, see `validate_integer()`. It is all the same for validate_numeric, yet now floating point values are allowed, too.
 900
 901   *Type*: statement
 902
 903 #### `validate_re`
 904
 905 Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the string to
 906 test, and the second argument should be a stringified regular expression
 907 (without the // delimiters) or an array of regular expressions. If none
 908 of the regular expressions match the string passed in, compilation aborts with a parse error.
 909
 910   You can pass a third argument as the error message raised and shown to the user.
 911
 912   The following strings validate against the regular expressions:
 913
 914   ```
 915   validate_re('one', '^one$')
 916   validate_re('one', [ '^one', '^two' ])
 917   ```
 918
 919   The following string fails to validate, causing compilation to abort:
 920
 921   ```
 922   validate_re('one', [ '^two', '^three' ])
 923   ```
 924
 925   To set the error message:
 926
 927   ```
 928   validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7')
 929   ```
 930
 931   *Type*: statement
 932
 933 #### `validate_slength`
 934
 935 Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if arg 2 is not convertable to a number.
 936
 937   The following values pass:
 938
 939   ```
 940   validate_slength("discombobulate",17)
 941   validate_slength(["discombobulate","moo"],17)
 942   ```
 943
 944   The following values fail:
 945
 946   ```
 947   validate_slength("discombobulate",1)
 948   validate_slength(["discombobulate","thermometer"],5)
 949   ```
 950
 951   *Type*: statement
 952
 953 #### `validate_string`
 954
 955 Validates that all passed values are string data structures. Aborts catalog compilation if any value fails this check.
 956
 957   The following values pass:
 958
 959   ```
 960   $my_string = "one two"
 961   validate_string($my_string, 'three')
 962   ```
 963
 964   The following values fail, causing compilation to abort:
 965
 966   ```
 967   validate_string(true)
 968   validate_string([ 'some', 'array' ])
 969   $undefined = undef
 970   validate_string($undefined)
 971   ```
 972
 973   *Type*: statement
 974
 975 #### `values`
 976
 977 When given a hash, this function returns the values of that hash.
 978
 979   *Examples:*
 980
 981   ```
 982   $hash = {
 983     'a' => 1,
 984     'b' => 2,
 985     'c' => 3,
 986   }
 987   values($hash)
 988   ```
 989
 990   The example above returns [1,2,3].
 991
 992   *Type*: rvalue
 993
 994 #### `values_at`
 995
 996 Finds value inside an array based on location. The first argument is the array you want to analyze, and the second element can be a combination of:
 997
 998   * A single numeric index
 999   * A range in the form of 'start-stop' (eg. 4-9)
1000   * An array combining the above
1001
1002   For example, `values_at(['a','b','c'], 2)` returns ['c']; `values_at(['a','b','c'], ["0-1"])` returns ['a','b']; and `values_at(['a','b','c','d','e'], [0, "2-3"])` returns ['a','c','d'].
1003
1004   *Type*: rvalue
1005
1006 #### `zip`
1007
1008 Takes one element from first array and merges corresponding elements from second array. This generates a sequence of n-element arrays, where n is one more than the count of arguments. For example, `zip(['1','2','3'],['4','5','6'])` results in ["1", "4"], ["2", "5"], ["3", "6"]. *Type*: rvalue
1009
1010 ##Limitations
1011
1012 As of Puppet Enterprise version 3.7, the stdlib module is no longer included in PE. PE users should install the most recent release of stdlib for compatibility with Puppet modules.
1013
1014 ###Version Compatibility
1015
1016 Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x |
1017 :---------------|:-----:|:---:|:---:|:----:
1018 **stdlib 2.x**  | **yes** | **yes** | no | no
1019 **stdlib 3.x**  | no    | **yes**  | **yes** | no
1020 **stdlib 4.x**  | no    | **yes**  | **yes** | no
1021 **stdlib 5.x**  | no    | no  | **yes**  | **yes**
1022
1023 **stdlib 5.x**: When released, stdlib 5.x will drop support for Puppet 2.7.x. Please see [this discussion](https://github.com/puppetlabs/puppetlabs-stdlib/pull/176#issuecomment-30251414).
1024
1025 ##Development
1026
1027 Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
1028
1029 We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
1030
1031 You can read the complete module contribution guide on the [Puppet Labs wiki](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing).
1032
1033 To report or research a bug with any part of this module, please go to
1034 [http://tickets.puppetlabs.com/browse/PUP](http://tickets.puppetlabs.com/browse/PUP).
1035
1036 ##Contributors
1037
1038 The list of contributors can be found at: https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors
1039
1040
1041
1042