mjolnir._asm.modules

Home: https://github.com/asmagill/mjolnir_asm._asm

Functions to capture information about, install and remove luarocks for mjolnir modules.
While it is tailored specifically to use with the mjolnir modules, it should
work with luarocks in general.

This is very basic, and experimental. Note that any luarocks compatible arguments
specified after the tree for remove and install are passed in as is, so format
accordingly, and very few cases have been tested so far, so it's still very beta!

These tools assume a default Luarocks tree named "mjolnir" exists. You can always
specify a different tree name if you wish. To use the "mjolnir" tree, make sure
something like the following is in your ~/.luarocks/config.lua file:

       rocks_trees = {
               { name = [[user]], root = home..[[/.luarocks]] },
               { name = [[mjolnir]], root = home..[[/.mjolnir/rocks]] },
               { name = [[system]], root = [[/usr/local]] },
       }

Note that this ends up loading practically all of the luarocks modules into memory
and may leave Mjolnir in an inconsistent state concerning available modules. You
should probably only require this module when you specifically want it, and then
run mjolnir.reload() when done.

mjolnir-tools is a command-line tool which is installed into your tree bin
directory (~/.mjolnir/rocks/bin, if you use the mjolnir tree as shown above). To use
this utility, make sure that the directory is in your shell's PATH or copy/link the
file to somewhere that is.

To change the default tree from "mjolnir" to something else, you can use the module's
default_tree variable (see Variables), or to make it permanent, create a file in your
.mjolnir directory named .mjolnir._asm.modules.lua and put the following into it
(change "mjolnir" to match your preferred default tree):

    return {
        -- default_tree: is the luarocks tree to use by default
        default_tree = "mjolnir",
    }

available

mjolnir._asm.modules.available([name] [, exact]) -> table

Returns a table containg the manifest of available (remote) modules which contain
name in their name. If exact is true, then the module name must match name exactly.
If name and exact are both missing, then it returns all available modules, similar
to "luarocks search --all".

default_tree

mjolnir._asm.modules.default_tree = string

By default, this module assumes the default luarocks tree is "mjolnir". You
can set this variable to another value if you wish the default tree to be
something else.
If you want to permanently change the default tree to something else, create
a file in your .mjolnir/ directory named ".mjolnir._asm.modules.lua" and put
the following into it (change "mjolnir" to match your preferred default tree):

       return {
            -- default_tree: is the luarocks tree to use by default
            default_tree = "mjolnir",
       }

install

mjolnir._asm.modules.install(name [, tree [, ... ]]) -> name, version | false, error

Tries to install the specified module into the specified tree (defaults to mjolnir).
If other arguments are provided after tree, they are passed into luarocks as is, so
format accordingly. Returns the name and version of the module installed, if successful.

installed

mjolnir._asm.modules.installed([tree]) -> table

Returns a table containing the luarocks manifest of installed modules for a tree.
If tree is absent, it defaults to the "mjolnir" tree. If tree is --all, then it
returns the manifest for all installed modules. Otherwise it returns the manifest
for the specified tree.

output

mjolnir._asm.modules.output( n ) -> string

Because Luarocks outputs most of it's status and errors via io.stdout:write(),
we capture the stderr and stdout streams during module install and removal. This
function returns the output of the most recent - n install or remove. When n is
not provided, it is 0, resulting in the most recent install or remove.

output

mjolnir._asm.modules.output[]

Because Luarocks outputs most of it's status and errors via io.stdout:write(),
we capture the stderr and stdout streams during module install and removal. To
see the full output of the last install or remove invocation, just look at the
end of this array, i.e.
print(mjolnir._asm.modules.output[#mjolnir._asm.modules.output])

remove

mjolnir._asm.modules.remove(name [, tree [, ... ]]) -> boolean [, error]

Tries to remove the specified module from the specified tree (defaults to mjolnir).
If other arguments are provided after tree, they are passed into luarocks as is,
so format accordingly. Returns true or false indicating success or failure.

sorted_versions

mjolnir._asm.modules.sorted_versions(manifestdata [, desc]) -> table

Returns a sorted array of the versions available in the manifest data provided.
This manifest data is a specific module's result value from a search. If desc
is true return the list in descending order; otherwise in ascending order.

trees

mjolnir._asm.modules.trees([name]) -> table

Returns a table of the luarocks tree definition name, or all of the tree definitions
if name is not provided.

versions

mjolnir._asm.modules.versions([tree]) -> table

Returns a table containing the list of modules in the specified tree (if tree is absent,
then default to tree "mjolnir"; if tree is --all, then all available trees) with the
following atributes:
installed = the version string for the installed version
available = the latest version string available for download
local_only = a boolean indicating that the module does not appear in any known repository
upgrade = a boolean indicating if the available version is greater than the installed one