lsptar.lsp

Module index

source download

Module: lsptar.lsp

Run newLISP program(s) in a tar file.

Author: Ralph Ronnquist, Realthing Entertainment Pty Ltd
Version: 1.0, 2015-04-08 initial release
Version: 1.1, 2015-06-05 handle gzip compressed tar
Version: 1.2, 2015-06-08 revised to using -tar argument
Version: 1.3, 2015-06-10 fixed up invocation alternatives

Run NewLISP Application in "tar" or "tgz" File

This module defines a load-tar function for loading newlisp sources from a tar file, and it includes a use of this to discover and act on a "-tar myapp.tgz main.lsp" command line argument phrase by "running" it. Or more precisely, it acts by instrumenting the load method to load files from "myapp.tgz" where possible, and then it loads "main.lsp" from "myapp.tgz".

Alternatively, if the main script argument is omitted, or not in the tar file, then the first file of the tar is loaded instead. In either case, the load function remains instrumented to load from the tar file first, both during and after the main script loading.

If the loading of the main script returns, the load function remains instrumented and the in-core copy of the tar file remains. Subsequent load will keep loading from the tar file first, and the function read-tar can be used to read data files from the tar file. The function clear-tar may be used to restore the load function (which is preserved as newlisp-load), and discard the tar file. Also, any subsequent load-tar will discard a previous tar file.

Using lsptar.lsp in .init.lsp

The module is set up to be used as an initial script on the command line. Thus, a principle command line using lsptar.lsp would be as follows. 
  % newlisp lsptar.lsp -tar myapp.tgz
Obviously "mayapp.tgz" could be something else; it is just the name of the tar file to be run. As such, it may be either uncompressed or gzip compressed; lsptar.lsp detects which it is by looking at the first few bytes.

The lsptar.lsp script is "silent" if the "-tar myapp.tgz" argument phrase is missing. The idea is that it's part of your .init.lsp script, so that you don't need to mention it on the command line, and you still can use newlisp as per usual without the "-tar" argument. In that case, the command line would simply be as follows. 
  % newlisp -tar myapp.tgz
It may come in handy to bewilder an audience.

Embedded lsptar

To install this module as an embedded script interpreter, you need to do the following: 
  % newlisp lsptar.lsp -x lsptar
  % chmod a+x lsptar
But before that, you might want to revise lsptar.lsp to explicitly use the command line without requiring a "-tar" marker argument. Doing so gives you the executable program lsptar to use as script interpreter, as in the following examples (assuming lsptar in PATH): Further, you might also define an executable wrapper script, say ".wrapper" with a single line, as follows: 
  #!/full/path/to/lsptar myapp.tgz
And set up symbolic links for alternative main scripts: 
  % ln -s .wrapper foo.lsp
  % ln -s .wrapper bar.lsp
By that set up, you get foo.lsp and bar.lsp to be run as alternative main scripts in the gzip compressed tar file "myapp.tgz", and the wrapper file itself will load the first file in myapp.tgz as main script. If you take some care in the naming of files, it may look a bit like a busybox set up.

Using lsptar.lsp on the command line

You use the lsptar.lsp module as is, without embedding, by nominating the tar file, as in: 
  % newlisp lsptar.lsp -tar myapp.tgz main.lsp
or possibly (not recommended): 
  % newlisp -tar myapp.tgz main.lsp lsptar.lsp
The latter example will of course first load "main.lsp" from the current working directory, if it is found there, and then, if the main.lsp loading returns, lsptar.lsp will load it from the tar file, if it is found there. Basically the second example relies on newlisp being gracefully silent about "peculiar" and missing files, but it's a recipe for major confusion if main.lsp happens to be around.

Notes

Note that the whole tar is read (and uncompressed if needed) into memory in full, and things will go haywire with excessively large tar files.

Note that uncompression uses the newlisp standard module zlib.lsp.

Note that the original, standard load function is preserved as newlisp-load.

Note that the tar file index building is tied to the GNU tar file format, and it might not work well with other formats. If you feel strongly for using a different tar file format, you may need to rework the index building procedure accordingly.

Note that in order to use a tar file for data only, it should contain an empty first file. Data content is then obtained after loading by using the read-tar function. Or if you are keen, by explicitly slicing TarData with region lookup through TarIndex.

Note that tar loading only handles path names into the tar, and all other load function usage variants succumb to their normal handling.

Reference Documentation of Functions



§

load-tar

syntax: (load-tar tar main)
Loads main and all its dependent files from the tar file tar. If main is omitted, nil or not present in tar, then the first file in tar is loaded instead. The tar file tar may be uncomressed or gzip compressed, where the latter requires the newlisp standard module zlib.lsp.

If and when the loading of the main file returns, the tar file remains in core, and the load function remains instrumented. Any subsequent load will be from the tar file first. Use clean-tar to discard the in-core tar file, and restore the load function.



§

clear-tar

syntax: (clear-tar)
Cleans up after load-tar by restoring the load function from newlisp-load, and clearing the symbols TarData and TarIndex.



§

read-tar

syntax: (read-tar name)
Returns the content of the named entry in the current tar file, previously loaded via load-tar. Use this function to read data files in the tar file. A "data only" tar file needs a blank first entry. The function returns nil if name is not in the current tar file.

- ∂ -

generated with newLISP  and newLISPdoc