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