openvox 8.19.0

data/lib/puppet/pops/types/iterable.rb

@@ -0,0 +1,375 @@
+# frozen_string_literal: true
+
+module Puppet::Pops::Types
+  # Implemented by classes that can produce an iterator to iterate over their contents
+  module IteratorProducer
+    def iterator
+      raise ArgumentError, 'iterator() is not implemented'
+    end
+  end
+
+  # The runtime Iterable type for an Iterable
+  module Iterable
+    # Produces an `Iterable` for one of the following types with the following characterstics:
+    #
+    # `String`       - yields each character in the string
+    # `Array`        - yields each element in the array
+    # `Hash`         - yields each key/value pair as a two element array
+    # `Integer`      - when positive, yields each value from zero to the given number
+    # `PIntegerType` - yields each element from min to max (inclusive) provided min < max and neither is unbounded.
+    # `PEnumtype`    - yields each possible value of the enum.
+    # `Range`        - yields an iterator for all elements in the range provided that the range start and end
+    #                  are both integers or both strings and start is less than end using natural ordering.
+    # `Dir`          - yields each name in the directory
+    #
+    # An `ArgumentError` is raised for all other objects.
+    #
+    # @param my_caller [Object] The calling object to reference in errors
+    # @param obj [Object] The object to produce an `Iterable` for
+    # @param infer_elements [Boolean] Whether or not to recursively infer all elements of obj. Optional
+    #
+    # @return [Iterable,nil] The produced `Iterable`
+    # @raise [ArgumentError] In case an `Iterable` cannot be produced
+    # @api public
+    def self.asserted_iterable(my_caller, obj, infer_elements = false)
+      iter = on(obj, nil, infer_elements)
+      raise ArgumentError, "#{my_caller.class}(): wrong argument type (#{obj.class}; is not Iterable." if iter.nil?
+
+      iter
+    end
+
+    # Produces an `Iterable` for one of the following types with the following characteristics:
+    #
+    # `String`       - yields each character in the string
+    # `Array`        - yields each element in the array
+    # `Hash`         - yields each key/value pair as a two element array
+    # `Integer`      - when positive, yields each value from zero to the given number
+    # `PIntegerType` - yields each element from min to max (inclusive) provided min < max and neither is unbounded.
+    # `PEnumtype`    - yields each possible value of the enum.
+    # `Range`        - yields an iterator for all elements in the range provided that the range start and end
+    #                  are both integers or both strings and start is less than end using natural ordering.
+    # `Dir`          - yields each name in the directory
+    #
+    # The value `nil` is returned for all other objects.
+    #
+    # @param o [Object] The object to produce an `Iterable` for
+    # @param element_type [PAnyType] the element type for the iterator. Optional
+    # @param infer_elements [Boolean] if element_type is nil, whether or not to recursively
+    #   infer types for the entire collection. Optional
+    #
+    # @return [Iterable,nil] The produced `Iterable` or `nil` if it couldn't be produced
+    #
+    # @api public
+    def self.on(o, element_type = nil, infer_elements = true)
+      case o
+      when IteratorProducer
+        o.iterator
+      when Iterable
+        o
+      when String
+        Iterator.new(PStringType.new(PIntegerType.new(1, 1)), o.each_char)
+      when Array
+        if o.empty?
+          Iterator.new(PUnitType::DEFAULT, o.each)
+        else
+          if element_type.nil? && infer_elements
+            tc = TypeCalculator.singleton
+            element_type = PVariantType.maybe_create(o.map { |e| tc.infer_set(e) })
+          end
+          Iterator.new(element_type, o.each)
+        end
+      when Hash
+        # Each element is a two element [key, value] tuple.
+        if o.empty?
+          HashIterator.new(PHashType::DEFAULT_KEY_PAIR_TUPLE, o.each)
+        else
+          if element_type.nil? && infer_elements
+            tc = TypeCalculator.singleton
+            element_type =
+              PTupleType
+              .new([
+                     PVariantType.maybe_create(o.keys.map { |e| tc.infer_set(e) }),
+                     PVariantType.maybe_create(o.values.map { |e| tc.infer_set(e) })
+                   ],
+                   PHashType::KEY_PAIR_TUPLE_SIZE)
+          end
+          HashIterator.new(element_type, o.each_pair)
+        end
+      when Integer
+        if o == 0
+          Iterator.new(PUnitType::DEFAULT, o.times)
+        elsif o > 0
+          IntegerRangeIterator.new(PIntegerType.new(0, o - 1))
+        else
+          nil
+        end
+      when PIntegerType
+        # a finite range will always produce at least one element since it's inclusive
+        o.finite_range? ? IntegerRangeIterator.new(o) : nil
+      when PEnumType
+        Iterator.new(o, o.values.each)
+      when PTypeAliasType
+        on(o.resolved_type)
+      when Range
+        min = o.min
+        max = o.max
+        if min.is_a?(Integer) && max.is_a?(Integer) && max >= min
+          IntegerRangeIterator.new(PIntegerType.new(min, max))
+        elsif min.is_a?(String) && max.is_a?(String) && max >= min
+          # A generalized element type where only the size is inferred is used here since inferring the full
+          # range might waste a lot of memory.
+          if min.length < max.length
+            shortest = min
+            longest = max
+          else
+            shortest = max
+            longest = min
+          end
+          Iterator.new(PStringType.new(PIntegerType.new(shortest.length, longest.length)), o.each)
+        else
+          # Unsupported range. It's either descending or nonsensical for other reasons (float, mixed types, etc.)
+          nil
+        end
+      else
+        # Not supported. We cannot determine the element type
+        nil
+      end
+    end
+
+    # Answers the question if there is an end to the iteration. Puppet does not currently provide any unbounded
+    # iterables.
+    #
+    # @return [Boolean] `true` if the iteration is unbounded
+    def self.unbounded?(object)
+      case object
+      when Iterable
+        object.unbounded?
+      when String, Integer, Array, Hash, Enumerator, PIntegerType, PEnumType, Dir
+        false
+      else
+        TypeAsserter.assert_instance_of('', PIterableType::DEFAULT, object, false)
+        !object.respond_to?(:size)
+      end
+    end
+
+    def each(&block)
+      step(1, &block)
+    end
+
+    def element_type
+      PAnyType::DEFAULT
+    end
+
+    def reverse_each(&block)
+      # Default implementation cannot propagate reverse_each to a new enumerator so chained
+      # calls must put reverse_each last.
+      raise ArgumentError, 'reverse_each() is not implemented'
+    end
+
+    def step(step, &block)
+      # Default implementation cannot propagate step to a new enumerator so chained
+      # calls must put stepping last.
+      raise ArgumentError, 'step() is not implemented'
+    end
+
+    def to_a
+      raise Puppet::Error, 'Attempt to create an Array from an unbounded Iterable' if unbounded?
+
+      super
+    end
+
+    def hash_style?
+      false
+    end
+
+    def unbounded?
+      true
+    end
+  end
+
+  # @api private
+  class Iterator
+    # Note! We do not include Enumerable module here since that would make this class respond
+    # in a bad way to all enumerable methods. We want to delegate all those calls directly to
+    # the contained @enumeration
+    include Iterable
+
+    def initialize(element_type, enumeration)
+      @element_type = element_type
+      @enumeration = enumeration
+    end
+
+    def element_type
+      @element_type
+    end
+
+    def size
+      @enumeration.size
+    end
+
+    def respond_to_missing?(name, include_private)
+      @enumeration.respond_to?(name, include_private)
+    end
+
+    def method_missing(name, *arguments, &block)
+      @enumeration.send(name, *arguments, &block)
+    end
+
+    def next
+      @enumeration.next
+    end
+
+    def map(*args, &block)
+      @enumeration.map(*args, &block)
+    end
+
+    def reduce(*args, &block)
+      @enumeration.reduce(*args, &block)
+    end
+
+    def all?(&block)
+      @enumeration.all?(&block)
+    end
+
+    def any?(&block)
+      @enumeration.any?(&block)
+    end
+
+    def step(step, &block)
+      raise ArgumentError if step <= 0
+
+      r = self
+      r = r.step_iterator(step) if step > 1
+
+      if block_given?
+        begin
+          if block.arity == 1
+            loop { yield(r.next) }
+          else
+            loop { yield(*r.next) }
+          end
+        rescue StopIteration
+        end
+        self
+      else
+        r
+      end
+    end
+
+    def reverse_each(&block)
+      r = Iterator.new(@element_type, @enumeration.reverse_each)
+      block_given? ? r.each(&block) : r
+    end
+
+    def step_iterator(step)
+      StepIterator.new(@element_type, self, step)
+    end
+
+    def to_s
+      et = element_type
+      et.nil? ? 'Iterator-Value' : "Iterator[#{et.generalize}]-Value"
+    end
+
+    def unbounded?
+      Iterable.unbounded?(@enumeration)
+    end
+  end
+
+  # Special iterator used when iterating over hashes. Returns `true` for `#hash_style?` so that
+  # it is possible to differentiate between two element arrays and key => value associations
+  class HashIterator < Iterator
+    def hash_style?
+      true
+    end
+  end
+
+  # @api private
+  class StepIterator < Iterator
+    include Enumerable
+
+    def initialize(element_type, enumeration, step_size)
+      super(element_type, enumeration)
+      raise ArgumentError if step_size <= 0
+
+      @step_size = step_size
+    end
+
+    def next
+      result = @enumeration.next
+      skip = @step_size - 1
+      if skip > 0
+        begin
+          skip.times { @enumeration.next }
+        rescue StopIteration
+        end
+      end
+      result
+    end
+
+    def reverse_each(&block)
+      r = Iterator.new(@element_type, to_a.reverse_each)
+      block_given? ? r.each(&block) : r
+    end
+
+    def size
+      super / @step_size
+    end
+  end
+
+  # @api private
+  class IntegerRangeIterator < Iterator
+    include Enumerable
+
+    def initialize(range, step = 1)
+      raise ArgumentError if step == 0
+
+      @range = range
+      @step_size = step
+      @current = (step < 0 ? range.to : range.from) - step
+    end
+
+    def element_type
+      @range
+    end
+
+    def next
+      value = @current + @step_size
+      if @step_size < 0
+        raise StopIteration if value < @range.from
+      elsif value > @range.to
+        raise StopIteration
+      end
+      @current = value
+    end
+
+    def reverse_each(&block)
+      r = IntegerRangeIterator.new(@range, -@step_size)
+      block_given? ? r.each(&block) : r
+    end
+
+    def size
+      (@range.to - @range.from) / @step_size.abs
+    end
+
+    def step_iterator(step)
+      # The step iterator must use a range that has its logical end truncated at an even step boundary. This will
+      # fulfil two objectives:
+      # 1. The element_type method should not report excessive integers as possible numbers
+      # 2. A reversed iterator must start at the correct number
+      #
+      range = @range
+      step = @step_size * step
+      mod = (range.to - range.from) % step
+      if mod < 0
+        range = PIntegerType.new(range.from - mod, range.to)
+      elsif mod > 0
+        range = PIntegerType.new(range.from, range.to - mod)
+      end
+      IntegerRangeIterator.new(range, step)
+    end
+
+    def unbounded?
+      false
+    end
+  end
+end

data/lib/puppet/pops/types/p_binary_type.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'base64'
+module Puppet::Pops
+module Types
+# A Puppet Language Type that represents binary data content (a sequence of 8-bit bytes).
+# Instances of this data type can be created from `String` and `Array[Integer[0,255]]`
+# values. Also see the `binary_file` function for reading binary content from a file.
+#
+# A `Binary` can be converted to `String` and `Array` form - see function `new` for
+# the respective target data type for more information.
+#
+# Instances of this data type serialize as base 64 encoded strings when the serialization
+# format is textual, and as binary content when a serialization format supports this.
+#
+# @api public
+class PBinaryType < PAnyType
+  # Represents a binary buffer
+  # @api public
+  class Binary
+    attr_reader :binary_buffer
+
+    # Constructs an instance of Binary from a base64 urlsafe encoded string (RFC 2045).
+    # @param [String] A string with RFC 2045 compliant encoded binary
+    #
+    def self.from_base64(str)
+      new(Base64.decode64(str))
+    end
+
+    # Constructs an instance of Binary from a base64 encoded string (RFC4648 with "URL and Filename
+    # Safe Alphabet" (That is with '-' instead of '+', and '_' instead of '/').
+    #
+    def self.from_base64_urlsafe(str)
+      new(Base64.urlsafe_decode64(str))
+    end
+
+    # Constructs an instance of Binary from a base64 strict encoded string (RFC 4648)
+    # Where correct padding must be used and line breaks causes an error to be raised.
+    #
+    # @param [String] A string with RFC 4648 compliant encoded binary
+    #
+    def self.from_base64_strict(str)
+      new(Base64.strict_decode64(str))
+    end
+
+    # Creates a new Binary from a String containing binary data. If the string's encoding
+    # is not already ASCII-8BIT, a copy of the string is force encoded as ASCII-8BIT (that is Ruby's "binary" format).
+    # This means that this binary will have the exact same content, but the string will considered
+    # to hold a sequence of bytes in the range 0 to 255.
+    #
+    # The given string will be frozen as a side effect if it is in ASCII-8BIT encoding. If this is not
+    # wanted, a copy should be given to this method.
+    #
+    # @param [String] A string with binary data
+    # @api public
+    #
+    def self.from_binary_string(bin)
+      new(bin)
+    end
+
+    # Creates a new Binary from a String containing text/binary in its given encoding. If the string's encoding
+    # is not already UTF-8, the string is first transcoded to UTF-8.
+    # This means that this binary will have the UTF-8 byte representation of the original string.
+    # For this to be valid, the encoding used in the given string must be valid.
+    # The validity of the given string is therefore asserted.
+    #
+    # The given string will be frozen as a side effect if it is in ASCII-8BIT encoding. If this is not
+    # wanted, a copy should be given to this method.
+    #
+    # @param [String] A string with valid content in its given encoding
+    # @return [Puppet::Pops::Types::PBinaryType::Binary] with the UTF-8 representation of the UTF-8 transcoded string
+    # @api public
+    #
+    def self.from_string(encoded_string)
+      enc = encoded_string.encoding.name
+      unless encoded_string.valid_encoding?
+        raise ArgumentError, _("The given string in encoding '%{enc}' is invalid. Cannot create a Binary UTF-8 representation") % { enc: enc }
+      end
+
+      # Convert to UTF-8 (if not already UTF-8), and then to binary
+      encoded_string = (enc == "UTF-8") ? encoded_string.dup : encoded_string.encode('UTF-8')
+      encoded_string.force_encoding("ASCII-8BIT")
+      new(encoded_string)
+    end
+
+    # Creates a new Binary from a String containing raw binary data of unknown encoding. If the string's encoding
+    # is not already ASCII-8BIT, a copy of the string is forced to ASCII-8BIT (that is Ruby's "binary" format).
+    # This means that this binary will have the exact same content, but the string will considered
+    # to hold a sequence of bytes in the range 0 to 255.
+    #
+    # @param [String] A string with binary data
+    # @api private
+    #
+    def initialize(bin)
+      @binary_buffer = (bin.encoding.name == "ASCII-8BIT" ? bin : bin.b).freeze
+    end
+
+    # Presents the binary content as a string base64 encoded string (without line breaks).
+    #
+    def to_s
+      Base64.strict_encode64(@binary_buffer)
+    end
+
+    # Returns the binary content as a "relaxed" base64 (standard) encoding where
+    # the string is broken up with new lines.
+    def relaxed_to_s
+      Base64.encode64(@binary_buffer)
+    end
+
+    # Returns the binary content as a url safe base64 string (where + and / are replaced by - and _)
+    #
+    def urlsafe_to_s
+      Base64.urlsafe_encode64(@binary_buffer)
+    end
+
+    def hash
+      @binary_buffer.hash
+    end
+
+    def eql?(o)
+      self.class == o.class && @binary_buffer == o.binary_buffer
+    end
+
+    def ==(o)
+      eql?(o)
+    end
+
+    def length
+      @binary_buffer.length
+    end
+  end
+
+  def self.register_ptype(loader, ir)
+    create_ptype(loader, ir, 'AnyType')
+  end
+
+  # Only instances of Binary are instances of the PBinaryType
+  #
+  def instance?(o, guard = nil)
+    o.is_a?(Binary)
+  end
+
+  def eql?(o)
+    self.class == o.class
+  end
+
+  # Binary uses the strict base64 format as its string representation
+  # @return [TrueClass] true
+  def roundtrip_with_string?
+    true
+  end
+
+  # @api private
+  def self.new_function(type)
+    @new_function ||= Puppet::Functions.create_loaded_function(:new_Binary, type.loader) do
+      local_types do
+        type 'ByteInteger = Integer[0,255]'
+        type 'Base64Format = Enum["%b", "%u", "%B", "%s", "%r"]'
+        type 'StringHash = Struct[{value => String, "format" => Optional[Base64Format]}]'
+        type 'ArrayHash = Struct[{value => Array[ByteInteger]}]'
+        type 'BinaryArgsHash = Variant[StringHash, ArrayHash]'
+      end
+
+      # Creates a binary from a base64 encoded string in one of the formats %b, %u, %B, %s, or %r
+      dispatch :from_string do
+        param 'String', :str
+        optional_param 'Base64Format', :format
+      end
+
+      dispatch :from_array do
+        param 'Array[ByteInteger]', :byte_array
+      end
+
+      # Same as from_string, or from_array, but value and (for string) optional format are given in the form
+      # of a hash.
+      #
+      dispatch :from_hash do
+        param 'BinaryArgsHash', :hash_args
+      end
+
+      def from_string(str, format = nil)
+        format ||= '%B'
+        case format
+        when "%b"
+          # padding must be added for older rubies to avoid truncation
+          padding = '=' * (str.length % 3)
+          Binary.new(Base64.decode64(str + padding))
+
+        when "%u"
+          Binary.new(Base64.urlsafe_decode64(str))
+
+        when "%B"
+          Binary.new(Base64.strict_decode64(str))
+
+        when "%s"
+          Binary.from_string(str)
+
+        when "%r"
+          Binary.from_binary_string(str)
+
+        else
+          raise ArgumentError, "Unsupported Base64 format '#{format}'"
+        end
+      end
+
+      def from_array(array)
+        # The array is already known to have bytes in the range 0-255, or it is in error
+        # Without this pack C would produce weird results
+        Binary.from_binary_string(array.pack("C*"))
+      end
+
+      def from_hash(hash)
+        case hash['value']
+        when Array
+          from_array(hash['value'])
+        when String
+          from_string(hash['value'], hash['format'])
+        end
+      end
+    end
+  end
+
+  DEFAULT = PBinaryType.new
+
+  protected
+
+  def _assignable?(o, guard)
+    o.instance_of?(self.class)
+  end
+end
+end
+end