Added documentation for new structure dsl

Author: apainintheneck

lib/macho/headers.rb

@@ -751,13 +751,13 @@ class PrelinkedKernelHeader < MachOStructure
       field :prelink_version, :uint32, :endian => :big
 
       # @return [void]
-      field :reserved, :binary, :size => 40, :unpack => "L>10"
+      field :reserved, :varbyte, :size => 40, :unpack => "L>10"
 
       # @return [void]
-      field :platform_name, :binary, :size => 64
+      field :platform_name, :varbyte, :size => 64
 
       # @return [void]
-      field :root_path, :binary, :size => 256
+      field :root_path, :varbyte, :size => 256
 
       # @return [Boolean] whether this prelinked kernel supports KASLR
       def kaslr?

lib/macho/load_commands.rb

@@ -367,7 +367,7 @@ def initialize(endianness, alignment)
     # LC_UUID.
     class UUIDCommand < LoadCommand
       # @return [Array<Integer>] the UUID
-      field :uuid, :binary, :size => 16, :unpack => "C16"
+      field :uuid, :varbyte, :size => 16, :unpack => "C16"
 
       # @return [String] a string representation of the UUID
       def uuid_string
@@ -398,7 +398,7 @@ def to_h
     # the task's address space. Corresponds to LC_SEGMENT.
     class SegmentCommand < LoadCommand
       # @return [String] the name of the segment
-      field :segname, :string, :size => 16, :to_s => true
+      field :segname, :varchar, :size => 16, :to_s => true
 
       # @return [Integer] the memory address of the segment
       field :vmaddr, :uint32
@@ -1325,7 +1325,7 @@ def to_h
     # Corresponds to LC_NOTE.
     class NoteCommand < LoadCommand
       # @return [String] the name of the owner for this note
-      field :data_owner, :string, :size => 16, :to_s => true
+      field :data_owner, :varchar, :size => 16, :to_s => true
 
       # @return [Integer] the offset, within the file, of the note
       field :offset, :uint64

lib/macho/sections.rb

@@ -89,11 +89,11 @@ module Sections
     # Represents a section of a segment for 32-bit architectures.
     class Section < MachOStructure
       # @return [String] the name of the section, including null pad bytes
-      field :sectname, :string, :size => 16
+      field :sectname, :varchar, :size => 16
 
       # @return [String] the name of the segment's section, including null
       #  pad bytes
-      field :segname, :string, :size => 16
+      field :segname, :varchar, :size => 16
 
       # @return [Integer] the memory address of the section
       field :addr, :uint32

lib/macho/structure.rb

@@ -1,5 +1,62 @@
 # frozen_string_literal: true
 
+# MachOStructure DSL Documentation:
+#   The MachOStructure class makes it easy to describe
+# binary chunks by using the #field method. This method
+# generates the byte size and format strings necessary
+# to parse a chunk of binary data. It also automatically
+# generates the constructor and readers for all fields
+# as well.
+#   The fields are created in order so you will be
+# expected to pass those arguements to the constructor
+# in the same order. Fields with no arguments should
+# be defined last and fields with default arguments
+# should be defined right before them.
+#   The type and options of inherited fields can be changed
+# but their argument position and the number of arguments
+# (used to calculate min_args) will also not change.
+#   Usually, endianness is handled by the
+# Utils#specialize_format method but occasionally a
+# field needs to specifiy that beforehand. That is
+# what the :endian option is for. If not specified,
+# a placeholder is used so that can be specified later.
+#
+# Syntax:
+#   field [field name], [field type], [option => value]*
+#
+# Ex:
+# class AllFields < MachO::MachOStructure
+#   field :name1, :varbyte, :size => 16
+#   field :name2, :varchar, :size => 32
+#   field :name3, :int32
+#   field :name4, :uint32
+#   field :name5, :uint64
+#   field :name6, :view
+#   field :name7, :lcstr
+#   field :name8, :two_level_hints_table
+#   field :name9, :tool_entries
+# end
+#
+# Field types:
+#   :varbyte = a null terminated binary chunk
+#   :varchar = a null terminated binary string (cstring)
+#   :int32 = signed 32 bit integer
+#   :uint32 = unsigned 32 bit integer
+#   :uint64 = unsigned 64 bit integer
+#   :view = class (must be instantiated before passed to constructor)
+#   :lcstr = class (will be instantiated in constructor)
+#   :two_level_hints_table = no arg class (will be instantiated in constructor)
+#   :tool_entries = class (will be instantiated in constructor)
+#
+# Option types:
+#   Exclusive (only one can be used at a time):
+#     :mask [Integer] bitmask to be applied to field
+#     :unpack [String] binary unpack string used for further unpacking of :varbyte
+#     :default [Value] default field value
+#   Inclusive (can be used with other options):
+#     :to_s [Boolean] generate #to_s method based on field
+#     :endian [Symbol] optionally specify :big or :little endian
+
 module MachO
   # A general purpose pseudo-structure.
   # @abstract
@@ -15,8 +72,8 @@ module Fields
       # @api private
       BYTE_SIZE = {
         # Binary slices
-        :binary => nil,
-        :string => nil,
+        :varbyte => nil,
+        :varchar => nil,
         :int32 => 4,
         :uint32 => 4,
         :uint64 => 8,
@@ -36,8 +93,8 @@ module Fields
       # @api private
       FORMAT_CODE = {
         # Binary slices
-        :binary => "a",
-        :string => "Z",
+        :varbyte => "a",
+        :varchar => "Z",
         :int32 => "l=",
         :uint32 => "L=",
         :uint64 => "Q=",

test/test_structure_dsl.rb

@@ -7,8 +7,8 @@ class MachOStructureTest < Minitest::Test
   # that information is reflected in the bytesize, min_args
   # and format.
   class AllFields < MachO::MachOStructure
-    field :binary, :binary, :size => 16
-    field :string, :string, :size => 32
+    field :varbyte, :varbyte, :size => 16
+    field :varchar, :varchar, :size => 32
     field :int32, :int32
     field :uint32, :uint32
     field :uint64, :uint64
@@ -19,8 +19,8 @@ class AllFields < MachO::MachOStructure
   end
 
   def test_all_field_types
-    assert_includes AllFields.instance_methods, :binary
-    assert_includes AllFields.instance_methods, :string
+    assert_includes AllFields.instance_methods, :varbyte
+    assert_includes AllFields.instance_methods, :varchar
     assert_includes AllFields.instance_methods, :int32
     assert_includes AllFields.instance_methods, :uint32
     assert_includes AllFields.instance_methods, :uint64
@@ -66,7 +66,7 @@ def test_mask_option
   end
 
   class UnpackCmd < MachO::MachOStructure
-    field :unpack_field, :binary, :size => 8, :unpack => "L>2"
+    field :unpack_field, :varbyte, :size => 8, :unpack => "L>2"
   end
 
   def test_unpack_option