ruby-macho 0.0.9 → 0.1.0

data/lib/macho/macho_file.rb

@@ -3,6 +3,7 @@ module MachO
 	# as well as binary executable instructions. Mach-O binaries are
 	# architecture specific.
 	# @see https://en.wikipedia.org/wiki/Mach-O
+	# @see MachO::FatFile
 	class MachOFile
 		# @return [MachO::MachHeader] if the Mach-O is 32-bit
 		# @return [MachO::MachHeader64] if the Mach-O is 64-bit
@@ -361,6 +362,7 @@ module MachO
 		# Write all Mach-O data to the file used to initialize the instance.
 		# @raise [MachOError] if the instance was created from a binary string
 		# @return [void]
+		# @note Overwrites all data in the file!
 		def write!
 			if @filename.nil?
 				raise MachOError.new("cannot write to a default file when initialized from a binary string")
@@ -371,6 +373,10 @@ module MachO
 
 		private
 
+		# The file's Mach-O header structure.
+		# @return [MachO::MachHeader] if the Mach-O is 32-bit
+		# @return [MachO::MachHeader64] if the Mach-O is 64-bit
+		# @private
 		def get_mach_header
 			magic = get_magic
 			cputype = get_cputype
@@ -388,6 +394,11 @@ module MachO
 			end
 		end
 
+		# The file's magic number.
+		# @return [Fixnum] the magic
+		# @raise [MachO::MagicError] if the magic is not valid Mach-O magic
+		# @raise [MachO::FatBinaryError] if the magic is for a Fat file
+		# @private
 		def get_magic
 			magic = @raw_data[0..3].unpack("N").first
 
@@ -402,6 +413,10 @@ module MachO
 			magic
 		end
 
+		# The file's CPU type.
+		# @return [Fixnum] the CPU type
+		# @raise [MachO::CPUTypeError] if the CPU type is unknown
+		# @private
 		def get_cputype
 			cputype = @raw_data[4..7].unpack("V").first
 
@@ -412,6 +427,10 @@ module MachO
 			cputype
 		end
 
+		# The file's CPU subtype.
+		# @return [Fixnum] the CPU subtype
+		# @raise [MachO::CPUSubtypeError] if the CPU subtype is unknown
+		# @private
 		def get_cpusubtype
 			cpusubtype = @raw_data[8..11].unpack("V").first
 
@@ -425,6 +444,10 @@ module MachO
 			cpusubtype
 		end
 
+		# The file's type.
+		# @return [Fixnum] the file type
+		# @raise [MachO::FiletypeError] if the file type is unknown
+		# @private
 		def get_filetype
 			filetype = @raw_data[12..15].unpack("V").first
 
@@ -435,24 +458,37 @@ module MachO
 			filetype
 		end
 
+		# The number of load commands in the file.
+		# @return [Fixnum] the number of load commands
+		# @private
 		def get_ncmds
 			ncmds = @raw_data[16..19].unpack("V").first
 
 			ncmds
 		end
 
+		# The size of all load commands, in bytes.
+		# return [Fixnum] the size of all load commands
+		# @private
 		def get_sizeofcmds
 			sizeofcmds = @raw_data[20..23].unpack("V").first
 
 			sizeofcmds
 		end
 
+		# The Mach-O header's flags.
+		# @return [Fixnum] the flags
+		# @private
 		def get_flags
 			flags = @raw_data[24..27].unpack("V").first
 
 			flags
 		end
 
+		# All load commands in the file.
+		# @return [Array<MachO::LoadCommand>] an array of load commands
+		# @raise [MachO::LoadCommandError] if an unknown load command is encountered
+		# @private
 		def get_load_commands
 			offset = header.bytesize
 			load_commands = []
@@ -476,6 +512,10 @@ module MachO
 			load_commands
 		end
 
+		# Updates the size of all load commands in the raw data.
+		# @param size [Fixnum] the new size, in bytes
+		# @return [void]
+		# @private
 		def set_sizeofcmds(size)
 			new_size = [size].pack("V")
 			@raw_data[20..23] = new_size

data/lib/macho/sections.rb

@@ -56,6 +56,7 @@ module MachO
 	SECT_ICON_HEADER = "__header"
 	SECT_ICON_TIFF = "__tiff"
 
+	# Represents a section of a segment for 32-bit architectures.
 	class Section < MachOStructure
 		attr_reader :sectname, :segname, :addr, :size, :offset, :align, :reloff
 		attr_reader :nreloc, :flags, :reserved1, :reserved2
@@ -63,6 +64,7 @@ module MachO
 		@format = "a16a16VVVVVVVVV"
 		@sizeof = 68
 
+		# @private
 		def initialize(sectname, segname, addr, size, offset, align, reloff,
 				nreloc, flags, reserved1, reserved2)
 			@sectname = sectname
@@ -78,19 +80,26 @@ module MachO
 			@reserved2 = reserved2
 		end
 
+		# @return [String] the section's name, with any trailing NULL characters removed
 		def section_name
 			@sectname.delete("\x00")
 		end
 
+		# @return [String] the parent segment's name, with any trailing NULL characters removed
 		def segment_name
 			@segname.delete("\x00")
 		end
 
+		# @example
+		#  puts "this section is regular" if sect.flag?(S_REGULAR)
+		# @param flag [Fixnum] a section flag constant
+		# @return [Boolean] true if `flag` is present in the sections's flag field
 		def flag?(flag)
 			flags & flag == flag
 		end
 	end
 
+	# Represents a section of a segment for 64-bit architectures.
 	class Section64 < MachOStructure
 		attr_reader :sectname, :segname, :addr, :size, :offset, :align, :reloff
 		attr_reader :nreloc, :flags, :reserved1, :reserved2, :reserved3
@@ -98,6 +107,7 @@ module MachO
 		@format = "a16a16QQVVVVVVVV"
 		@sizeof = 80
 
+		# @private
 		def initialize(sectname, segname, addr, size, offset, align, reloff,
 				nreloc, flags, reserved1, reserved2, reserved3)
 			@sectname = sectname
@@ -114,14 +124,20 @@ module MachO
 			@reserved3 = reserved3
 		end
 
+		# @return [String] the section's name, with any trailing NULL characters removed
 		def section_name
 			@sectname.delete("\x00")
 		end
 
+		# @return [String] the parent segment's name, with any trailing NULL characters removed
 		def segment_name
 			@segname.delete("\x00")
 		end
 
+		# @example
+		#  puts "this section is regular" if sect.flag?(S_REGULAR)
+		# @param flag [Fixnum] a section flag constant
+		# @return [Boolean] true if `flag` is present in the sections's flag field
 		def flag?(flag)
 			flags & flag == flag
 		end

data/lib/macho/structure.rb

@@ -1,13 +1,16 @@
 module MachO
-	# general purpose pseudo-structure
+	# A general purpose pseudo-structure. 
 	class MachOStructure
-		@format = nil
+		# Subclasses should fill these in manually.
+		@format = ""
 		@sizeof = 0
 
+		# @return [Fixnum] the size, in bytes, of the represented structure.
 		def self.bytesize
 			@sizeof
 		end
 
+		# @return [MachO::MachOStructure] a new MachOStructure initialized with `bin`
 		def self.new_from_bin(bin)
 			self.new(*bin.unpack(@format))
 		end

data/lib/macho/utils.rb

@@ -1,5 +1,8 @@
 module MachO
-	# http://www.opensource.apple.com/source/cctools/cctools-870/libstuff/rnd.c
+	# @param value [Fixnum] the number being rounded
+	# @param round [Fixnum] the number being rounded with
+	# @return [Fixnum] the next number >= `value` such that `round` is its divisor
+	# @see http://www.opensource.apple.com/source/cctools/cctools-870/libstuff/rnd.c
 	def self.round(value, round)
 		round -= 1
 		value += round
@@ -7,18 +10,26 @@ module MachO
 		value
 	end
 
+	# @param num [Fixnum] the number being checked
+	# @return [Boolean] true if `num` is a valid Mach-O magic number, false otherwise
 	def self.magic?(num)
 		MH_MAGICS.has_key?(num)
 	end
 
+	# @param num [Fixnum] the number being checked
+	# @return [Boolean] true if `num` is a valid Fat magic number, false otherwise
 	def self.fat_magic?(num)
 		num == FAT_MAGIC || num == FAT_CIGAM
 	end
 
+	# @param num [Fixnum] the number being checked
+	# @return [Boolean] true if `num` is a valid 32-bit magic number, false otherwise
 	def self.magic32?(num)
 		num == MH_MAGIC || num == MH_CIGAM
 	end
 
+	# @param num [Fixnum] the number being checked
+	# @return [Boolean] true if `num` is a valid 64-bit magic number, false otherwise
 	def self.magic64?(num)
 		num == MH_MAGIC_64 || num == MH_CIGAM_64
 	end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-macho
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors:
 - William Woodruff