puppet 4.2.0 → 4.3.0

data/lib/puppet/parser/functions/hiera_array.rb

@@ -1,34 +1,77 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_array, :type => :rvalue, :arity => -2,:doc => "Returns all 
-  matches throughout the hierarchy --- not just the first match --- as a flattened array of unique values.
-  If any of the matched values are arrays, they're flattened and included in the results.
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the value.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  If any matched value is a hash, puppet will raise a type mismatch error.
-
-  More thorough examples of `hiera` are available at:  
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera_array,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<-DOC
+Finds all matches of a key throughout the hierarchy and returns them as a single flattened
+array of unique values. If any of the matched values are arrays, they're flattened and
+included in the results. This is called an
+[array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge).
+
+The `hiera_array` function takes up to three arguments, in this order:
+
+1. A string key that Hiera searches for in the hierarchy. **Required**.
+2. An optional default value to return if Hiera doesn't find anything matching the key.
+    * If this argument isn't provided and this function results in a lookup failure, Puppet
+    fails with a compilation error.
+3. The optional name of an arbitrary
+[hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+    * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+    searching the rest of the hierarchy.
+
+**Example**: Using `hiera_array`
+
+~~~ yaml
+# Assuming hiera.yaml
+# :hierarchy:
+#   - web01.example.com
+#   - common
+
+# Assuming common.yaml:
+# users:
+#   - 'cdouglas = regular'
+#   - 'efranklin = regular'
+
+# Assuming web01.example.com.yaml:
+# users: 'abarry = admin'
+~~~
+
+~~~ puppet
+$allusers = hiera_array('users', undef)
+
+# $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+~~~
+
+You can optionally generate the default value with a
+[lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+takes one parameter.
+
+**Example**: Using `hiera_array` with a lambda
+
+~~~ puppet
+# Assuming the same Hiera data as the previous example:
+
+$allusers = hiera_array('users') | $key | { "Key \'${key}\' not found" }
+
+# $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+# If hiera_array couldn't match its key, it would return the lambda result,
+# "Key 'users' not found".
+~~~
+
+`hiera_array` expects that all values returned will be strings or arrays. If any matched
+value is a hash, Puppet raises a type mismatch error.
+
+See
+[the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+for more information about Hiera lookup functions.
+
+- Since 4.0.0
+DOC
+) do |*args|
     function_fail(["hiera_array() has been converted to 4x API"])
   end
 end

data/lib/puppet/parser/functions/hiera_hash.rb

@@ -1,36 +1,87 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_hash, :type => :rvalue, :arity => -2, :doc => 
-  "Returns a merged hash of matches from throughout the hierarchy. In cases where two or 
-  more hashes share keys, the hierarchy  order determines which key/value pair will be 
-  used in the returned hash, with the pair in the highest priority data source winning.
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the value.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  `hiera_hash` expects that all values returned will be hashes. If any of the values 
-  found in the data sources are strings or arrays, puppet will raise a type mismatch error.
-
-  More thorough examples of `hiera_hash` are available at:  
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera_hash,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<-DOC
+Finds all matches of a key throughout the hierarchy and returns them in a merged hash.
+If any of the matched hashes share keys, the final hash uses the value from the
+highest priority match. This is called a
+[hash merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#hash-merge).
+
+The merge strategy is determined by Hiera's
+[`:merge_behavior`](https://docs.puppetlabs.com/hiera/latest/configuring.html#mergebehavior)
+setting.
+
+The `hiera_hash` function takes up to three arguments, in this order:
+
+1. A string key that Hiera searches for in the hierarchy. **Required**.
+2. An optional default value to return if Hiera doesn't find anything matching the key.
+    * If this argument isn't provided and this function results in a lookup failure, Puppet
+    fails with a compilation error.
+3. The optional name of an arbitrary
+[hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+    * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+    searching the rest of the hierarchy.
+
+**Example**: Using `hiera_hash`
+
+~~~ yaml
+# Assuming hiera.yaml
+# :hierarchy:
+#   - web01.example.com
+#   - common
+
+# Assuming common.yaml:
+# users:
+#   regular:
+#     'cdouglas': 'Carrie Douglas'
+
+# Assuming web01.example.com.yaml:
+# users:
+#   administrators:
+#     'aberry': 'Amy Berry'
+~~~
+
+~~~ puppet
+# Assuming we are not web01.example.com:
+
+$allusers = hiera_hash('users', undef)
+
+# $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+#                     administrators => {"aberry" => "Amy Berry"}}
+~~~
+
+You can optionally generate the default value with a
+[lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+takes one parameter.
+
+**Example**: Using `hiera_hash` with a lambda
+
+~~~ puppet
+# Assuming the same Hiera data as the previous example:
+
+$allusers = hiera_hash('users') | $key | { "Key \'${key}\' not found" }
+
+# $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+#                     administrators => {"aberry" => "Amy Berry"}}
+# If hiera_hash couldn't match its key, it would return the lambda result,
+# "Key 'users' not found".
+~~~
+
+`hiera_hash` expects that all values returned will be hashes. If any of the values
+found in the data sources are strings or arrays, Puppet raises a type mismatch error.
+
+See
+[the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+for more information about Hiera lookup functions.
+
+- Since 4.0.0
+DOC
+  ) do |*args|
     function_fail(["hiera_hash() has been converted to 4x API"])
   end
 end

data/lib/puppet/parser/functions/hiera_include.rb

@@ -1,46 +1,87 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_include, :arity => -2, :doc => "Assigns classes to a node
-  using an array merge lookup that retrieves the value for a user-specified key
-  from a Hiera data source.
-
-  To use `hiera_include`, the following configuration is required:
-
-  - A key name to use for classes, e.g. `classes`.
-  - A line in the puppet `sites.pp` file (e.g. `/etc/puppetlabs/puppet/manifests/sites.pp`)
-    reading `hiera_include('classes')`. Note that this line must be outside any node
-    definition and below any top-scope variables in use for Hiera lookups.
-  - Class keys in the appropriate data sources. In a data source keyed to a node's role,
-    one might have:
-
-            ---
-            classes:
-              - apache
-              - apache::passenger
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the array to be used in the subsequent call to include.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  More thorough examples of `hiera_include` are available at:
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera_include,
+    :arity => -2,
+    :doc => <<-DOC
+Assigns classes to a node using an
+[array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.htmlarray-merge)
+that retrieves the value for a user-specified key from Hiera's data.
+
+The `hiera_include` function requires:
+
+- A string key name to use for classes.
+- A call to this function (i.e. `hiera_include('classes')`) in your environment's
+`sites.pp` manifest, outside of any node definitions and below any top-scope variables
+that Hiera uses in lookups.
+- `classes` keys in the appropriate Hiera data sources, with an array for each
+`classes` key and each value of the array containing the name of a class.
+
+The function takes up to three arguments, in this order:
+
+1. A string key that Hiera searches for in the hierarchy. **Required**.
+2. An optional default value to return if Hiera doesn't find anything matching the key.
+    * If this argument isn't provided and this function results in a lookup failure, Puppet
+    fails with a compilation error.
+3. The optional name of an arbitrary
+[hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+    * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+    searching the rest of the hierarchy.
+
+The function uses an
+[array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.htmlarray-merge)
+to retrieve the `classes` array, so every node gets every class from the hierarchy.
+
+**Example**: Using `hiera_include`
+
+~~~ yaml
+# Assuming hiera.yaml
+# :hierarchy:
+#   - web01.example.com
+#   - common
+
+# Assuming web01.example.com.yaml:
+# classes:
+#   - apache::mod::php
+
+# Assuming common.yaml:
+# classes:
+#   - apache
+~~~
+
+~~~ puppet
+# In site.pp, outside of any node definitions and below any top-scope variables:
+hiera_include('classes', undef)
+
+# Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+~~~
+
+You can optionally generate the default value with a
+[lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+takes one parameter.
+
+**Example**: Using `hiera_include` with a lambda
+
+~~~ puppet
+# Assuming the same Hiera data as the previous example:
+
+# In site.pp, outside of any node definitions and below any top-scope variables:
+hiera_include('classes') | $key | {"Key \'${key}\' not found" }
+
+# Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+# If hiera_include couldn't match its key, it would return the lambda result,
+# "Key 'classes' not found".
+~~~
+
+See [the documentation](http://links.puppetlabs.com/hierainclude) for more information
+and a more detailed example of how `hiera_include` uses array merge lookups to classify
+nodes.
+
+- Since 4.0.0
+DOC
+  ) do |*args|
     function_fail(["hiera_include() has been converted to 4x API"])
   end
 end

data/lib/puppet/parser/functions/inline_epp.rb

@@ -1,76 +1,51 @@
 Puppet::Parser::Functions::newfunction(:inline_epp, :type => :rvalue, :arity => -2, :doc =>
-"Evaluates an Embedded Puppet Template (EPP) string and returns the rendered text result as a String.
+"Evaluates an Embedded Puppet (EPP) template string and returns the rendered
+text result as a String.
 
-EPP support the following tags:
+`inline_epp('<EPP TEMPLATE STRING>', <PARAMETER HASH>)`
 
-* `<%= puppet expression %>` - This tag renders the value of the expression it contains.
-* `<% puppet expression(s) %>` - This tag will execute the expression(s) it contains, but renders nothing.
-* `<%# comment %>` - The tag and its content renders nothing.
-* `<%%` or `%%>` - Renders a literal `<%` or `%>` respectively.
-* `<%-` - Same as `<%` but suppresses any leading whitespace.
-* `-%>` - Same as `%>` but suppresses any trailing whitespace on the same line (including line break).
-* `<%- |parameters| -%>` - When placed as the first tag declares the template's parameters.
+The first argument to this function should be a string containing an EPP
+template. In most cases, the last argument is optional; if used, it should be a
+[hash](/puppet/latest/reference/lang_data_hash.html) that contains parameters to
+pass to the template.
 
-Inline EPP supports the following visibilities of variables in scope which depends on how EPP parameters
-are used - see further below:
+- See the [template](/puppet/latest/reference/lang_template.html) documentation
+for general template usage information.
+- See the [EPP syntax](/puppet/latest/reference/lang_template_epp.html)
+documentation for examples of EPP.
 
-* Global scope (i.e. top + node scopes) - global scope is always visible
-* Global + Enclosing scope - if the EPP template does not declare parameters, and no arguments are given
-* Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
-* Global + declared parameters - if the EPP declares parameters, given argument names must match
+For example, to evaluate an inline EPP template and pass it the `docroot` and
+`virtual_docroot` parameters, call the `inline_epp` function like this:
 
-EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example,
-`<%- |$x, $y, $z='unicorn'| -%>` when placed first in the EPP text declares that the parameters `x` and `y` must be
-given as template arguments when calling `inline_epp`, and that `z` if not given as a template argument
-defaults to `'unicorn'`. Template parameters are available as variables, e.g.arguments `$x`, `$y` and `$z` in the example.
-Note that `<%-` must be used or any leading whitespace will be interpreted as text
+`inline_epp('docroot: <%= $docroot %> Virtual docroot: <%= $virtual_docroot %>',
+{ 'docroot' => '/var/www/html', 'virtual_docroot' => '/var/www/example' })`
 
-Arguments are passed to the template by calling `inline_epp` with a Hash as the last argument, where parameters
-are bound to values, e.g. `inline_epp('...', {'x'=>10, 'y'=>20})`. Excess arguments may be given
-(i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all.
-Template parameters shadow variables in outer scopes.
+Puppet produces a syntax error if you pass more parameters than are declared in
+the template's parameter tag. When passing parameters to a template that
+contains a parameter tag, use the same names as the tag's declared parameters.
 
-Note: An inline template is best stated using a single-quoted string, or a heredoc since a double-quoted string
-is subject to expression interpolation before the string is parsed as an EPP template. Here are examples
-(using heredoc to define the EPP text):
+Parameters are required only if they are declared in the called template's
+parameter tag without default values. Puppet produces an error if the
+`inline_epp` function fails to pass any required parameter.
 
-    # produces 'Hello local variable world!'
-    $x ='local variable'
-    inline_epptemplate(@(END:epp))
-    <%- |$x| -%>
-    Hello <%= $x %> world!
-    END
+An inline EPP template should be written as a single-quoted string or
+[heredoc](puppet/latest/reference/lang_data_string.html#heredocs).
+A double-quoted string is subject to expression interpolation before the string
+is parsed as an EPP template.
 
-    # produces 'Hello given argument world!'
-    $x ='local variable world'
-    inline_epptemplate(@(END:epp), { x =>'given argument'})
-    <%- |$x| -%>
-    Hello <%= $x %> world!
-    END
+For example, to evaluate an inline EPP template using a heredoc, call the
+`inline_epp` function like this:
 
-    # produces 'Hello given argument world!'
-    $x ='local variable world'
-    inline_epptemplate(@(END:epp), { x =>'given argument'})
-    <%- |$x| -%>
-    Hello <%= $x %>!
-    END
-
-    # results in error, missing value for y
-    $x ='local variable world'
-    inline_epptemplate(@(END:epp), { x =>'given argument'})
-    <%- |$x, $y| -%>
-    Hello <%= $x %>!
-    END
-
-    # Produces 'Hello given argument planet'
-    $x ='local variable world'
-    inline_epptemplate(@(END:epp), { x =>'given argument'})
-    <%- |$x, $y=planet| -%>
-    Hello <%= $x %> <%= $y %>!
-    END
+~~~ puppet
+# Outputs 'Hello given argument planet!'
+inline_epp(@(END), { x => 'given argument' })
+<%- | $x, $y = planet | -%>
+Hello <%= $x %> <%= $y %>!
+END
+~~~
 
 - Since 3.5
-- Requires Future Parser") do |arguments|
+- Requires [future parser](/puppet/3.8/reference/experiments_future.html) in Puppet 3.5 to 3.8") do |arguments|
 
   function_fail(["inline_epp() is only available when parser/evaluator future is in effect"])
 end

data/lib/puppet/parser/functions/inline_template.rb

@@ -1,7 +1,7 @@
 Puppet::Parser::Functions::newfunction(:inline_template, :type => :rvalue, :arity => -2, :doc =>
   "Evaluate a template string and return its value.  See
-  [the templating docs](http://docs.puppetlabs.com/guides/templating.html) for
-  more information.  Note that if multiple template strings are specified, their
+  [the templating docs](http://docs.puppetlabs.com/puppet/latest/reference/lang_template.html) for
+  more information. Note that if multiple template strings are specified, their
   output is all concatenated and returned as the output of the function.") do |vals|
 
   require 'erb'

data/lib/puppet/parser/functions/map.rb

@@ -3,36 +3,71 @@ Puppet::Parser::Functions::newfunction(
   :type => :rvalue,
   :arity => -3,
   :doc => <<-DOC
-Applies a parameterized block to each element in a sequence of entries from the first
-argument and returns an array with the result of each invocation of the parameterized block.
+Applies a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+to every value in a data structure and returns an array containing the results.
 
-This function takes two mandatory arguments: the first should be an Array, Hash, or of Enumerable type
-(integer, Integer range, or String), and the second a parameterized block as produced by the puppet syntax:
+This function takes two mandatory arguments, in this order:
 
-      $a.map |$x| { ... }
-      map($a) |$x| { ... }
+1. An array or hash the function will iterate over.
+2. A lambda, which the function calls for each element in the first argument. It can
+request one or two parameters.
 
-When the first argument `$a` is an Array or of enumerable type, the block is called with each entry in turn.
-When the first argument is a hash the entry is an array with `[key, value]`.
+**Example**: Using the `map` function
 
-Example Using map with two arguments
+`$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
 
-     # Turns hash into array of values
-     $a.map |$x|{ $x[1] }
+or
 
-     # Turns hash into array of keys
-     $a.map |$x| { $x[0] }
+`$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
 
-When using a block with 2 parameters, the element's index (starting from 0) for an array, and the key for a hash
-is given to the block's first parameter, and the value is given to the block's second parameter.args.
+When the first argument (`$data` in the above example) is an array, Puppet passes each
+value in turn to the lambda.
 
-Example Using map with two arguments
+**Example**: Using the `map` function with an array and a one-parameter lambda
 
-     # Turns hash into array of values
-     $a.map |$key,$val|{ $val }
+~~~ puppet
+# For the array $data, return an array containing each value multiplied by 10
+$data = [1,2,3]
+$transformed_data = $data.map |$items| { $items * 10 }
+# $transformed_data contains [10,20,30]
+~~~
 
-     # Turns hash into array of keys
-     $a.map |$key,$val|{ $key }
+When the first argument is a hash, Puppet passes each key and value pair to the lambda
+as an array in the form `[key, value]`.
+
+**Example**: Using the `map` function with a hash and a one-parameter lambda
+
+~~~ puppet
+# For the hash $data, return an array containing the keys
+$data = {'a'=>1,'b'=>2,'c'=>3}
+$transformed_data = $data.map |$items| { $items[0] }
+# $transformed_data contains ['a','b','c']
+~~~
+
+When the first argument is an array and the lambda has two parameters, Puppet passes the
+array's indexes (enumerated from 0) in the first parameter and its values in the second
+parameter.
+
+**Example**: Using the `map` function with an array and a two-parameter lambda
+
+~~~ puppet
+# For the array $data, return an array containing the indexes
+$data = [1,2,3]
+$transformed_data = $data.map |$index,$value| { $index }
+# $transformed_data contains [0,1,2]
+~~~
+
+When the first argument is a hash, Puppet passes its keys to the first parameter and its
+values to the second parameter.
+
+**Example**: Using the `map` function with a hash and a two-parameter lambda
+
+~~~ puppet
+# For the hash $data, return an array containing each value
+$data = {'a'=>1,'b'=>2,'c'=>3}
+$transformed_data = $data.map |$key,$value| { $value }
+# $transformed_data contains [1,2,3]
+~~~
 
 - Since 4.0.0
 DOC

data/lib/puppet/parser/functions/match.rb

@@ -2,23 +2,38 @@ Puppet::Parser::Functions::newfunction(
   :match,
   :arity => 2,
   :doc => <<-DOC
-Returns the match result of matching a String or Array[String] with one of:
+Matches a regular expression against a string and returns an array containing the match
+and any matched capturing groups.
 
-* Regexp
-* String - transformed to a Regexp
-* Pattern type
-* Regexp type
+The first argument is a string or array of strings. The second argument is either a
+regular expression, regular expression represented as a string, or Regex or Pattern
+data type that the function matches against the first argument.
 
-Returns An Array with the entire match at index 0, and each subsequent submatch at index 1-n.
-If there was no match `undef` is returned. If the value to match is an Array, a array
-with mapped match results is returned.
+The returned array contains the entire match at index 0, and each captured group at
+subsequent index values. If the value or expression being matched is an array, the
+function returns an array with mapped match results.
 
-Example matching:
+If the function doesn't find a match, it returns 'undef'.
 
-  "abc123".match(/([a-z]+)[1-9]+/)    # => ["abc"]
-  "abc123".match(/([a-z]+)([1-9]+)/)  # => ["abc", "123"]
+**Example**: Matching a regular expression in a string
 
-See the documentation for "The Puppet Type System" for more information about types.
+~~~ ruby
+$matches = "abc123".match(/[a-z]+[1-9]+/)
+# $matches contains [abc123]
+~~~
+
+**Example**: Matching a regular expressions with grouping captures in a string
+
+~~~ ruby
+$matches = "abc123".match(/([a-z]+)([1-9]+)/)
+# $matches contains [abc123, abc, 123]
+~~~
+
+**Example**: Matching a regular expression with grouping captures in an array of strings
+
+~~~ ruby
+$matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
+# $matches contains [[abc123, abc, 123], [def456, def, 456]]
 
 - Since 4.0.0
 DOC