src/vfs/extfs/helpers/README

   1             Writing scripts for Midnight Commander's external vfs
   2
   3 IMPORTANT NOTE: There may be some bugs left in extfs. Enjoy.
   4
   5 Starting with version 3.1, the Midnight Commander comes with so called
   6 extfs, which is one of the virtual filesystems. This system makes it
   7 possible to create new virtual filesystems for the GNU MC very easily.
   8
   9 To handle requests, create a shell/perl/python/etc script/program
  10 (with executable permissions) in $(libexecdir)/mc/extfs.d
  11 or in ~/.local/share/mc/extfs.d/.
  12
  13 (Note: $(libexecdir) should be substituted for actual libexecdir path
  14 stored when configured or compiled, like /usr/local/libexec or /usr/libexec).
  15
  16 Assign a vfs suffix. For example, if you have .zip file, and would like
  17 to see what's inside it, path will be
  18
  19 /anypath/my.zip/uzip://some_path/...
  20
  21 In this example, .zip is suffix, but I call vfs 'uzip'. Why? Well,
  22 what this vfs essentially does is UNzip. UN is too long, so I choosed
  23 U. Note that sometime in future filesystem like zip may exist: It will
  24 take whole tree and create .zip file from it. So /usr/zip:// will be
  25 zipfile containing whole /usr tree.
  26
  27 If your vfs does not require file to work on, add '+' to the end of name.
  28 Note, that trailing '+' in file name is not a part of vfs name, it is
  29 just an vfs attribue. So you have not use it in vfs commands:
  30
  31 cd rpms://
  32
  33 is correct command, and
  34
  35 cd rpms+://
  36
  37 is incorrect command.
  38
  39
  40 * Commands that should be implemented by your shell script
  41 ----------------------------------------------------------
  42
  43 Return zero from your script upon completion of the command, otherwise
  44 nonzero for failure or in case of an unsupported command.
  45
  46 $libdir/extfs/prefix command [arguments]
  47
  48 * Command: list archivename
  49
  50 This command should list the complete archive content in the following format
  51 (a little modified ls -l listing):
  52
  53 AAAAAAA NNN OOOOOOOO GGGGGGGG SSSSSSSS DATETIME [PATH/]FILENAME [-> [PATH/]FILENAME[/]]]
  54
  55 where (things in [] are optional):
  56
  57 AAAAAAA  is the permission string like in ls -l
  58 NNN      is the number of links
  59 OOOOOOOO is the owner (either UID or name)
  60 GGGGGGGG is the group (either GID or name)
  61 SSSSSSSS is the file size
  62 FILENAME is the filename
  63 PATH     is the path from the archive's root without the leading slash (/)
  64 DATETIME has one of the following formats:
  65             Mon DD hh:mm[:ss], Mon DD YYYY, MM-DD-YYYY hh:mm[:ss]
  66
  67             where Mon is a three letter English month name, DD is day
  68             01-31 (can be 1-31, if following Mon), MM is month 01-12,
  69             YYYY is four digit year, hh is hours, mm is minutes,
  70             and ss is optional seconds.
  71
  72 If the -> [PATH/]FILENAME part is present, it means:
  73
  74 If permissions start with an l (ell), then it is the name that symlink
  75 points to. (If this PATH starts with a MC vfs prefix, then it is a symlink
  76 somewhere to the other virtual filesystem (if you want to specify path from
  77 the local root, use local:/path_name instead of /path_name, since /path_name
  78 means from root of the archive listed).
  79
  80 If permissions do not start with l, but number of links is greater than one,
  81 then it says that this file should be a hardlinked with the other file.
  82
  83 * Command: copyout archivename storedfilename extractto
  84
  85 This should extract from archive archivename the file called
  86 storedfilename (possibly with path if not located in archive's root
  87 [this is wrong. current extfs strips paths! -- pavel@ucw.cz])
  88 to file extractto.
  89
  90 * Command: copyin archivename storedfilename sourcefile
  91
  92 This should add to the archivename the sourcefile with the name
  93 storedfilename inside the archive.
  94
  95 Important note: archivename in the above examples may not have the
  96 extension you are expecting to have, like it may happen that
  97 archivename will be something like /tmp/f43513254 or just
  98 anything. Some archivers do not like it, so you'll have to find some
  99 workaround.
 100
 101 * Command: rm archivename storedfilename
 102
 103 This should remove storedfilename from archivename.
 104
 105 * Command: mkdir archivename dirname
 106
 107 This should create a new directory called dirname inside archivename.
 108
 109 * Command: rmdir archivename dirname
 110
 111 This should remove an existing directory dirname. If the directory is
 112 not empty, mc will recursively delete it (possibly prompting).
 113
 114 * Command: run
 115
 116 Undocumented :-)
 117
 118 ---------------------------------------------------------
 119
 120 Don't forget to mark this file executable (chmod 755 ThisFile, for example)
 121
 122 For skeleton structure of executable, look at some of filesystems
 123 similar to yours.
 124
 125 ---------------------------------------------------------
 126
 127 In constructing these routines, errors will be made, and mc will not display
 128 a malformed printing line.  That can lead the programmer down many false
 129 trails in search of the bug.  Since this routine is an executable shell script
 130 it can be run from the command line independently of mc, and its output will
 131 show on the console or can be redirected to a file.
 132
 133 * Putting it to use
 134 ----------------------------------------------------------
 135 The file .mc.ext in a home directory, and in mc's user directory (commonly
 136 /etc/mc), contains instructions for operations on files depending
 137 on filename extensions.  It is well documented in other files in this
 138 distribution, so here are just a few notes specifically on use of the
 139 Virtual File System you just built.
 140
 141 There are entries in .mc.ext defining a few operations that can be done on a
 142 file from an mc panel.  Typically they are annotated with a hash mark and a
 143 file extension like this:
 144
 145 # zip
 146
 147 There must be a way to find the file by extension, so the next line does
 148 that.  In essence it says "identify the string ".zip" or (|) ".ZIP" at the
 149 end ($) of a filename":
 150
 151 regex/\.(zip|ZIP)$
 152
 153 The operations themselves follow that. They must be indented by at least a
 154 space, and a tab works as well.  In particular, the Open operation will
 155 now use your new virtual file system by cd'ing to it like this:
 156
 157    Open=%cd zip:%d/%p
 158
 159 This is the line used when a file is highlighted in a panel and the user
 160 presses <Enter> or <Return>.  The contents of the archive should show just
 161 as if they were in a real directory, and can be manipulated as such.
 162 The rest of the entry pertains to use of the F3 View key:
 163
 164    View=%view{ascii} unzip -v %f
 165
 166 And perhaps an optional icon for X:
 167
 168    Icon=zip.xpm
 169
 170 And perhaps an operation to extract the contents of the file, called from
 171 a menu selection:
 172
 173    Extract=unzip %f '*'
 174
 175 This is just an example.  The current entry for .zip files has a menu selection
 176 of 'Unzip' which could be used in place of 'Extract'.  What goes here depends
 177 on what items you have in, or add to, the menu system, and that's another
 178 subject.  The sum of this is the .mc.ext entry:
 179
 180 # zip
 181 regex/\.(zip|ZIP)$
 182    Open=%cd %p/uzip://
 183    View=%view{ascii} unzip -v %f
 184    Icon=zip.xpm
 185    Extract=unzip %f '*'
 186
 187 Add an entry like this to the .mc.ext file in a user's home directory, If you
 188 want others to have it, add it to the mc.ext file in the mc system directory,
 189 often /etc/mc/mc.ext.  Notice this file is not prepended with a dot.
 190
 191 Once all this is done, and things are in their proper places, exit mc if you
 192 were using it, and restart it so it picks up the new information.
 193
 194 That's all there is to it.  The hardest part is making a listing function
 195 that sorts the output of a system listing command and turns it into a form
 196 that mc can use.  Currently awk (or gawk) is used because nearly all systems
 197 have it. If another scripting language is available, like perl, that could
 198 also be used.