# frozen_string_literal: true # Provides stepping with given interval over elements in an iterable and optionally runs a # [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) for each # element. # # This function takes two to three arguments: # # 1. An 'Iterable' that the function will iterate over. # 2. An `Integer` step factor. This must be a positive integer. # 3. An optional lambda, which the function calls for each element in the interval. It must # request one parameter. # # @example Using the `step` function # # ```puppet # $data.step(<n>) |$parameter| { <PUPPET CODE BLOCK> } # ``` # # or # # ```puppet # $stepped_data = $data.step(<n>) # ``` # # or # # ```puppet # step($data, <n>) |$parameter| { <PUPPET CODE BLOCK> } # ``` # # or # # ```puppet # $stepped_data = step($data, <n>) # ``` # # When no block is given, Puppet returns an `Iterable` that yields the first element and every nth successor # element, from its first argument. This allows functions on iterables to be chained. # When a block is given, Puppet iterates and calls the block with the first element and then with # every nth successor element. It then returns `undef`. # # @example Using the `step` function with an array, a step factor, and a one-parameter block # # ```puppet # # For the array $data, call a block with the first element and then with each 3rd successor element # $data = [1,2,3,4,5,6,7,8] # $data.step(3) |$item| { # notice($item) # } # # Puppet notices the values '1', '4', '7'. # ``` # When no block is given, 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 `step` function chained with a `map` function. # # ```puppet # # For the array $data, return an array, set to the first element and each 5th successor element, in reverse # # order multiplied by 10 # $data = Integer[0,20] # $transformed_data = $data.step(5).map |$item| { $item * 10 } # $transformed_data contains [0,50,100,150,200] # ``` # # @example The same example using `step` function chained with a `map` in alternative syntax # # ```puppet # # For the array $data, return an array, set to the first and each 5th # # successor, in reverse order, multiplied by 10 # $data = Integer[0,20] # $transformed_data = map(step($data, 5)) |$item| { $item * 10 } # $transformed_data contains [0,50,100,150,200] # ``` # # @since 4.4.0 # Puppet::Functions.create_function(:step) do dispatch :step do param 'Iterable', :iterable param 'Integer[1]', :step end dispatch :step_block do param 'Iterable', :iterable param 'Integer[1]', :step block_param 'Callable[1,1]', :block end def step(iterable, step) # produces an Iterable Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable, true).step(step) end def step_block(iterable, step, &block) Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable).step(step, &block) nil end end