slowfat 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6abcf48f837234179e5df0d15ad3897130d20113
-  data.tar.gz: abd92e3c770f993e954555310073319b587fd314
+  metadata.gz: 91f614012072f497abd7a42928629b09e82b215e
+  data.tar.gz: 99530e503ba9d5769c3bdc4c4bf2e3548c39dc5b
 SHA512:
-  metadata.gz: 2aac85c59372730819e52971a32ddb4965e0446c17b24714e1e9abc305c78224848dee6ac49b6ef93f0bdc867279ef4399a5e38f3f5cfc38c0dc625ad5ee921e
-  data.tar.gz: e912068bef784900cbffdc7a760165646e66a39125f37b592a0f03ec8df09935af228dc4ce69a64f283462f627fb2152c16aedfa31050edade8babe4c26e12d5
+  metadata.gz: d94d90f02158398a6069e8f6b27ddf8785834d861d132e0f5d9cd205a10b4fb98bcca51a99a7279528aed8ff2cc6884f35d01ede389a5e7c67ee5cba9acec19f
+  data.tar.gz: e48cb89463beb0506277e9d158b8038d345cda5ffb375da49b26f3cfef5522288434a1f4b061c9799fda507b63c8c07f064fcc790533fa4326dab0af749c94ae

data/README.md

@@ -1,2 +1,27 @@
-# ruby-slowfat
-FAT library for Ruby, designed to perform minimum I/O for use on slow links such as serial connections.
+# ruby-slowfat - FAT library for Ruby designed for slow links/media
+
+## Description
+
+Ruby class/gem to access FAT filesystems (currently only FAT16) over slow links or media, such as serial connections. Prioritizes minimum I/O whenever possible, and flexible backing (files, sockets, etc.).
+
+## Features
+ * FAT16 support
+ * Read and format directory listings
+ * Read contents of files
+
+## TODO
+ * FAT12 support
+ * Write support
+ * Optimize a couple places where we might do more I/O than required
+
+## Use
+    require 'slowfat'
+
+    img = File.open("test_fat16.img", 'r')
+    fs = Fat::Filesystem.new(backing: img, base: 0x7E00)
+    print fs.dir("WINDOWS").to_s
+    print fs.file("WINDOWS/SETUP.TXT").contents
+
+
+## Full Documentation
+YARD docs included, also available on [RubyDoc.info](https://www.rubydoc.info/github/sarahemm/ruby-slowfat/master)

data/lib/slowfat/bootsect.rb

@@ -1,24 +1,40 @@
 module SlowFat
+  ##
+  # BootSector handles accessing information inside the boot sector, such as BPB, signature, and boot code.
   class BootSector
+    # @return [String] the OEM Name contained in this boot sector.
     attr_reader :oem_name
 
+    ##
+    # DataError is raised if unexpected data is encountered when handling the filesystem.
     class DataError < StandardError
     end
 
+    ##
+    # Initialize a new BootSector object (normally only called from Filesystem)
+    # @param data [String] raw data making up this boot sector
     def initialize(data)
       (@jmp, @oem_name, @bpb, @ebpb, @boot_code, @boot_signature) = data.unpack('a3a8a25a26a448v')
       raise DataError, "Invalid boot signature in boot sector." if(@boot_signature != 0xAA55)
     end
 
+    ##
+    # Parse out and return a BIOS Parameter Block from this boot sector
+    # @return [BiosParameterBlock] the BPB parsed out of this boot sector
     def bios_parameter_block
       BiosParameterBlock.new @bpb
     end
 
+    ##
+    # Parse out and return an Extended BIOS Parameter Block from this boot sector
+    # @return [ExtendedBiosParameterBlock] the EBPB parsed out of this boot sector
     def extended_bios_parameter_block
       ExtendedBiosParameterBlock.new @ebpb
     end
   end
 
+  ##
+  # BiosParameterBlock holds information from a BPB.
   class BiosParameterBlock
     attr_reader :bytes_per_logsect, :logsects_per_cluster, :reserved_logsects, :fats, :root_entries, :logsects, :media_descriptor, :logsects_per_fat, :physects_per_track, :heads, :hidden_logsects, :large_total_logsects
 
@@ -26,6 +42,9 @@ module SlowFat
       (@bytes_per_logsect, @logsects_per_cluster, @reserved_logsects, @fats, @root_entries, @total_logsects, @media_descriptor, @logsects_per_fat, @physects_per_track, @heads, @hidden_logsects, @large_total_logsects) = data.unpack('vCvCvvCvvvVV')
     end
 
+    ##
+    # Return the type of media this boot sector is on
+    # @return [Symbol] the type of media described by the media descriptor in the boot sector
     def media_descriptor_type
       case @media_descriptor_id
         when 0xE5
@@ -42,6 +61,8 @@ module SlowFat
     end
   end
   
+  ##
+  # ExtendedBiosParameterBlock holds information from an EBPB.
   class ExtendedBiosParameterBlock
     attr_reader :physical_drive_nbr, :boot_signature, :volume_serial, :volume_label, :fs_type
 

data/lib/slowfat/data.rb

@@ -1,18 +1,32 @@
 module SlowFat
+  ##
+  # Data is used to access the actual contents of FAT clusters.
   class Data
-    attr_reader :base, :size
-
+    ##
+    # Initialize a new Data object (normally only called from FatFile)
+    # @param backing [IO] the storage containing the filesystem (e.g. open file)
+    # @param base [Integer] the start of the data area within the backing
+    # @param cluster_size [Integer] the size of each cluster in the filesystem
     def initialize(backing:, base:, cluster_size:)
       @backing = backing
       @base = base
       @cluster_size = cluster_size
     end
 
+    ##
+    # Return the contents of a given cluster.
+    # @param cluster [Integer] the cluster number to obtain data from
+    # @param size [Integer] the size of data to obtain
+    # @return [String] the data obtained from the given cluster
     def cluster_contents(cluster:, size:)
       @backing.seek @base + @cluster_size * cluster
       @backing.read size
     end
 
+    ##
+    # Return the contents of all clusters in given chain
+    # @param chain [Integer] the chain of clusters to obtain data from
+    # @param size [Integer] the total size of data to obtain
     def cluster_chain_contents(chain:, size:)
       data = ""
       chain.each_index do |idx|

data/lib/slowfat/dir.rb

@@ -1,7 +1,15 @@
 module SlowFat
+  ##
+  # Directory represents one directory on a FAT filesystem.
   class Directory
+    # @return [Array<Dentry>] an array of directory entries within this directory
     attr_reader :entries
 
+    ##
+    # Initialize a new Directory object (normally only called from Filesystem.dir)
+    # @param backing [IO] the storage containing the filesystem (e.g. open file)
+    # @param base [Integer] the location of the beginning of this directory structure within the backing device
+    # @param max_entries [Integer] the maximum number of entries that can be in this directory
     def initialize(backing:, base:, max_entries:)
       @backing = backing
       @entries = []
@@ -14,6 +22,10 @@ module SlowFat
       end
     end
 
+    ##
+    # Return a directory entry for a specific file within this directory
+    # @param filename [String] the name of the file to access
+    # @return [Dentry] the directory entry object matching the requested file
     def file_entry(filename)
       @entries.each do |dentry|
         full_dentry_filename = dentry.extension.length > 0 ? "#{dentry.filename}.#{dentry.extension}".downcase : dentry.filename.downcase
@@ -23,6 +35,10 @@ module SlowFat
       nil
     end
 
+    ##
+    # Return a directory entry for a specific subdirectory within this directory
+    # @param filename [String] the name of the directory to access
+    # @return [Dentry] the directory entry object matching the requested subdirectory
     def dir_entry(filename)
       @entries.each do |dentry|
         full_dentry_filename = dentry.extension.length > 0 ? "#{dentry.filename}.#{dentry.extension}".downcase : dentry.filename.downcase
@@ -32,9 +48,39 @@ module SlowFat
       nil
     end
 
-    class Dentry
-      attr_reader :filename, :extension, :start_cluster, :size, :type
+    ##
+    # Convert a Directory into a vaguely DOS-style file listing
+    # @return [String] the contents of this directory, formatted as a human-readable listing
+    def to_s
+      buf = ""
+      @entries.each do |dentry|
+        if(dentry.type == :file) then
+          buf += sprintf("%-8s %-3s   %d\n", dentry.filename, dentry.extension, dentry.size)
+        elsif(dentry.type == :directory)
+          buf += sprintf("%-8s %-3s   <DIR>\n", dentry.filename, dentry.extension)
+        end
+      end
+
+      buf
+    end
 
+    ##
+    # Dentry represents one entry inside a Directory.
+    class Dentry
+       # @return [String] the name of the file or other directory entry
+      attr_reader :filename
+      # @return [String] the file extension
+      attr_reader :extension
+      # @return [Integer] the starting cluster of this file in the backing
+      attr_reader :start_cluster
+      # @return [Integer] the size of the file in bytes
+      attr_reader :size
+      # @return [Symbol] the type of item this dentry describes
+      attr_reader :type
+
+      ##
+      # Initialize a new directory entry (normally only called from Directory)
+      # @param dir_data [String] the data making up this dentry in the backing
       def initialize(dir_data)
         case dir_data[0].ord
           when 0x00
@@ -61,43 +107,47 @@ module SlowFat
         @type = :directory if attrib_bits & 0x10 > 0
       end
 
+      ##
+      # Returns true if this dentry has the read only attribute set
       def read_only?
-        @hidden
+        @read_only
       end
 
+      ##
+      # Returns true if this dentry has the hidden attribute set
       def hidden?
         @hidden
       end
 
+      ##
+      # Returns true if this dentry has the system attribute set
       def system?
         @system
       end
       
+      ##
+      # Returns true if this dentry has the archive attribute set
       def archive?
         @archive
       end
 
+      ##
+      # Returns true if this dentry has the device attribute set
       def device?
         @device
       end
 
+      ##
+      # Returns true if this dentry is a file that has been deleted
       def deleted?
         @deleted
       end
 
+      ##
+      # Returns true if this dentry is a dot directory (. or ..)
       def dotdir?
         @dotdir
       end
     end
-
-    def dump
-      @entries.each do |dentry|
-        if(dentry.type == :file) then
-          printf("%-8s %-3s   %d\n", dentry.filename, dentry.extension, dentry.size)
-        elsif(dentry.type == :directory)
-          printf("%-8s %-3s   <DIR>\n", dentry.filename, dentry.extension)
-        end
-      end
-    end
   end
 end

data/lib/slowfat/fat_file.rb

@@ -1,11 +1,20 @@
 module SlowFat
+  ##
+  # FatFile represents a single file on a FAT filesystem
   class FatFile
+    ##
+    # Initialize a new Directory object (normally only called from Directory's functions)
+    # @param filesystem [Filesystem] the filesystem containing this file
+    # @param dentry [Dentry] the directory entry pointing to this file
     def initialize(filesystem:, dentry:)
       @filesystem = filesystem
       @dentry = dentry
       @data = Data.new(backing: filesystem.backing, base: filesystem.data_base, cluster_size: filesystem.cluster_size)
     end
 
+    ##
+    # Return the entire contents of a file
+    # @return [String] the contents of this file
     def contents
       @data.cluster_chain_contents chain: @filesystem.fats[0].chain_starting_at(@dentry.start_cluster), size: @dentry.size
     end

data/lib/slowfat/file_alloc_table.rb

@@ -1,13 +1,24 @@
 module SlowFat
+  ##
+  # FileAllocationTable represents one FAT (of two on a disk, most commonly)
   class FileAllocationTable
     attr_reader :chains, :base, :size
 
+    ##
+    # Initialize a new FileAllocatinTable object (normally only called from Filesystem)
+    # @param backing [IO] the storage containing the filesystem (e.g. open file)
+    # @param base [Integer] the location of the beginning of this FAT structure within the backing device
+    # @param size [Integer] the total size of this FAT
     def initialize(backing:, base:, size:)
       @backing = backing
       @base = base
       @size = size
     end
 
+    ##
+    # Retrieve a full chain of cluster numbers, starting at a given cluster
+    # @param start_cluster [Integer] the cluster number to retrieve a chain starting from
+    # @return [Array<Integer>] a list of clusters in the chain, starting from the cluster provided
     def chain_starting_at(start_cluster)
       current_cluster = start_cluster
       current_chain = []

data/lib/slowfat/filesystem.rb

@@ -1,11 +1,29 @@
+##
+# The SlowFat module handles the entire filesystem access process.
 module SlowFat
+  ##
+  # Filesystem coordinates overall FAT filesystem access.
   class Filesystem
-    attr_reader :backing, :rootdir_base, :rootdir, :data_base, :fats, :cluster_size
+    # @return [IO] the backing IO object for this filesystem
+    attr_reader :backing
+    # @return [Integer] the location where the root directory information starts within the backing
+    attr_reader :rootdir_base
+    # @return [Directory] the Directory object containing the root directory
+    attr_reader :rootdir
+    # @return [Integer] the location where the data starts within the backing
+    attr_reader :data_base
+    # @return [Array<FileAllocationTable>] array of file allocation tables
+    attr_reader :fats
+    # @return [Integer] the cluster size used on this filesystem
+    attr_reader :cluster_size
 
-    def initialize(backing:)
-      # TODO: this needs to be more flexible
-      @base = 0x0000
+    ##
+    # Set up a new filesystem connection
+    # @param backing [IO] the storage containing the filesystem (e.g. open file)
+    # @param base [Integer] the start of the filesystem within the backing device
+    def initialize(backing:, base: 0x0000)
       @backing = backing
+      @base = base
 
       fat_base = @base + 512
       fat_size = bios_parameter_block.bytes_per_logsect * bios_parameter_block.logsects_per_fat
@@ -21,20 +39,34 @@ module SlowFat
       @data_base = rootdir_base + bios_parameter_block.root_entries * 32 - @cluster_size*2
     end
 
+    ##
+    # Access the boot sector of this filesystem.
+    # @return [BootSector] the boot sector on this filesystem
     def bootsect
       @backing.seek @base
       BootSector.new @backing.read(512)
     end
 
+    ##
+    # Access the BIOS Parameter Block of this filesystem.
+    # @return [BiosParameterBlock] the BPB on this filesystem
     def bios_parameter_block
       bootsect.bios_parameter_block
     end
 
+    ##
+    # Access the Extended BIOS Parameter Block of this filesystem.
+    # @return [ExtendedBiosParameterBlock] the EBPB on this filesystem
     def extended_bios_parameter_block
       bootsect.extended_bios_parameter_block
     end
 
+    ##
+    # Access a directory within this filesystem.
+    # @param dirname [String] the path to retrieve a directory object for
+    # @return [Directory] the directory object matching the requested path
     def dir(dirname)
+      # TODO: accept either / or \
       path_elements = dirname.split('/')
       current_dir_base = @rootdir_base
       next_dir = nil
@@ -52,6 +84,10 @@ module SlowFat
       Directory.new(backing: @backing, base: current_dir_base, max_entries: max_entries)
     end
 
+    ##
+    # Access a file within this filesystem
+    # @param path [String] the path to retrieve a file object for
+    # @return [FatFile] the file object matching the requested path
     def file(path)
       path_components = path.split('/')
       dir_components = path_components[0..-2]

data/lib/slowfat/version.rb

@@ -1,4 +1,4 @@
 module SlowFat
   # The version number of the SlowFat module.
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slowfat
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - sarahemm
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-17 00:00:00.000000000 Z
+date: 2021-04-18 00:00:00.000000000 Z
 dependencies: []
 description: FAT filesystem library for use with slow I/O (e.g. serial links)
 email: github@sen.cx