find-zfile(3)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

NAME

find-zfile - Compressed file support
zfile-setup - Compressed file support setup
zfile-reset - Compressed file support reset

SYNOPSIS

find-zfile "file-name"
zfile-setup "zfile-id" "extension-regex" "list-command"

top-cut-to-regex

bottom-cut-to-regex

body-search-regex1

body-replace-regex1

body-search-regex2

body-replace-regex2

change-slashes

bottom-summary-search-regex

bottom-summary-replace-regex

list-header

extract-command

zfile-setup

zfile-id

extension-regex

piped-extract-command

zfile-reset

DESCRIPTION

find-zfile provides generic support for listing and extracting the contents of compressed files, find-zfile also supports the extraction and loading of the internal files into a buffer.

find-zfile must be configured for each compression utility using zfile-setup. It relies on command-line programs to generate content lists which are used to generate the main file listing, and subsequently, the ability to extract individual files for file extraction support.

For basic content listing support the first 3 arguments must be given to zfile-setup. The first argument is a tool ID, if an existing tool's ID is entered zfile-setup will reconfigure the tool, otherwise a new tool will be created. The second argument, "extension-regex" is used to match a file to this utility, the file's full name is compared with ".*\.<extension-regex>" and if matched the tool will be used. Comparisons are always case insensitive for improved cross-platform behaviour.

The compressed file contents list is generated from executing the user supplied "list-command" and dumping the output into the list buffer. The command is run from the directory containing the compressed file and the following special tags may be used within the "list-command" which get substituted as follows:

%

%"<str>%"

"

<str>

%zb

The token is replaced with the compressed file's base name, i.e. the file name without the path or the extension.

%ze

extension-regex

tar.gz

%zf

The token is replaced with the compressed file's file name, i.e. the file name without the path but with the extension.

%zp

/

%zP

/

%zp

%os-chars(5)

The head of the list output is often unwanted verbose printout, this can be automatically be removed by the use of the "top-cut-to-regex" argument. The argument, if supplied (not an empty string), must be a regex search string matching the end of the text to be removed. If found, all text from the end of the match and before is removed.

To improve usability, the list typically needs reformatting so that items can be selected (first column must be a space) and the list can be sorted on the main column headings. This is achieved by supplying body regex-based search and replace strings, as many can be supplied as required. Note that the result should ensure the information given for each item aligns with the column heading otherwise the sort features are unlike to work. Of particular important is the item name, if this is miss-aligned the item extraction is unlikely to work.

The bottom of the output often has summary information, such as the total number of files a size etc. MicroEmacs puts the summary information for directory listing on the second line, and for consistency zfile does too. This can be best achieved by supplying the bottom-summary regex-based search & replace strings, if the search matched the replace string is inserted into the second line of the buffer. If no summary search is supplied zfile creates a basic file and directory count summary.

For extraction to work, the given list-header line must include the string 'Name' and this sting must be aligned to the start of each item's file or directory name. For copying, viewing or editing files, the same key bindings used in directory listing are also supported by zfile.

The selected files are then extracted by executing the supplied "extract-command" to the selected destination, if copying, or to a temporary directory which is automatically removed later. As with the list-command, the extract command is run from the directory containing the compressed file and the same %z? tokens can be used. The command line must contain a %p or %P token to specify the output location, it can also use the %% & %" tokens, %f for the item name and %*[...] for multiple file support, see help on file-tool-setup(3) for more information on this last token.

When first used, if there are currently no compression utilities configured MicroEmacs will test for the availability of 7zip(1), tar(1) and gunzip(1), and automatically configure the tool appropriately. If these tools, particularly 7zip are available then use of zfile-setup may not be necessary. However, the system setup or the default configuration of MicroEmacs may change, in which case zfile-reset should be run, this will remove any existing zfile configuration for the current platform, including any manual configuration, and regenerate the bast default setup available.

EXAMPLE

For zip file support the freely available unzip(1) command can be used, running "unzip -l /tmp/Jasspa_MicroEmacs_macros.zip" produces an output like the following:

Archive:  Jasspa_MicroEmacs_macros.zip 
  Length     Date   Time    Name 
 --------    ----   ----    ---- 
        0  18-09-24 01:18   macros/ 
     3552  18-09-24 01:18   macros/dmf.emf 
     1413  18-09-24 01:18   macros/langutl.emf 
    22193  18-09-24 01:18   macros/hkcpp.emf 
        . 
        . 
        . 
     2314  18-09-24 01:18   macros/hkrd.emf 
    18910  18-09-24 01:18   COPYING.txt 
     4759  18-09-24 01:18   readme.txt 
 --------                   ------- 
  3461536                   364 files

The following configuration can be used:

zfile-id=zip 
extension-regex=\(zip\|epub\|apk\) 
list-command=unzip -l %zf 
top-cut-to-regex=---\n 
bottom-cut-to-regex=^ --- 
body-search-regex1=        0  \([-\d: ]\{14\}\)   \(.*/\)$ 
body-replace-regex1= d...          0  \1 \2 
body-search-regex2=^\([ \d]\{9\}\)  \([-\d: ]\{14\}\)   \(.*\)$ 
body-replace-regex2= ....  \1  \2 \3 
change-slashes=0 
bottom-summary-search-regex=^ *\(\d+\) +\(\d+ files\) 
bottom-summary-replace-regex=    \1 used in \2 
list-header= Attr     Length        Modified Name 
extract-command=unzip -o %zf %*[ %"%f%"] -d %"%p%"

With this setup, running find-zfile on this zip file will produce the following listing:

ZFile-zip: /tmp/Jasspa_MicroEmacs_macros.zip 
    3461536 used in 364 files 

 Attr     Length        Modified Name 
 d...          0  18-09-24 01:18 macros/ 
 ....       3552  18-09-24 01:18 macros/dmf.emf 
 ....       1413  18-09-24 01:18 macros/langutl.emf 
 ....      22193  18-09-24 01:18 macros/hkcpp.emf 
    . 
    . 
    . 
 ....       2314  18-09-24 01:18 macros/hkrd.emf 
 ....      18910  18-09-24 01:18 COPYING.txt 
 ....       4759  18-09-24 01:18 readme.txt

The top 3 lines are removed as they are not required due to the reformatting requiring a new header line. Each directory line is reformatted first and flags with a 'd' Attribute, the remaining file lines are then reformatted. The bottom summary information is matched with the search regex so the useful information it contains can be pulled out and inserted onto the second line.

As the names of all items now align with the 'Name' string in the new header, the extraction process will get the correct names. Note that files search as dmf.emf will be extracted into a macros sub-directory.

NOTES

find-zfile, zfile-setup, and zfile-reset are macros defined in zfile.emf.