ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/binary/ctypes/scalar_type.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/binary/ctypes/type'
+
+module Ronin
+  module Support
+    module Binary
+      module CTypes
+        #
+        # Base class for all scalar types.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        class ScalarType < Type
+
+          # The size in bytes of the type.
+          #
+          # @return [1, 2, 4, 8]
+          attr_reader :size
+
+          # The alignment in bytes for the scalar type.
+          #
+          # @return [Integer]
+          attr_reader :alignment
+
+          # The endian-ness of the type.
+          #
+          # @return [:little, :big, nil]
+          attr_reader :endian
+
+          # Indicates whether the type is signed.
+          #
+          # @return [Boolean]
+          attr_reader :signed
+
+          #
+          # Initializes the scalar type.
+          #
+          # @param [1, 2, 4, 8] size
+          #   The scalar type's size in bytes.
+          #
+          # @param [Integer, nil] alignment
+          #   Optional custom alignment for the scalar type.
+          #
+          # @param [:little, :big, nil] endian
+          #   The endianness of the scalar type. `nil` indicates the type has no
+          #   endianness.
+          #
+          # @param [Boolean] signed
+          #   Indicates whether the scalar type is signed or unsigned.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments.
+          #
+          # @option kwargs [String] :pack_string
+          #   The String for `Array#pack` or `String#unpack`.
+          #
+          def initialize(size: , alignment: size, endian: , signed: , **kwargs)
+            super(**kwargs)
+
+            @endian    = endian
+            @size      = size
+            @alignment = alignment
+            @signed    = signed
+          end
+
+          # 
+          # Whether the scalar type is signed.
+          #
+          # @return [Boolean]
+          #
+          def signed?
+            @signed
+          end
+
+          # 
+          # Whether the scalar type is unsigned.
+          #
+          # @return [Boolean]
+          #
+          def unsigned?
+            !@signed
+          end
+
+          #
+          # Creates a copy of the scalar type with a different {#alignment}.
+          #
+          # @param [Integer] new_alignment
+          #   The new alignment for the new scalar type.
+          #
+          # @return [ScalarType]
+          #   The new scalar type.
+          #
+          def align(new_alignment)
+            self.class.new(
+              size:        @size,
+              alignment:   new_alignment,
+              endian:      @endian,
+              signed:      @signed,
+              pack_string: @pack_string
+            )
+          end
+
+          #
+          # Packs the value into the scalar type's binary format.
+          #
+          # @param [Integer, Float, String] value
+          #   The value to pack.
+          #
+          # @return [String]
+          #   The packed binary data.
+          #
+          # @raise [NotImplementedError]
+          #   {#pack_string} was not set.
+          #
+          # @api public
+          #
+          def pack(value)
+            if @pack_string
+              [value].pack(@pack_string)
+            else
+              raise(NotImplementedError,"#{self.class} does not define a #pack_string")
+            end
+          end
+
+          #
+          # Unpacks the binary data.
+          #
+          # @param [String] data
+          #   The binary data to unpack.
+          #
+          # @return [Integer, Float, String, nil]
+          #   The unpacked value.
+          #
+          # @raise [NotImplementedError]
+          #   {#pack_string} was not set.
+          #
+          # @api public
+          #
+          def unpack(data)
+            if @pack_string
+              data.unpack1(@pack_string)
+            else
+              raise(NotImplementedError,"#{self.class} does not define a #pack_string")
+            end
+          end
+
+          #
+          # Enqueues a scalar value onto the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @param [Integer, Float, String, nil] value
+          #   The scalar value to enqueue.
+          #
+          # @api private
+          #
+          def enqueue_value(values,value)
+            values.push(value)
+          end
+
+          #
+          # Dequeues a scalar value from the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @return [Integer, Float, String, nil]
+          #   The dequeued scalar value.
+          #
+          # @api private
+          #
+          def dequeue_value(values)
+            values.shift
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/binary/ctypes/string_type.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/binary/ctypes/type'
+
+module Ronin
+  module Support
+    module Binary
+      module CTypes
+        #
+        # Represents a C string type.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        class StringType < Type
+
+          #
+          # Initializes the string type.
+          #
+          def initialize
+            super(pack_string: 'Z*')
+          end
+
+          #
+          # Indicates that Strings can have arbitrary size.
+          #
+          # @return [Float::INFINITY]
+          #
+          def size
+            Float::INFINITY
+          end
+
+          alias length size
+
+          #
+          # The alignment for the string type
+          #
+          # @return [1]
+          #
+          def alignment
+            1
+          end
+
+          #
+          # Indicates that the String contains signed characters.
+          #
+          # @return [true]
+          #
+          def signed?
+            true
+          end
+
+          #
+          # Indicates that the String does not contains unsigned characters.
+          #
+          # @return [false]
+          #
+          def unsigned?
+            false
+          end
+
+          #
+          # Packs the String into a null-terminated C String.
+          #
+          # @param [String] value
+          #   The String to pack.
+          #
+          # @return [String]
+          #   The packed binary data.
+          #
+          # @api public
+          #
+          def pack(value)
+            [value].pack(@pack_string)
+          end
+
+          #
+          # Unpacks a null-terminated C String.
+          #
+          # @param [String] data
+          #   The binary data to unpack.
+          #
+          # @return [String, nil]
+          #   The unpacked String.
+          #
+          # @api public
+          #
+          def unpack(data)
+            data.unpack1(@pack_string)
+          end
+
+          #
+          # Enqueues a string onto the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @param [String, nil] value
+          #   The string to enqueue.
+          #
+          # @api private
+          #
+          def enqueue_value(values,value)
+            values.push(value)
+          end
+
+          #
+          # Dequeues a string from the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @return [String]
+          #   The dequeued string.
+          #
+          # @api private
+          #
+          def dequeue_value(values)
+            values.shift
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/binary/ctypes/struct_object_type.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/binary/ctypes/object_type'
+require 'ronin/support/binary/ctypes/struct_type'
+
+module Ronin
+  module Support
+    module Binary
+      module CTypes
+        #
+        # Represents a {Binary::Struct} type.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        class StructObjectType < ObjectType
+
+          # The {Struct} class.
+          #
+          # @return [Class<Binary::Struct>]
+          attr_reader :struct_class
+
+          # The type used for packing literal `Hash` values.
+          #
+          # @return [StructType]
+          attr_reader :struct_type
+
+          #
+          # Initializes the memory-mapped struct type.
+          #
+          # @param [<Binary::Struct>] struct_class
+          #   The {Struct} class.
+          #
+          # @param [StructType] struct_type
+          #   The struct type for the struct class.
+          #
+          def initialize(struct_class,struct_type)
+            @struct_class = struct_class
+            @struct_type  = struct_type
+
+            super(@struct_type.size)
+          end
+
+          #
+          # The size of the struct type.
+          #
+          # @return [Integer, Float::INFINITY]
+          #
+          def size
+            @struct_type.size
+          end
+
+          #
+          # The alignment, in bytes, of the memory-mapped {Struct}.
+          #
+          # @return [Integer]
+          #
+          def alignment
+            @struct_type.alignment
+          end
+
+          #
+          # Creates a copy of the struct object type with a different
+          # {#alignment}.
+          #
+          # @param [Integer] new_alignment
+          #   The new alignment for the new struct object type.
+          #
+          # @return [ScalarType]
+          #   The new struct object type.
+          #
+          def align(new_alignment)
+            self.class.new(@struct_class,@struct_type.align(new_alignment))
+          end
+
+          #
+          # The members of the struct type.
+          #
+          # @return [Hash{Symbol => StructType::Member}]
+          #
+          def members
+            @struct_type.members
+          end
+
+          #
+          # Packs the memory-mapped {Struct}.
+          #
+          # @param [Binary::Struct, Hash] struct
+          #   The memory-mapped {Struct} object.
+          #
+          # @return [String]
+          #   The underlying binary data for the memory object.
+          #
+          # @raise [ArgumentError]
+          #   The given value was not a {Binary::Struct} or `Hash`.
+          #
+          def pack(struct)
+            case struct
+            when Binary::Struct
+              struct.to_s
+            when Hash
+              @struct_type.pack(struct)
+            else
+              raise(ArgumentError,"value must be either a #{Binary::Struct} or an #{Hash}: #{struct.inspect}")
+            end
+          end
+
+          #
+          # Unpacks the memory-mapped {Struct}.
+          #
+          # @param [String] data
+          #   The raw binary data to unpack.
+          #
+          # @return [Binary::Struct]
+          #   the unpacked {Struct} object.
+          #
+          def unpack(data)
+            @struct_class.unpack(data)
+          end
+
+          #
+          # Enqueues the memory-mapped {Struct} into the list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @param [Binary::Struct, Hash] struct
+          #   The {Struct} object to enqueue.
+          #
+          def enqueue_value(values,struct)
+            case struct
+            when Binary::Struct
+              values.push(struct.to_s)
+            when Hash
+              values.push(@struct_type.pack(struct))
+            end
+          end
+
+          #
+          # Dequeues a memory object from the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @return [Struct]
+          #   The dequued {Struct} object.
+          #
+          def dequeue_value(values)
+            @struct_class.new(values.shift)
+          end
+
+        end
+      end
+    end
+  end
+end