1.1 --- a/ADFSlib.py	Mon Oct 10 22:38:19 2011 +0200
     1.2 +++ b/ADFSlib.py	Mon Oct 10 22:40:00 2011 +0200
     1.3 @@ -43,9 +43,10 @@
     1.4  
     1.5  class ADFSdirectory:
     1.6  
     1.7 -    """ADFSdirectory
     1.8 +    """directory = ADFSdirectory(name, files)
     1.9      
    1.10 -    directory = ADFSdirectory(name, files)
    1.11 +    The directory created contains name and files attributes containing the
    1.12 +    directory name and the objects it contains.
    1.13      """
    1.14      
    1.15      def __init__(self, name, files):
    1.16 @@ -60,9 +61,7 @@
    1.17  
    1.18  class ADFSfile:
    1.19  
    1.20 -    """ADFSfile
    1.21 -    
    1.22 -    file = ADFSfile(name, data, load_address, execution_address, length)
    1.23 +    """file = ADFSfile(name, data, load_address, execution_address, length)
    1.24      """
    1.25      
    1.26      def __init__(self, name, data, load_address, execution_address, length):
    1.27 @@ -79,14 +78,24 @@
    1.28      
    1.29      def has_filetype(self):
    1.30      
    1.31 +        """Returns True if the file's meta-data contains filetype information."""
    1.32          return self.load_address & 0xfff00000 == 0xfff00000
    1.33      
    1.34      def filetype(self):
    1.35      
    1.36 +        """Returns the meta-data containing the filetype information.
    1.37 +        
    1.38 +        Note that a filetype can be obtained for all files, though it may not
    1.39 +        necessarily be valid. Use has_filetype() to determine whether the file
    1.40 +        is likely to have a valid filetype."""
    1.41 +        
    1.42          return "%03x" % ((self.load_address >> 8) & 0xfff)
    1.43      
    1.44      def time_stamp(self):
    1.45      
    1.46 +        """Returns the time stamp for the file as a tuple of values containing
    1.47 +        the local time, or an empty tuple if the file does not have a time stamp."""
    1.48 +        
    1.49          # RISC OS time is given as a five byte block containing the
    1.50          # number of centiseconds since 1900 (presumably 1st January 1900).
    1.51          
    1.52 @@ -106,9 +115,7 @@
    1.53  
    1.54  class ADFSdisc:
    1.55  
    1.56 -    """ADFSdisc
    1.57 -    
    1.58 -    disc = ADFSdisc(file_handle, verify = 0)
    1.59 +    """disc = ADFSdisc(file_handle, verify = 0)
    1.60      
    1.61      Represents an ADFS disc image stored in the file with the specified file
    1.62      handle. The image is not verified by default; pass True or another
    1.63 @@ -117,10 +124,31 @@
    1.64      If the disc image specified cannot be read successfully, an ADFS_exception
    1.65      is raised.
    1.66      
    1.67 +    The disc's name is recorded in the disc_name attribute; its type is
    1.68 +    recorded in the disc_type attribute. To obtain a human-readable description
    1.69 +    of the disc format call the disc_format() method.
    1.70 +    
    1.71      Once an ADFSdisc instance has been created, it can be used to access the
    1.72 -    contents of the disc image. The files attribute contains
    1.73 +    contents of the disc image. The files attribute contains a list of objects
    1.74 +    from the disc's catalogue, including both directories and files,
    1.75 +    represented by ADFSdirectory and ADFSfile instances respectively.
    1.76 +    
    1.77 +    The contents of the disc can be extracted to a directory structure in the
    1.78 +    user's filing system with the extract_files() method.
    1.79 +    
    1.80 +    For debugging purposes, the print_catalogue() method prints the contents of
    1.81 +    the disc's catalogue to the console. Similarly, the print_log() method
    1.82 +    prints the disc verification log and can be used to show any disc errors
    1.83 +    that have been found.
    1.84      """
    1.85      
    1.86 +    _format_names = {"ads": "ADFS S format",
    1.87 +                     "adm": "ADFS M format",
    1.88 +                     "adl": "ADFS L format",
    1.89 +                     "adD": "ADFS D format",
    1.90 +                     "adE": "ADFS E format",
    1.91 +                     "adEbig": "ADFS F format"}
    1.92 +    
    1.93      def __init__(self, adf, verify = 0):
    1.94      
    1.95          # Log problems if the verify flag is set.
    1.96 @@ -137,7 +165,7 @@
    1.97              self.nsectors = 16
    1.98              self.sector_size = 256
    1.99              interleave = 0
   1.100 -            self.disc_type = 'adf'
   1.101 +            self.disc_type = 'ads'
   1.102              self.dir_markers = ('Hugo',)
   1.103          
   1.104          #if string.lower(adf_file[-4:])==(suffix+"adf"):
   1.105 @@ -146,7 +174,7 @@
   1.106              self.nsectors = 16
   1.107              self.sector_size = 256
   1.108              interleave = 0
   1.109 -            self.disc_type = 'adf'
   1.110 +            self.disc_type = 'adm'
   1.111              self.dir_markers = ('Hugo',)
   1.112          
   1.113          #elif string.lower(adf_file[-4:])==(suffix+"adl"):
   1.114 @@ -1393,9 +1421,7 @@
   1.115      
   1.116      def print_catalogue(self, files = None, path = "$", filetypes = 0):
   1.117      
   1.118 -        """print_catalogue(self, files = None, path = "$", filetypes = 0)
   1.119 -        
   1.120 -        Prints the contents of the disc catalogue to standard output.
   1.121 +        """Prints the contents of the disc catalogue to standard output.
   1.122          Usually, this method is called without specifying any of the keyword
   1.123          arguments, but these can be used to customise the output.
   1.124          
   1.125 @@ -1631,12 +1657,8 @@
   1.126                        separator = ",", convert_dict = {},
   1.127                        with_time_stamps = False):
   1.128      
   1.129 -        """extract_files(self, out_path, files = None, filetypes = 0,
   1.130 -                         separator = ",", convert_dict = {},
   1.131 -                         with_time_stamps = False)
   1.132 -        
   1.133 -        Extracts the files stored in the disc image into a directory structure
   1.134 -        stored on the path specified by out_path.
   1.135 +        """Extracts the files stored in the disc image into a directory
   1.136 +        structure stored on the path specified by out_path.
   1.137          
   1.138          The files parameter specified a list of ADFSfile or ADFSdirectory
   1.139          instances to extract to the target file system. This keyword argument
   1.140 @@ -1743,9 +1765,7 @@
   1.141      
   1.142      def _plural(self, msg, values, words):
   1.143      
   1.144 -        """message = _plural(self, msg, values, words)
   1.145 -        
   1.146 -        Return a message which takes into account the plural form of
   1.147 +        """Returns a message which takes into account the plural form of
   1.148          words in the original message, assuming that the appropriate
   1.149          form for negative numbers of items is the same as that for
   1.150          more than one item.
   1.151 @@ -1778,9 +1798,7 @@
   1.152      
   1.153      def print_log(self, verbose = 0):
   1.154      
   1.155 -        """print_log(self, verbose = 0)
   1.156 -        
   1.157 -        Print the disc verification log. Any purely informational messages
   1.158 +        """Prints the disc verification log. Any purely informational messages
   1.159          are only printed if verbose is set to 1.
   1.160          """
   1.161          
   1.162 @@ -1810,4 +1828,7 @@
   1.163          for msgtype, line in self.verify_log:
   1.164          
   1.165              print line
   1.166 -
   1.167 +    
   1.168 +    def disc_format(self):
   1.169 +    
   1.170 +        return self._format_names[self.disc_type]