nte/README.md

210 lines
4.5 KiB
Markdown
Raw Normal View History

2024-05-24 21:49:27 +02:00
<div align="center">
2024-05-24 22:01:59 +02:00
<img src="logo/nte-colors.svg" width="200" />
2024-05-24 21:49:27 +02:00
<br />
<h1>nte</h1>
</div>
2024-05-22 21:19:37 +02:00
nix template engine - takes some templates, entries and applies the templates to the entries
2024-05-22 21:55:06 +02:00
# examples
check `example/` for a static website written in nte
2024-05-22 21:19:37 +02:00
build and run it using
```sh
nix shell nixpkgs#darkhttpd --command sh -c "nix build -L .#examples.x86_64-linux.default && darkhttpd ./result"
```
the site will be available at http://localhost:8080
2024-05-22 21:55:06 +02:00
the example is a cut down version of [my own website](https://jacekpoz.pl) (of course also written in nte)
# usage
2024-05-22 21:19:37 +02:00
first add nte as an input in your project's flake
```nix
nte = {
url = "git+https://git.jacekpoz.pl/jacekpoz/nte";
inputs.nixpkgs.follows = "nixpkgs";
};
```
then the engine function will be available under
```nix
inputs.nte.engines.${system}.default
```
it accepts 3 arguments:
2024-05-25 17:36:26 +02:00
- `pkgs` - nixpkgs
- `src` - the directory containing all entries and templates
- an attrset of:
- `extraArgs` - an attrset of additional arguments passed to all entries and templates
- `entries` - a list of all entry files to be processed
- `templates` - a list of all template files to be applied
2024-05-22 21:19:37 +02:00
and returns a string containing a shell script that applies the templates to the entries
2024-05-25 17:48:11 +02:00
the flake gives the engine `pkgs`, so when passing the engine function to a derivation, only provide it with the source directory:
```nix
import ./project/default.nix {
# ...
nte = nte.engines.${system}.default ./project;
};
```
then you can use it as in the example derivation below:
2024-05-22 21:19:37 +02:00
```nix
{
nte,
stdenv,
...
}: let
extraArgs = {
foo = 2137;
bar = "dupa";
baz = arg1: arg2: ''
here's arg1: ${arg1}
and here's arg2: ${arg2}
'';
};
entries = [
./entry1.nix
./foo/entry2.nix
./foo/entry3.nix
./bar/entry4.nix
./bar/entry5.nix
./bar/entry6.nix
];
templates = [
./template1.nix
./template2.nix
];
in
stdenv.mkDerivation {
name = "nte-example";
version = "0.1";
src = ./.;
buildPhase = ''
runHook preBuild
${nte {inherit extraArgs entries templates;}}
runHook postBuild
'';
}
```
nte will handle creating directories if your source file structure isn't flat
2024-05-25 17:38:20 +02:00
nte offers a standard library that contains `nixpkgs`, a `getEntry` function that handles an entry's `file` and utility functions found in [stdlib.nix](./stdlib.nix)
2024-05-22 21:19:37 +02:00
## templates
2024-05-25 17:36:26 +02:00
a template can take an arbitrary number of arguments and returns `{ name, format, output }`:
- `name` - used as a template ID for the entries
- `format` - the extension of the output file (ignored if an entry defines `file`)
- `output` - string if in a base template, entry to another template otherwise
2024-05-22 21:19:37 +02:00
example template:
```nix
{
name,
location,
info,
...
}: {
name = "greeting";
2024-05-25 17:36:26 +02:00
format = "txt";
2024-05-22 21:19:37 +02:00
output = ''
Hello ${name}! Welcome to ${location}.
Here's some more information:
${info}
'';
}
```
a template's output can also be an entry to another template:
```nix
{
name,
location,
date,
time,
...
2024-05-25 17:36:26 +02:00
}: {
2024-05-22 21:19:37 +02:00
name = "greeting-with-date";
output = {
template = "greeting";
inherit name location;
info = ''
You're visiting ${location} on ${date} at ${time}!
'';
};
}
```
2024-05-25 17:36:26 +02:00
a template that's inherited from a different template also inherits its format - no need to define it again
2024-05-22 21:19:37 +02:00
## entries
2024-05-25 17:36:26 +02:00
an entry can take an arbitrary number of arguments and returns `{ template, ... }`, the `...` being the desired template's arguments (sans `extraArgs`, those are passed either way)
2024-05-22 21:19:37 +02:00
example entries (using the previous example templates):
```nix
_: {
template = "greeting";
name = "Jacek";
location = "Wrocław";
info = ''
As of 2023, the official population of Wrocław is 674132 making it the third largest city in Poland.
'';
}
```
an entry using the stdlib:
```nix
{
run,
...
}: {
template = "greeting-with-date";
2024-05-25 17:36:26 +02:00
2024-05-22 21:19:37 +02:00
name = "Rafał";
location = "Osieck";
date = run "date +%F";
time = run "date +%T";
}
```
if a binary isn't in `$PATH`, remember that each entry gets `pkgs`:
```nix
{
pkgs,
run,
...
}: let
date = "${pkgs.coreutils-full}/bin/date";
in {
# ...
date = run "${date} +%F";
time = run "${date} +%T";
}
```
2024-05-25 17:36:26 +02:00
nte by default will follow your source file structure, if you want to specify the output location yourself use `file`:
```nix
_: {
# ...
file = "foo/bar.txt";
}
```
in this example the output of this entry will end up at `$out/foo/bar.txt` instead of the default location - a base template's `format` will also be ignored
2024-05-22 21:19:37 +02:00
# license
MIT