diff --git a/README.md b/README.md index 87e3448..dbc9d65 100644 --- a/README.md +++ b/README.md @@ -55,24 +55,6 @@ You must commit the Lua into your configuration or plugin so that it can be loaded by native Neovim Lua systems, with absolutely no knowledge of the Fennel it originated from. -### Compiling all files - -If you for whatever reason need to compile _all_ of your files to Lua at once -then you may do so by invoking the `compile-all-files` function like so. - -```lua -require('nfnl')['compile-all-files']() -``` - -In the case where you're absolutely adamant that you need to `.gitignore` your -compiled Lua output, this can be used after you `git pull` to ensure everything -is compiled. I strongly advise committing your Lua for performance _and_ -stability reasons however. - -This project was designed around the principal of compiling early and then never -needing to compile again unless you make changes. I thought long and hard about -the tradeoffs so you don't have to. - ## Configuration nfnl is configured on a per directory basis using `.nfnl.fnl` files which also @@ -331,6 +313,36 @@ just include this in your `.nfnl.fnl` configuration file for your project. (default.fnl-path->lua-path (.. "some-other-dir/" rel-fnl-path))))} ``` +### API + +Although you can require any internal nfnl Lua module and call it's functions +([full index of internal modules and functions][apidoc]) there is a specific +module, `nfnl.api` ([documentation][api-module-doc]), that is designed to be +hooked up to your own functions, mappings and autocmds. + +The functions within are designed to "do the right thing" with little to no +configuration. You shouldn't need them in normal use, but they may come in +useful when you need to fit nfnl into an interesting workflow or system. + +As an example, here's how and why you'd use the `compile-all-files` function +from another Fennel file to, you guessed it, compile all of your files. + +```fennel +(local nfnl (require :nfnl.api)) + +;; Takes an optional directory as an argument, defaults to (vim.fn.getcwd). +(nfnl.compile-all-files) +``` + +In the case where you're absolutely adamant that you need to `.gitignore` your +compiled Lua output, this can be used after you `git pull` to ensure everything +is compiled. However, I strongly advise committing your Lua for performance +_and_ stability. + +This project was designed around the principal of compiling early and then never +needing to compile again unless you make changes. I thought long and hard about +the tradeoffs so you don't have to. These tools are here for when I'm wrong. + ## Development If you have nfnl installed in Neovim you should be able to just modify Fennel @@ -409,3 +421,4 @@ experience. [fd]: https://github.com/sharkdp/fd [nfnl-plugin-example]: https://github.com/Olical/nfnl-plugin-example [lua-in-git-justifications]: https://github.com/Olical/nfnl/issues/5#issuecomment-1655447175 +[api-module-doc]: https://github.com/Olical/nfnl/blob/main/docs/api/nfnl/api.md diff --git a/docs/api/nfnl/api.md b/docs/api/nfnl/api.md new file mode 100644 index 0000000..d8ee915 --- /dev/null +++ b/docs/api/nfnl/api.md @@ -0,0 +1,20 @@ +# Api.fnl + +**Table of contents** + +- [`compile-all-files`](#compile-all-files) + +## `compile-all-files` +Function signature: + +``` +(compile-all-files dir) +``` + +Compiles all files in the given dir (optional), defaulting to the current working directory. Returns a sequential table with each of the files compilation result. + + Will do nothing if you execute it on a directory that doesn't contain an nfnl configuration file. + + + diff --git a/docs/api/nfnl/init.md b/docs/api/nfnl/init.md index fc37d3c..cbe54fa 100644 --- a/docs/api/nfnl/init.md +++ b/docs/api/nfnl/init.md @@ -2,18 +2,8 @@ **Table of contents** -- [`compile-all-files`](#compile-all-files) - [`setup`](#setup) -## `compile-all-files` -Function signature: - -``` -(compile-all-files dir) -``` - -Compiles all files in the given directory, defaulting to the current working directory. - ## `setup` Function signature: diff --git a/fnl/nfnl/api.fnl b/fnl/nfnl/api.fnl new file mode 100644 index 0000000..bbaeee6 --- /dev/null +++ b/fnl/nfnl/api.fnl @@ -0,0 +1,14 @@ +(local {: autoload} (require :nfnl.module)) +(local compile (autoload :nfnl.compile)) +(local config (autoload :nfnl.config)) + +(fn compile-all-files [dir] + "Compiles all files in the given dir (optional), defaulting to the current working directory. Returns a sequential table with each of the files compilation result. + + Will do nothing if you execute it on a directory that doesn't contain an nfnl configuration file." + (let [dir (or dir (vim.fn.getcwd)) + {: config : root-dir : cfg} (config.find-and-load dir)] + (when config + (compile.all-files {: root-dir : cfg})))) + +{: compile-all-files} diff --git a/fnl/nfnl/init.fnl b/fnl/nfnl/init.fnl index 03c7820..c64c7fa 100644 --- a/fnl/nfnl/init.fnl +++ b/fnl/nfnl/init.fnl @@ -1,7 +1,4 @@ (local {: autoload} (require :nfnl.module)) -(local compile (autoload :nfnl.compile)) -(local config (autoload :nfnl.config)) -(local notify (autoload :nfnl.notify)) (local callback (autoload :nfnl.callback)) (when vim @@ -22,14 +19,4 @@ (fn setup [] "A noop for now, may be used one day. You just need to load this module for the plugin to initialise for now.") -(fn compile-all-files [dir] - "Compiles all files in the given directory, defaulting to the current working directory." - - (local dir (or dir (vim.fn.getcwd))) - (let [{: config : root-dir : cfg} (config.find-and-load dir)] - (if config - (notify.info "Compilation complete.\n" (compile.all-files {: root-dir : cfg})) - (notify.warn "No .nfnl.fnl configuration found.")))) - -{: setup - : compile-all-files} +{: setup} diff --git a/lua/nfnl/api.lua b/lua/nfnl/api.lua new file mode 100644 index 0000000..4890641 --- /dev/null +++ b/lua/nfnl/api.lua @@ -0,0 +1,18 @@ +-- [nfnl] Compiled from fnl/nfnl/api.fnl by https://github.com/Olical/nfnl, do not edit. +local _local_1_ = require("nfnl.module") +local autoload = _local_1_["autoload"] +local compile = autoload("nfnl.compile") +local config = autoload("nfnl.config") +local function compile_all_files(dir) + local dir0 = (dir or vim.fn.getcwd()) + local _let_2_ = config["find-and-load"](dir0) + local config0 = _let_2_["config"] + local root_dir = _let_2_["root-dir"] + local cfg = _let_2_["cfg"] + if config0 then + return compile["all-files"]({["root-dir"] = root_dir, cfg = cfg}) + else + return nil + end +end +return {["compile-all-files"] = compile_all_files} diff --git a/lua/nfnl/init.lua b/lua/nfnl/init.lua index 3ff97ba..902a40a 100644 --- a/lua/nfnl/init.lua +++ b/lua/nfnl/init.lua @@ -1,9 +1,6 @@ -- [nfnl] Compiled from fnl/nfnl/init.fnl by https://github.com/Olical/nfnl, do not edit. local _local_1_ = require("nfnl.module") local autoload = _local_1_["autoload"] -local compile = autoload("nfnl.compile") -local config = autoload("nfnl.config") -local notify = autoload("nfnl.notify") local callback = autoload("nfnl.callback") if vim then if (0 == _G.vim.fn.has("nvim-0.9.0")) then @@ -20,16 +17,4 @@ end local function setup() return "A noop for now, may be used one day. You just need to load this module for the plugin to initialise for now." end -local function compile_all_files(dir) - local dir0 = (dir or vim.fn.getcwd()) - local _let_5_ = config["find-and-load"](dir0) - local config0 = _let_5_["config"] - local root_dir = _let_5_["root-dir"] - local cfg = _let_5_["cfg"] - if config0 then - return notify.info("Compilation complete.\n", compile["all-files"]({["root-dir"] = root_dir, cfg = cfg})) - else - return notify.warn("No .nfnl.fnl configuration found.") - end -end -return {setup = setup, ["compile-all-files"] = compile_all_files} +return {setup = setup}