openvox 8.19.0

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :next,
+  :arity => -2,
+  :doc => <<~DOC
+    Immediately returns the given optional value from a block (lambda), function, class body or user defined type body.
+    If a value is not given, an `undef` value is returned. This function does not return to the immediate caller.
+
+    The signal produced to return a value bubbles up through
+    the call stack until reaching a code block (lambda), function, class definition or
+    definition of a user defined type at which point the value given to the function will
+    be produced as the result of that body of code. An error is raised
+    if the signal to return a value reaches the end of the call stack.
+
+    **Example:** Using `next` in `each`
+
+    ```puppet
+    $data = [1,2,3]
+    $data.each |$x| { if $x == 2 { next() } notice $x }
+    ```
+
+    Would notice the values `1` and `3`
+
+    **Example:** Using `next` to produce a value
+
+    If logic consists of deeply nested conditionals it may be complicated to get out of the innermost conditional.
+    A call to `next` can then simplify the logic. This example however, only shows the principle.
+    ```puppet
+    $data = [1,2,3]
+    notice $data.map |$x| { if $x == 2 { next($x*100) }; $x*10 }
+    ```
+    Would notice the value `[10, 200, 30]`
+
+    * Also see functions `return` and `break`
+    * Since 4.8.0
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('next')
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# This is just syntactic sugar for a collection, although it will generally
+# be a good bit faster.
+
+Puppet::Parser::Functions.newfunction(:realize, :arity => -2, :doc => "Make a virtual object real.  This is useful
+    when you want to know the name of the virtual object and don't want to
+    bother with a full collection.  It is slightly faster than a collection,
+    and, of course, is a bit shorter.  You must pass the object using a
+    reference; e.g.: `realize User[luke]`.") do |vals|
+  if Puppet[:tasks]
+    raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+      Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+      { :operation => 'realize' }
+    )
+  end
+
+  vals = [vals] unless vals.is_a?(Array)
+
+  coll = Puppet::Pops::Evaluator::Collectors::FixedSetCollector.new(self, vals.flatten)
+  compiler.add_collection(coll)
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :reduce,
+  :type => :rvalue,
+  :arity => -3,
+  :doc => <<~DOC
+    Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+    to every value in a data structure from the first argument, carrying over the returned
+    value of each iteration, and returns the result of the lambda's final iteration. This
+    lets you create a new value or data structure by combining values from the first
+    argument's data structure.
+
+    This function takes two mandatory arguments, in this order:
+
+    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 takes
+    two mandatory parameters:
+        1. A memo value that is overwritten after each iteration with the iteration's result.
+        2. A second value that is overwritten after each iteration with the next value in the
+        function's first argument.
+
+    **Example**: Using the `reduce` function
+
+    `$data.reduce |$memo, $value| { ... }`
+
+    or
+
+    `reduce($data) |$memo, $value| { ... }`
+
+    You can also pass an optional "start memo" value as an argument, such as `start` below:
+
+    `$data.reduce(start) |$memo, $value| { ... }`
+
+    or
+
+    `reduce($data, start) |$memo, $value| { ... }`
+
+    When the first argument (`$data` in the above example) is an array, Puppet passes each
+    of the data structure's values in turn to the lambda's parameters. When the first
+    argument is a hash, Puppet converts each of the hash's values to an array in the form
+    `[key, value]`.
+
+    If you pass a start memo value, Puppet executes the lambda with the provided memo value
+    and the data structure's first value. Otherwise, Puppet passes the structure's first two
+    values to the lambda.
+
+    Puppet calls the lambda for each of the data structure's remaining values. For each
+    call, it passes the result of the previous call as the first parameter ($memo in the
+    above examples) and the next value from the data structure as the second parameter
+    ($value).
+
+    If the structure has one value, Puppet returns the value and does not call the lambda.
+
+    **Example**: Using the `reduce` function
+
+    ~~~ puppet
+    # Reduce the array $data, returning the sum of all values in the array.
+    $data = [1, 2, 3]
+    $sum = $data.reduce |$memo, $value| { $memo + $value }
+    # $sum contains 6
+
+    # Reduce the array $data, returning the sum of a start memo value and all values in the
+    # array.
+    $data = [1, 2, 3]
+    $sum = $data.reduce(4) |$memo, $value| { $memo + $value }
+    # $sum contains 10
+
+    # Reduce the hash $data, returning the sum of all values and concatenated string of all
+    # keys.
+    $data = {a => 1, b => 2, c => 3}
+    $combine = $data.reduce |$memo, $value| {
+      $string = "${memo[0]}${value[0]}"
+      $number = $memo[1] + $value[1]
+      [$string, $number]
+    }
+    # $combine contains [abc, 6]
+    ~~~
+
+    **Example**: Using the `reduce` function with a start memo and two-parameter lambda
+
+    ~~~ puppet
+    # Reduce the array $data, returning the sum of all values in the array and starting
+    # with $memo set to an arbitrary value instead of $data's first value.
+    $data = [1, 2, 3]
+    $sum = $data.reduce(4) |$memo, $value| { $memo + $value }
+    # At the start of the lambda's first iteration, $memo contains 4 and $value contains 1.
+    # After all iterations, $sum contains 10.
+
+    # Reduce the hash $data, returning the sum of all values and concatenated string of
+    # all keys, and starting with $memo set to an arbitrary array instead of $data's first
+    # key-value pair.
+    $data = {a => 1, b => 2, c => 3}
+    $combine = $data.reduce( [d, 4] ) |$memo, $value| {
+      $string = "${memo[0]}${value[0]}"
+      $number = $memo[1] + $value[1]
+      [$string, $number]
+    }
+    # At the start of the lambda's first iteration, $memo contains [d, 4] and $value
+    # contains [a, 1].
+    # $combine contains [dabc, 10]
+    ~~~
+
+    **Example**: Using the `reduce` function to reduce a hash of hashes
+
+    ~~~ puppet
+    # Reduce a hash of hashes $data, merging defaults into the inner hashes.
+    $data = {
+      'connection1' => {
+        'username' => 'user1',
+        'password' => 'pass1',
+      },
+      'connection_name2' => {
+        'username' => 'user2',
+        'password' => 'pass2',
+      },
+    }
+
+    $defaults = {
+      'maxActive' => '20',
+      'maxWait'   => '10000',
+      'username'  => 'defaultuser',
+      'password'  => 'defaultpass',
+    }
+
+    $merged = $data.reduce( {} ) |$memo, $x| {
+      $memo + { $x[0] => $defaults + $data[$x[0]] }
+    }
+    # At the start of the lambda's first iteration, $memo is set to {}, and $x is set to
+    # the first [key, value] tuple. The key in $data is, therefore, given by $x[0]. In
+    # subsequent rounds, $memo retains the value returned by the expression, i.e.
+    # $memo + { $x[0] => $defaults + $data[$x[0]] }.
+    ~~~
+
+    - Since 4.0.0
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('reduce')
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2009 Thomas Bellman
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THOMAS BELLMAN BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+#
+# Except as contained in this notice, the name of Thomas Bellman shall
+# not be used in advertising or otherwise to promote the sale, use or
+# other dealings in this Software without prior written authorization
+# from Thomas Bellman.
+
+module Puppet::Parser::Functions
+  newfunction(
+    :regsubst, :type => :rvalue,
+               :arity => -4,
+
+               :doc => "
+Perform regexp replacement on a string or array of strings.
+
+* *Parameters* (in order):
+    * _target_  The string or array of strings to operate on.  If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array.
+    * _regexp_  The regular expression matching the target string.  If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself.
+    * _replacement_  Replacement string. Can contain backreferences to what was matched using \\0 (whole match), \\1 (first set of parentheses), and so on.
+    * _flags_  Optional. String of single letter flags for how the regexp is interpreted:
+        - *E*         Extended regexps
+        - *I*         Ignore case in regexps
+        - *M*         Multiline regexps
+        - *G*         Global replacement; all occurrences of the regexp in each target string will be replaced.  Without this, only the first occurrence will be replaced.
+    * _encoding_  Optional.  How to handle multibyte characters.  A single-character string with the following values:
+        - *N*         None
+        - *E*         EUC
+        - *S*         SJIS
+        - *U*         UTF-8
+
+* *Examples*
+
+Get the third octet from the node's IP address:
+
+    $i3 = regsubst($ipaddress,'^(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$','\\3')
+
+Put angle brackets around each octet in the node's IP address:
+
+    $x = regsubst($ipaddress, '([0-9]+)', '<\\1>', 'G')
+"
+  ) do |_args|
+    Error.is4x('regsubst')
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Requires the specified classes
+
+Puppet::Parser::Functions.newfunction(
+  :require,
+  :arity => -2,
+  :doc => "Evaluate one or more classes,  adding the required class as a dependency.
+
+The relationship metaparameters work well for specifying relationships
+between individual resources, but they can be clumsy for specifying
+relationships between classes.  This function is a superset of the
+'include' function, adding a class relationship so that the requiring
+class depends on the required class.
+
+Warning: using require in place of include can lead to unwanted dependency cycles.
+
+For instance the following manifest, with 'require' instead of 'include' would produce a nasty dependence cycle, because notify imposes a before between File[/foo] and Service[foo]:
+
+    class myservice {
+      service { foo: ensure => running }
+    }
+
+    class otherstuff {
+      include myservice
+      file { '/foo': notify => Service[foo] }
+    }
+
+Note that this function only works with clients 0.25 and later, and it will
+fail if used with earlier clients.
+
+You must use the class's full name;
+relative names are not allowed. In addition to names in string form,
+you may also directly use Class and Resource Type values that are produced when evaluating
+resource and relationship expressions.
+
+- Since 4.0.0 Class and Resource types, absolute names
+- Since 4.7.0 Returns an Array[Type[Class]] with references to the required classes
+"
+) do |classes|
+  call_function('require', classes)
+  Puppet.warn_once('deprecations', '3xfunction#require', _("Calling function_require via the Scope class is deprecated. Use Scope#call_function instead"))
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :return,
+  :arity => -2,
+  :doc => <<~DOC
+    Immediately returns the given optional value from a function, class body or user defined type body.
+    If a value is not given, an `undef` value is returned. This function does not return to the immediate caller.
+    If this function is called from within a lambda, the return action is from the scope of the
+    function containing the lambda (top scope), not the function accepting the lambda (local scope).
+
+    The signal produced to return a value bubbles up through
+    the call stack until reaching a function, class definition or
+    definition of a user defined type at which point the value given to the function will
+    be produced as the result of that body of code. An error is raised
+    if the signal to return a value reaches the end of the call stack.
+
+    **Example:** Using `return`
+
+    ```puppet
+    function example($x) {
+      # handle trivial cases first for better readability of
+      # what follows
+      if $x == undef or $x == [] or $x == '' {
+        return false
+      }
+      # complex logic to determine if value is true
+      true
+    }
+    notice example([]) # would notice false
+    notice example(42) # would notice true
+    ```
+
+    **Example:** Using `return` in a class
+
+    ```puppet
+    class example($x) {
+      # handle trivial cases first for better readability of
+      # what follows
+      if $x == undef or $x == [] or $x == '' {
+        # Do some default configuration of this class
+        notice 'foo'
+        return()
+      }
+      # complex logic configuring the class if something more interesting
+      # was given in $x
+      notice 'bar'
+    }
+    ```
+
+    When used like this:
+
+    ```puppet
+    class { example: x => [] }
+    ```
+
+    The code would notice `'foo'`, but not `'bar'`.
+
+    When used like this:
+
+    ```puppet
+    class { example: x => [some_value] }
+    ```
+
+    The code would notice `'bar'` but not `'foo'`
+
+    Note that the returned value is ignored if used in a class or user defined type.
+
+    **Example:** Using `return` in a lambda
+
+    ```puppet
+    # Concatenate three strings into a single string formatted as a list.
+    function getFruit() {
+      with("apples", "oranges", "bananas") |$x, $y, $z| {
+        return("${x}, ${y}, and ${z}")
+      }
+      notice "not reached"
+    }
+    $fruit = getFruit()
+    notice $fruit
+
+    # The output contains "apples, oranges, and bananas".
+    # "not reached" is not output because the function returns its value within the
+    # calling function's scope, which stops processing the calling function before
+    # the `notice "not reached"` statement.
+    # Using `return()` outside of a calling function results in an error.
+    ```
+
+    * Also see functions `return` and `break`
+    * Since 4.8.0
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('return')
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :reverse_each,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<~DOC
+    Reverses the order of the elements of something that is iterable and optionally runs a
+    [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) for each
+    element.
+
+    This function takes one to two arguments:
+
+    1. An `Iterable` that the function will iterate over.
+    2. An optional lambda, which the function calls for each element in the first argument. It must
+       request one parameter.
+
+    **Example:** Using the `reverse_each` function
+
+    ```puppet
+    $data.reverse_each |$parameter| { <PUPPET CODE BLOCK> }
+    ```
+
+    or
+
+    ```puppet
+    $reverse_data = $data.reverse_each
+    ```
+
+    or
+
+    ```puppet
+    reverse_each($data) |$parameter| { <PUPPET CODE BLOCK> }
+    ```
+
+    or
+
+    ```puppet
+    $reverse_data = reverse_each($data)
+    ```
+
+    When no second argument is present, Puppet returns an `Iterable` that represents the reverse
+    order of its first argument. This allows methods on `Iterable` to be chained.
+
+    When a lambda is given as the second argument, Puppet iterates the first argument in reverse
+    order and passes each value in turn to the lambda, then returns `undef`.
+
+    **Example:** Using the `reverse_each` function with an array and a one-parameter lambda
+
+    ``` puppet
+    # Puppet will log a notice for each of the three items
+    # in $data in reverse order.
+    $data = [1,2,3]
+    $data.reverse_each |$item| { notice($item) }
+    ```
+
+    When no second argument is present, Puppet returns a new `Iterable` which allows it to
+    be directly chained into another function that takes an `Iterable` as an argument.
+
+    **Example:** Using the `reverse_each` function chained with a `map` function.
+
+    ```puppet
+    # For the array $data, return an array containing each
+    # value multiplied by 10 in reverse order
+    $data = [1,2,3]
+    $transformed_data = $data.reverse_each.map |$item| { $item * 10 }
+    # $transformed_data is set to [30,20,10]
+    ```
+
+    **Example:** Using `reverse_each` function chained with a `map` in alternative syntax
+
+    ```puppet
+    # For the array $data, return an array containing each
+    # value multiplied by 10 in reverse order
+    $data = [1,2,3]
+    $transformed_data = map(reverse_each($data)) |$item| { $item * 10 }
+    # $transformed_data is set to [30,20,10]
+    ```
+
+    * Since 4.4.0
+
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('reverse_each')
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'scanf'
+
+Puppet::Parser::Functions.newfunction(
+  :scanf,
+  :type => :rvalue,
+  :arity => 2,
+  :doc => <<~DOC
+    Scans a string and returns an array of one or more converted values based on the given format string.
+    See the documentation of Ruby's String#scanf method for details about the supported formats (which
+    are similar but not identical to the formats used in Puppet's `sprintf` function.)
+
+    This function takes two mandatory arguments: the first is the string to convert, and the second is
+    the format string. The result of the scan is an array, with each successfully scanned and transformed value.
+    The scanning stops if a scan is unsuccessful, and the scanned result up to that point is returned. If there
+    was no successful scan, the result is an empty array.
+
+    ```puppet
+    "42".scanf("%i")
+    ```
+
+    You can also optionally pass a lambda to scanf, to do additional validation or processing.
+
+    ```puppet
+    "42".scanf("%i") |$x| {
+      unless $x[0] =~ Integer {
+        fail "Expected a well formed integer value, got '$x[0]'"
+      }
+      $x[0]
+    }
+    ```
+
+    - Since 4.0.0
+  DOC
+) do |args|
+  data = args[0]
+  format = args[1]
+  data.scanf(format)
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+Puppet::Parser::Functions.newfunction(:sha1, :type => :rvalue, :arity => 1, :doc => "Returns a SHA1 hash value from a provided string.") do |args|
+  Digest::SHA1.hexdigest(args[0])
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'digest/sha2'
+
+Puppet::Parser::Functions.newfunction(:sha256, :type => :rvalue, :arity => 1, :doc => "Returns a SHA256 hash value from a provided string.") do |args|
+  Digest::SHA256.hexdigest(args[0])
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2009 Thomas Bellman
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THOMAS BELLMAN BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+#
+# Except as contained in this notice, the name of Thomas Bellman shall
+# not be used in advertising or otherwise to promote the sale, use or
+# other dealings in this Software without prior written authorization
+# from Thomas Bellman.
+
+Puppet::Parser::Functions.newfunction(:shellquote, :type => :rvalue, :arity => -1, :doc => "\
+    Quote and concatenate arguments for use in Bourne shell.
+
+    Each argument is quoted separately, and then all are concatenated
+    with spaces.  If an argument is an array, the elements of that
+    array is interpolated within the rest of the arguments; this makes
+    it possible to have an array of arguments and pass that array to
+    shellquote instead of having to specify each argument
+    individually in the call.
+    ") \
+do |args|
+  safe = 'a-zA-Z0-9@%_+=:,./-'    # Safe unquoted
+  dangerous = '!"`$\\'            # Unsafe inside double quotes
+
+  result = []
+  args.flatten.each do |word|
+    if word.length != 0 and word.count(safe) == word.length
+      result << word
+    elsif word.count(dangerous) == 0
+      result << ('"' + word + '"')
+    elsif word.count("'") == 0
+      result << ("'" + word + "'")
+    else
+      r = '"'
+      word.each_byte do |c|
+        r += "\\" if dangerous.include?(c.chr)
+        r += c.chr
+      end
+      r += '"'
+      result << r
+    end
+  end
+
+  return result.join(" ")
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :slice,
+  :type => :rvalue,
+  :arity => -3,
+  :doc => <<~DOC
+    This function takes two mandatory arguments: the first should be an array or hash, and the second specifies
+    the number of elements to include in each slice.
+
+    When the first argument is a hash, each key value pair is counted as one. For example, a slice size of 2 will produce
+    an array of two arrays with key, and value.
+
+        $a.slice(2) |$entry|          { notice "first ${$entry[0]}, second ${$entry[1]}" }
+        $a.slice(2) |$first, $second| { notice "first ${first}, second ${second}" }
+
+    The function produces a concatenated result of the slices.
+
+        slice([1,2,3,4,5,6], 2) # produces [[1,2], [3,4], [5,6]]
+        slice(Integer[1,6], 2)  # produces [[1,2], [3,4], [5,6]]
+        slice(4,2)              # produces [[0,1], [2,3]]
+        slice('hello',2)        # produces [[h, e], [l, l], [o]]
+
+    You can also optionally pass a lambda to slice.
+
+        $a.slice($n) |$x| { ... }
+        slice($a) |$x| { ... }
+
+    The lambda should have either one parameter (receiving an array with the slice), or the same number
+    of parameters as specified by the slice size (each parameter receiving its part of the slice).
+    If there are fewer remaining elements than the slice size for the last slice, it will contain the remaining
+    elements. If the lambda has multiple parameters, excess parameters are set to undef for an array, or
+    to empty arrays for a hash.
+
+        $a.slice(2) |$first, $second| { ... }
+
+    - Since 4.0.0
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('slice')
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Puppet::Parser::Functions
+  newfunction(
+    :split, :type => :rvalue,
+            :arity => 2,
+
+            :doc => "\
+Split a string variable into an array using the specified split regexp.
+
+*Example:*
+
+    $string     = 'v1.v2:v3.v4'
+    $array_var1 = split($string, ':')
+    $array_var2 = split($string, '[.]')
+    $array_var3 = split($string, Regexp['[.:]'])
+
+`$array_var1` now holds the result `['v1.v2', 'v3.v4']`,
+while `$array_var2` holds `['v1', 'v2:v3', 'v4']`, and
+`$array_var3` holds `['v1', 'v2', 'v3', 'v4']`.
+
+Note that in the second example, we split on a literal string that contains
+a regexp meta-character (.), which must be escaped.  A simple
+way to do that for a single character is to enclose it in square
+brackets; a backslash will also escape a single character."
+  ) do |_args|
+    Error.is4x('split')
+  end
+end