riscos-stronghelp 0.3.16__tar.gz

riscos_stronghelp-0.3.16/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.1
+Name: riscos_stronghelp
+Version: 0.3.16
+Summary: Extract RISC OS StrongHelp manuals
+Home-page: https://github.com/gerph/riscos-stronghelp-python
+Author: Charles Ferguson
+Author-email: gerph@gerph.org
+License: MIT
+Description: # Python StrongHelp reader
+        
+        This repository contains a reader for the RISC OS StrongHelp manual image format.
+        
+        The Python module is able to be used to parse the format and return the files
+        which are present. The module can also be used as a command line tool to
+        extract the files to a unix file system.
+        
+        
+        ## Installation
+        
+        The tool for extracting StrongHelp files can be installed manually
+        using this repository or through PyPI. To install, use:
+        
+            pip3 install riscos_stronghelp
+        
+        
+        ## Command line
+        
+        At the command line the extraction tool may be used with the
+        supplied shell command:
+        
+            riscos-shextract [--extract-dir <directory>] <stronghelp-file>
+        
+        Or to list files:
+        
+            riscos-shextract --list <stronghelp-file>
+        
+Keywords: riscos
+Platform: UNKNOWN
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=2.7
+Description-Content-Type: text/markdown

riscos_stronghelp-0.3.16/README.md

@@ -0,0 +1,27 @@
+# Python StrongHelp reader
+
+This repository contains a reader for the RISC OS StrongHelp manual image format.
+
+The Python module is able to be used to parse the format and return the files
+which are present. The module can also be used as a command line tool to
+extract the files to a unix file system.
+
+
+## Installation
+
+The tool for extracting StrongHelp files can be installed manually
+using this repository or through PyPI. To install, use:
+
+    pip3 install riscos_stronghelp
+
+
+## Command line
+
+At the command line the extraction tool may be used with the
+supplied shell command:
+
+    riscos-shextract [--extract-dir <directory>] <stronghelp-file>
+
+Or to list files:
+
+    riscos-shextract --list <stronghelp-file>

riscos_stronghelp-0.3.16/riscos_stronghelp/__main__.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python
+"""
+Command line tool for extracting StrongHelp manuals into a directory.
+
+    python -m riscos_stronghelp --extract-dir <directory> <stronghelp-file>
+    python -m riscos_stronghelp --list <stronghelp-file>
+"""
+
+from __future__ import print_function
+import argparse
+import os
+import sys
+
+from riscos_stronghelp.format import StrongHelp, objtype_dir
+
+RISCOS_FILETYPES = {
+    0xFFF: 'Text',
+    0xFFE: 'Command',
+    0xFFD: 'Data',
+    0xFFC: 'Utility',
+    0xFFB: 'BASIC',
+    0xFFA: 'Module',
+    0xFF9: 'Sprite',
+    0xFF8: 'Absolute',
+    0xFF7: 'BBC font',
+    0xFF6: 'Font',
+    0xFF5: 'PoScript',
+    0xFF4: 'Printout',
+    0xFF2: 'Config',
+    0xFF0: 'TIFF',
+    0xFD1: 'BasicTxt',
+    0xFED: 'Palette',
+    0xFEC: 'Template',
+    0xFEB: 'Obey',
+    0xFEA: 'Desktop',
+    0xFE6: 'Unix Ex',
+    0xFE5: 'EPROM',
+    0xFDC: 'SoftLink',
+    0xFD3: 'DebImage',
+    0xFCA: 'Squash',
+    0xFC9: 'SunRastr',
+    0xFAF: 'HTML',
+    0xFAE: 'Resource',
+    0xF89: 'GZip',
+    0xF81: 'JS',
+    0xF80: 'XML',
+    0xF7F: 'XML_DTD',
+    0xF7E: 'XSL',
+    0xF75: 'JSON',
+    0xF74: 'YAML',
+    0xD94: 'ArtWork',
+    0xC85: 'JPEG',
+    0xBBC: 'BBC ROM',
+    0xB61: 'XBM',
+    0xB60: 'PNG',
+    0xB2F: 'WMF',
+    0xAFF: 'DrawFile',
+    0xAAD: 'SVG',
+    0xA91: 'Zip',
+    0xA66: 'WebP',
+    0xA65: 'JPEG2000',
+    0x69E: 'PNM',
+    0x69D: 'Targa',
+    0x69C: 'BMP',
+    0x697: 'PCX',
+    0x695: 'GIF',
+    0x690: 'Clear',
+    0x1C9: 'DiagData',
+    0x132: 'ICO',
+    0x1000: 'Directory',
+}
+
+
+def extract_to_directory(sh, output_dir):
+    """
+    Extract the whole archive to a target directory.
+    """
+    try:
+        os.makedirs(output_dir)
+    except OSError:
+        pass
+
+    for shf in sh:
+        print("Extracting {}".format(shf.filename))
+        filename = os.path.join(output_dir, shf.unix_filename)
+        if shf.objtype == objtype_dir:
+            try:
+                os.makedirs(filename)
+            except OSError:
+                pass
+        else:
+            with open(filename, 'wb') as fh:
+                fh.write(shf.read())
+
+
+def list_files(sh):
+    """
+    List files in the StrongHelp archive.
+    """
+    print("{:<25} {:<12} {:>10}".format("Name", "Type", "Length"))
+    print("-" * 50)
+    for shf in sh:
+        if shf.objtype == objtype_dir:
+            type_str = "Directory"
+        elif shf.filetype == -1:
+            type_str = "None"
+        else:
+            type_str = RISCOS_FILETYPES.get(shf.filetype, "{:03x}".format(shf.filetype))
+
+        print("{:<25} {:<12} {:10d}".format(shf.filename, type_str, shf.length))
+
+
+def setup_argparse():
+    parser = argparse.ArgumentParser(usage="%s [<options>] <strong-help-file>" % (os.path.basename(sys.argv[0]),))
+    parser.add_argument('file', action='store',
+                        help="StrongHelp file to read")
+    parser.add_argument('--extract-dir', action='store',
+                        help="Directory to extract into")
+    parser.add_argument('--list', action='store_true',
+                        help="List files in the StrongHelp file")
+
+    return parser
+
+
+def main():
+    parser = setup_argparse()
+
+    options = parser.parse_args()
+
+    sh = StrongHelp(options.file)
+
+    if options.list:
+        list_files(sh)
+    elif options.extract_dir:
+        extract_to_directory(sh, options.extract_dir)
+    else:
+        # Default behavior if no action specified: list files
+        list_files(sh)
+
+
+if __name__ == '__main__':
+    main()

riscos_stronghelp-0.3.16/riscos_stronghelp/format.py

@@ -0,0 +1,273 @@
+"""
+Parse the StrongHelp file format into structured data.
+
+Example usage::
+
+    from riscos_stronghelp.format import StrongHelp, objtype_dir
+
+    sh = StrongHelp(shfilename)
+
+    try:
+        os.makedirs(output_dir)
+    except OSError:
+        pass
+
+    for shf in sh:
+        print("{}".format(shf.filename))
+        filename = os.path.join(output_dir, shf.unix_filename)
+        if shf.objtype == objtype_dir:
+            try:
+                os.makedirs(filename)
+            except OSError:
+                pass
+        else:
+            with open(filename, 'wb') as fh:
+                fh.write(shf.read())
+"""
+
+import struct
+
+
+# Flags in the StrongHelp file
+flag_owner_read = (1<<0)  # owner read
+flag_owner_write = (1<<1)  # owner write
+flag_locked = (1<<3)  # locked
+flag_public_read = (1<<4)  # public read
+flag_public_write = (1<<5)  # public write
+flag_directory = (1<<8)  # is directory
+
+
+# RISC OS Object types
+objtype_file = 1
+objtype_dir = 2
+
+
+class StrongHelpFormatError(Exception):
+    pass
+
+
+class StrongHelpBlock(object):
+
+    def __init__(self, sh, offset):
+        self.sh = sh
+        self.offset = offset
+
+    def read_bytes(self, size, offset=0):
+        return self.sh.read_bytes(size, self.offset + offset)
+
+    def read_word(self, offset=0):
+        return self.sh.read_word(self.offset + offset)
+
+    def read_string(self, offset=0):
+        return self.sh.read_string(self.offset + offset)
+
+
+class StrongHelpObject(StrongHelpBlock):
+
+    def __init__(self, sh, offset, parent_dir, leafname, loadaddr=0, execaddr=0, flags=0, length=0):
+        super(StrongHelpObject, self).__init__(sh, offset)
+        self.parent_dir = parent_dir
+        self.leafname = leafname
+        self.loadaddr = loadaddr
+        self.execaddr = execaddr
+        self.flags = flags
+        self.length = length
+
+        #print("{} '{}' at &{:x}".format(self.__class__.__name__,
+        #                                self.filename, self.offset))
+
+    def __repr__(self):
+        return "<{}(name='{}', type=0x{:x}, size={})>".format(self.__class__.__name__,
+                                                              self.filename,
+                                                              self.filetype,
+                                                              self.length)
+
+    @property
+    def attributes(self):
+        """
+        RISC OS File attributes.
+        """
+        # Just the bottom 8 bits
+        return self.flags & 0xFF
+
+    @property
+    def objtype(self):
+        """
+        RISC OS object type.
+        """
+        return objtype_dir if (self.flags & flag_directory) else objtype_file
+
+    @property
+    def filetype(self):
+        if self.flags & flag_directory:
+            return 0x1000
+        if self.loadaddr & 0xFFF00000 == 0xFFF00000:
+            return (self.loadaddr >> 8) & 0xFFF
+        return -1
+
+    @property
+    def filename(self):
+        if not self.parent_dir:
+            return self.leafname
+        parent = self.parent_dir.filename
+        return "{}.{}".format(parent, self.leafname)
+
+    @property
+    def unix_filename(self):
+        leafname = self.leafname.replace('/', '.')
+        if not self.parent_dir:
+            return leafname
+
+        if self.filetype in (0xFFF, 0x1000):
+            # A text file or a directory
+            suffix = ''
+
+        elif self.filetype == -1:
+            # Not filetyped - there's a load and exec address.
+            # We will treat these as Data for now - the strongcopy tool
+            # doesn't support load and exec formats.
+            suffix = ',ffd'
+
+        else:
+            # Other filetypes
+            suffix = ',%03x' % (self.filetype,)
+
+        parent = self.parent_dir.unix_filename
+        if parent == '$':
+            return leafname + suffix
+        else:
+            return "{}/{}{}".format(parent, leafname, suffix)
+
+
+class StrongHelpFile(StrongHelpObject):
+
+    def __init__(self, sh, offset, parent_dir, leafname, loadaddr=0, execaddr=0, flags=0, length=0):
+        super(StrongHelpFile, self).__init__(sh, offset, parent_dir, leafname, loadaddr, execaddr, flags, length)
+
+        if offset == 0:
+            # This is a 0 byte file
+            self.size = 0
+
+        else:
+            if self.read_bytes(4, offset=0) != b'DATA':
+                raise StrongHelpFormatError("Bad file entry '{}' at offset &{:x}: "
+                                            "Block header is invalid".format(self.filename,
+                                                                             offset))
+
+            self.size = self.read_word(4)
+            if self.size < self.length:
+                raise StrongHelpFormatError("Bad file entry '{}' at offset &{:x}: "
+                                            "Block is too small ({}) for file length ({})".format(self.filename,
+                                                                                                  offset,
+                                                                                                  self.size,
+                                                                                                  self.length))
+
+    def read(self, encoding=None):
+        if not self.size:
+            data = b''
+        else:
+            data = self.read_bytes(self.length - 8, offset=8)
+        if encoding:
+            data = data.decode(encoding)
+
+        return data
+
+
+class StrongHelpDir(StrongHelpObject):
+
+    def __init__(self, sh, offset, parent_dir, leafname, loadaddr=0, execaddr=0, flags=0, length=0):
+        super(StrongHelpDir, self).__init__(sh, offset, parent_dir, leafname, loadaddr, execaddr, flags, length)
+
+        if self.read_bytes(4, offset=0) != b'DIR$':
+            raise StrongHelpFormatError("Bad directory entry '{}' at offset &{:x}: "
+                                        "Block header is invalid".format(self.filename,
+                                                                         offset))
+
+        self.dir_size = self.read_word(4)
+        self.dir_used = self.read_word(8)
+
+        if self.dir_used > self.dir_size:
+            raise StrongHelpFormatError("Bad directory entry '{}' at offset &{:x}: "
+                                        "Block is too small ({}) for used size ({})".format(self.filename,
+                                                                                            offset,
+                                                                                            self.dir_size,
+                                                                                            self.dir_used))
+        if self.dir_used < 12 + 24:
+            raise StrongHelpFormatError("Bad directory entry '{}' at offset &{:x}: "
+                                        "Block is too small ({}) for directory entry".format(self.filename,
+                                                                                             offset,
+                                                                                             self.dir_used))
+
+        self.objects = []
+        offset = 12
+        while offset < self.dir_used:
+            #print("--- file in dir {}, offset &{:x} ---".format(self.filename, offset))
+            object_offset = self.read_word(offset + 0)
+            loadaddr = self.read_word(offset + 4)
+            execaddr = self.read_word(offset + 8)
+            length = self.read_word(offset + 12)
+            flags = self.read_word(offset + 16)
+            reserved = self.read_word(offset + 20)
+            # FIXME: Assuming the filename encoding is latin-1 (probably correct, but not configurable)
+            name_bytes = self.read_string(offset + 24)
+            name = name_bytes.decode('latin-1')
+            offset += 24 + (len(name_bytes) + 4) & ~3
+
+            if flags & flag_directory:
+                shfile = StrongHelpDir(self.sh, object_offset, parent_dir=self, leafname=name,
+                                       loadaddr=loadaddr, execaddr=execaddr, flags=flags, length=length)
+            else:
+                shfile = StrongHelpFile(self.sh, object_offset, parent_dir=self, leafname=name,
+                                       loadaddr=loadaddr, execaddr=execaddr, flags=flags, length=length)
+            self.objects.append(shfile)
+
+
+class StrongHelp(object):
+
+    def __init__(self, filename=None, data=None):
+        self.filename = filename
+        if data:
+            self.data = data
+        else:
+            with open(filename, 'rb') as fh:
+                self.data = fh.read()
+
+        if self.data[0:4] != b'HELP':
+            raise StrongHelpFormatError("This is not a StrongHelp file")
+
+        self.root_size = self.read_word(4)
+        self.stronghelp_version = self.read_word(8)
+        self.free_list = self.read_word(12)
+
+        self.root_offset = self.read_word(16)
+
+        #print("Root offset = %08x" % (self.root_offset,))
+
+        self.root = StrongHelpDir(self, self.root_offset, parent_dir=None, leafname='$')
+
+    def __iter__(self):
+        """
+        List all the files in the StrongHelp file.
+        """
+        shdirs = [self.root]
+        while shdirs:
+            shdir = shdirs.pop()
+            for shobj in shdir.objects:
+                if isinstance(shobj, StrongHelpDir):
+                    shdirs.append(shobj)
+                yield shobj
+
+    def read_word(self, offset):
+        #print("Read word at &{:x}".format(offset))
+        (data,) = struct.unpack('<L', self.data[offset:offset + 4])
+        #print("  &{:08x} = {}".format(data, data))
+        return data
+
+    def read_bytes(self, size, offset):
+        return self.data[offset:offset + size]
+
+    def read_string(self, offset):
+        start = offset
+        while offset < len(self.data) and self.data[offset:offset+1] != b'\0':
+            offset += 1
+        return self.data[start:offset]

riscos_stronghelp-0.3.16/riscos_stronghelp.egg-info/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.1
+Name: riscos-stronghelp
+Version: 0.3.16
+Summary: Extract RISC OS StrongHelp manuals
+Home-page: https://github.com/gerph/riscos-stronghelp-python
+Author: Charles Ferguson
+Author-email: gerph@gerph.org
+License: MIT
+Description: # Python StrongHelp reader
+        
+        This repository contains a reader for the RISC OS StrongHelp manual image format.
+        
+        The Python module is able to be used to parse the format and return the files
+        which are present. The module can also be used as a command line tool to
+        extract the files to a unix file system.
+        
+        
+        ## Installation
+        
+        The tool for extracting StrongHelp files can be installed manually
+        using this repository or through PyPI. To install, use:
+        
+            pip3 install riscos_stronghelp
+        
+        
+        ## Command line
+        
+        At the command line the extraction tool may be used with the
+        supplied shell command:
+        
+            riscos-shextract [--extract-dir <directory>] <stronghelp-file>
+        
+        Or to list files:
+        
+            riscos-shextract --list <stronghelp-file>
+        
+Keywords: riscos
+Platform: UNKNOWN
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=2.7
+Description-Content-Type: text/markdown

riscos_stronghelp-0.3.16/riscos_stronghelp.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+setup.py
+riscos_stronghelp/__init__.py
+riscos_stronghelp/__main__.py
+riscos_stronghelp/format.py
+riscos_stronghelp.egg-info/PKG-INFO
+riscos_stronghelp.egg-info/SOURCES.txt
+riscos_stronghelp.egg-info/dependency_links.txt
+riscos_stronghelp.egg-info/entry_points.txt
+riscos_stronghelp.egg-info/top_level.txt

riscos_stronghelp-0.3.16/riscos_stronghelp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

riscos_stronghelp-0.3.16/riscos_stronghelp.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+riscos-shextract = riscos_stronghelp.__main__:main
+

riscos_stronghelp-0.3.16/riscos_stronghelp.egg-info/top_level.txt

@@ -0,0 +1 @@
+riscos_stronghelp

riscos_stronghelp-0.3.16/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

riscos_stronghelp-0.3.16/setup.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+"""
+Packaging for the riscos_stronghelp package.
+"""
+
+from distutils.core import setup
+import setuptools  # noqa
+
+from os import path
+# io.open is needed for projects that support Python 2.7
+# It ensures open() defaults to text mode with universal newlines,
+# and accepts an argument to specify the text encoding
+# Python 3 only projects can skip this import
+from io import open
+
+here = path.abspath(path.dirname(__file__))
+
+# Get the long description from the README file
+with open(path.join(here, 'README.md'), encoding='utf-8') as f:
+    long_description = f.read()
+
+
+setup(
+    name = 'riscos_stronghelp',
+    packages = ['riscos_stronghelp'],
+    version = "0.3.16",
+    license='MIT',
+    description = 'Extract RISC OS StrongHelp manuals',
+    long_description = long_description,
+    long_description_content_type = 'text/markdown',
+    author = 'Charles Ferguson',
+    author_email = 'gerph@gerph.org',
+    url = 'https://github.com/gerph/riscos-stronghelp-python',
+    keywords = ['riscos'],
+    entry_points={ 'console_scripts': ['riscos-shextract = riscos_stronghelp.__main__:main'] },
+    install_requires= [
+        ],
+    classifiers= [
+            'Development Status :: 4 - Beta',
+            'Intended Audience :: Developers',
+            'License :: OSI Approved :: MIT License',
+            'Programming Language :: Python :: 2.7',
+            'Programming Language :: Python :: 3',
+            "Operating System :: OS Independent",
+        ],
+    python_requires='>=2.7',
+)