From 91c31067d021bf78d700523c8032b23d85cbd387 Mon Sep 17 00:00:00 2001 From: gryf Date: Sun, 2 Oct 2022 15:05:40 +0200 Subject: [PATCH] Readme update --- README.rst | 214 ++++++++++++++++++++--------------------------------- 1 file changed, 80 insertions(+), 134 deletions(-) diff --git a/README.rst b/README.rst index 508f4dc..195ba27 100644 --- a/README.rst +++ b/README.rst @@ -1,14 +1,88 @@ -======================== -Midnight Commander extfs -======================== +=========================== +Midnight Commander extfslib +=========================== + +.. image:: https://img.shields.io/pypi/v/extfslib.svg + :target: https://pypi.python.org/pypi/extfslib + +Midnight Commander extfslib helper library for writing extfs archive plugins. + +Description +=========== + +Extfslib help with building Midnight Commander extf plugins, especially for +those which operates on different kind of archives. + +Simplest plugin built on top of this lib would be: + +.. code::python + + import extfslib + + + class MyArchive(extfslib.Archive): + + ARCHIVER = "fancyarch" + + def list(self): + if not self._contents: + return 1 + + for item in self._contents: + sys.stdout.buffer.write(self.ITEM % item) + + + arch = MyArchive('/path/to/file.fancyarch') + arch.list() + + +In this example class instance should be able to be called with ``list`` method. +All methods: + +- ``list`` +- ``copyin`` +- ``copyout`` +- ``rm`` +- ``mkdir`` +- ``rmdir`` +- ``run`` + +should be implemented if needed, since by default all of them are just defined, +but not implemented. + +Of course, real life example can be a little bit more complicated, since there +would be possible need for adapting ``LINE_PAT`` which is regular expression +for getting attributes for the list compatible with MC along with the ``ITEM`` +which holds the output pattern and utilizes dictionary from ``LINE_PAT``, +``CMD`` which maps between class and archiver commands. Possibly there might be +needed some other adjustments. -Those are Midnight Commander extfs plugins for handling several archive types -mostly known from AmigaOS - like **lha**, **lzx** and disk images like **adf** -and **dms**. Installation ============ +Install from Pypi + +.. code::shell-session + + # pip install extfslib + +or, as a user: + +.. code::shell-session + + $ pip install extfslib --user + +or use virtualenv: + +.. code::shell-session + + $ git clone https://github.com/gryf/mc_extfslib + $ cd mc_extfslib + $ virtualenv venv + $ source venv/bin/activate + (venv) $ pip install + See individual installation plugins below. Basically it comes down to: * copying ``extfslib.py`` and plugin files to ``~/.local/share/mc/extfs.d/`` @@ -19,134 +93,6 @@ See individual installation plugins below. Basically it comes down to: regex/\.pattern$ Open=%cd %p/handler_filename:// -ULha -==== - -ULha is an extfs plugin which can be used with lha/lzh/lharc archives. -Personally, I've use it almost exclusively for archives created long time ago -on my Amiga. Both reading from and writing into archive was implemented. - -Requirements ------------- - -ULha requires `free lha `_ implementation to work. - -Installation ------------- - -* copy ``extfslib.py`` and ``ulha`` to ``~/.local/share/mc/extfs.d/`` -* add or change entry for files handle in ``~/.config/mc/mc.ext``:: - - # lha - regex/\.[lL]([Hh][aA]|[Zz][hH])$ - Open=%cd %p/ulha:// - View=%view{ascii} lha l %f - -ULzx -==== - -ULzx is an extfs plugin which can be used to browse and extract lzx archives, -which are known almost exclusively from Amiga. - -Due to limitations of -`unlzx `_ tools, -only reading is supported. Also be aware, that -`unlzx `_ cannot -extract files individually, so copying entire archive content is not -recommended, since on every single file a full archive extract would be -performed, which in the end would have impact on performance. - -Requirements ------------- - -ULzx requires -`unlzx `_ tool. - -Installation ------------- - -* copy ``extfslib.py`` and ``ulzx`` to ``~/.local/share/mc/extfs.d/`` -* add or change entry for files handle in ``~/.config/mc/mc.ext``:: - - # lzx - regex/\.[lL][zZ][xX]$ - Open=%cd %p/ulzx:// - View=%view{ascii} unlzx -v %f - -UAdf -==== - -UAdf is an extfs plugin suitable for reading .adf, .adz and .dms Amiga floppy -disk images. Due to limitations of the -`unadf `_, file access inside disk image is -read only. - -In case of corrupted or no-dos images, message will be shown. - -Requirements ------------- - -It requires ``unadf`` utility from `ADFlib `_ -repository, with included `that commit -`_ -in particular, which introduced separation between filename and comment -attribute on Amiga Fast File System. - -If it turns out that your distribution doesn't provide proper version of ADFlib, -there will be a need for building it by hand. - -It may be done by using following steps: - -#. Grab the `sources - `_ - and `patches - `_ - from `Debian repository `_. -#. Extract ``unadf_0.7.11a-3.debian.tar.gz`` and ``unadf_0.7.11a.orig.tar.gz`` - into some temporary directory:: - - $ mkdir temp - $ cd temp - $ tar zxf ~/Downloads/unadf_0.7.11a-3.debian.tar.gz - $ tar zxf ~/Downloads/unadf_0.7.11a.orig.tar.gz - $ cd unadf-0.7.11a - -#. Apply Debian patches:: - - $ for i in `cat ../debian/patches/series`; do - > patch -Np1 < "../debian/patches/${i}" - > done - -#. Apply the patch from extras directory:: - - $ patch -Np1 < [path_to_this_repo]/extras/unadf_separate_comment.patch - $ make - $ cp Demo/unadf [destination_path] - -#. Place ``unadf`` binary under directory reachable by ``$PATH``. - -For optional dms support, `xdms `_ utility is -needed. - -Installation ------------- - -* copy ``extfslib.py`` and ``uadf`` to ``~/.local/share/mc/extfs.d/`` -* add or change entry for files handle in ``~/.config/mc/mc.ext``:: - - # adf - type/^Amiga\ .* disk - Open=%cd %p/uadf:// - View=%view{ascii} unadf -lr %f - - # adz - regex/\.([aA][dD][zZ])$ - Open=%cd %p/uadf:// - - # dms - regex/\.([dD][mM][sS])$ - Open=%cd %p/uadf:// - License =======