105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# locator
|
|
|
|
A <strike>service</strike> module locator for use with Lapis.
|
|
(Which doesn't use anythng Lapis-specific, so you could use it elsewhere.)
|
|
|
|
Installation:
|
|
|
|
1. subtree this project into the root of your project.
|
|
2. `echo 'return require((...) .. ".init")' > locator.lua` (and make sure it is
|
|
committed!)
|
|
3. Make `locator_config.moon` using the configuration format specified below.
|
|
4. `echo 'return require("locator").models' > models.moon` (to replace the
|
|
models autoloader provided with Lapis with our autoloader)
|
|
|
|
## Usages
|
|
|
|
1. `autoload`: A function to allow automatically loading modules when accessing
|
|
a table.
|
|
2. Implicit autoloaders: The module itself is an autoloader, and can be called
|
|
to create a specialized autoloader that checks directories local to where
|
|
your code is before other paths.
|
|
3. `make_migrations`: A function to make integrating migrations tables from
|
|
multiple Lapis projects into one to streamline applying migrations.
|
|
|
|
### `autoload` function
|
|
|
|
The core functionality is based on the `autoload` function, which returns a
|
|
table with `__call` and `__index` metamethods, allowing things like:
|
|
|
|
```
|
|
locator = require "locator"
|
|
|
|
-- the module itself is an autoloader, so you can grab anything in a
|
|
-- sub-directory like so:
|
|
import Users, Posts from locator.models -- looks in 'models' directory first
|
|
|
|
-- you can also use it (locator.models) as a function to require from models
|
|
Model = locator.models "Model" -- will look for 'models.Model' (& config paths)
|
|
```
|
|
|
|
You can create autoloaders yourself: `models = locator.autoload "models"`
|
|
|
|
### Implicit autoloaders
|
|
|
|
In sub-applications, make requiring things easier by acting like everything is
|
|
in your repository's root:
|
|
|
|
```
|
|
-- returns an autoloader that will try to require from wherever your
|
|
-- sub-application is installed before other paths
|
|
locate = require("locator")(...)
|
|
|
|
util = locate "util" -- will grab *our* utility functions
|
|
```
|
|
|
|
Grab a table of all views: `views = locator.views` (will create an autoloader
|
|
when you try to access it)
|
|
|
|
### `make_migrations` function
|
|
|
|
In your migrations, do something like this:
|
|
|
|
```
|
|
import make_migrations from require "locator"
|
|
import create_table, types from require "lapis.db.schema"
|
|
|
|
return make_migrations {
|
|
[1518418142]: =>
|
|
create_table "articles", {
|
|
{"id", types.serial primary_key: true}
|
|
{"title", types.text unique: true}
|
|
{"content", types.text}
|
|
}
|
|
}
|
|
```
|
|
|
|
Whatever migrations you have defined will be combined with migrations specified
|
|
in sub-applications added to `locator_config`, subject to conditions in the
|
|
config file.
|
|
|
|
## Config
|
|
|
|
Example configuration:
|
|
|
|
```
|
|
{
|
|
{
|
|
path: "applications.users" -- there is a sub-application at this location
|
|
migrations: {after: 1518414112} -- don't run this migration or any before it
|
|
}
|
|
{
|
|
path: "utility" -- another sub-application is here
|
|
}
|
|
}
|
|
```
|
|
|
|
The only required value per item in the configuration is `path`, formatted with
|
|
periods as a directory-separator. Currently, the only point of specifying a
|
|
migrations table is to specify a migration ID to ignore it and every migration
|
|
before it within that sub-application.
|
|
|
|
Without the configuration file, locator will crash with an error, and without
|
|
a path specified, locator doesn't know where else to look for files to require,
|
|
so it is very essential.
|