- Reference
- Options in
.nvim-thyme.fnl - Functions
thyme.loaderthyme.setupor(thyme:setup)- Functions at
thyme.fennel - Functions
pcall-able - Keymaps
<Plug>(thyme-alternate-file)<Plug>(thyme-operator-echo-compile-string){motion}<Plug>(thyme-operator-echo-eval){motion}<Plug>(thyme-operator-echo-eval-compiler){motion}<Plug>(thyme-operator-echo-macrodebug){motion}<Plug>(thyme-operator-print-compile-string){motion}<Plug>(thyme-operator-print-eval){motion}<Plug>(thyme-operator-print-eval-compiler){motion}<Plug>(thyme-operator-print-macrodebug){motion}
- Commands
- Options in
The configurations for nvim-thyme should be managed in
.nvim-thyme.fnl at the path vim.fn.stdpath('config') returns.
When .nvim-thyme.fnl is missing at the directory on nvim startup,
nvim-thyme will ask you to generate it with recommended settings:
See the file .nvim-thyme.fnl.example.
(default: {})
The options to be passed to fennel functions which takes an options table
argument: allowedGlobals, correlate, useMetadata, and so on.
See the official Fennel API documentation: https://fennel-lang.org/api
(default: If fnl/ directory exists at vim.fn.stdpath('config'), "fnl";
otherwise, "lua")
The relative path to vim.fn.stdpath('config') directory for your Fennel
runtime module files.
It only supports <fnl-dir>/?.fnl and <fnl-dir>/?/init.fnl relative to
vim.fn.stdpath('config').
Note
3rd-party plugins written in Fennel are supposed to be compiled to lua/ as
general nvim plugins written in Lua.
For the path management of macro files, see macro-path.
(default: a too long string)
;; A string created by concatenating one of the following tables with `;` as the delimiter.
;; If you have `fnl/` directory at `stdpath("config")`,
["./fnl/?.fnlm"
"./fnl/?/init.fnlm"
"./fnl/?.fnl"
"./fnl/?/init-macros.fnl"
"./fnl/?/init.fnl"]
;; or, if you don't have `fnl/` directory at `stdpath("config")`,
["./fnl/?.fnlm"
"./fnl/?/init.fnlm"
"./fnl/?.fnl"
"./fnl/?/init-macros.fnl"
"./fnl/?/init.fnl"
"%s/lua/?.fnlm"
"%s/lua/?/init.fnlm"
"%s/lua/?.fnl"
"%s/lua/?/init-macros.fnl"
"%s/lua/?/init.fnl"]
;; where %s represents `stdpath("config")` each.The path patterns for fennel.macro-path to find Fennel macro modules.
Relative path markers (./) are internally copied and replaced with each
directory path on &runtimepath. (Feel free to skip over it, but the
replacements are optimized, filtered by the directories suffixed by ? in this
option, e.g, with the default option value, ./ prefixes will be only replaced
with the paths that contains fnl directory on &runtimepath.)
Note: Unlike the macro-path option, nvim-thyme does not provide any
option to modify fennel.path. For Fennel runtime modules, nvim-thyme is
only designed to search through the path: ./fnl/?.fnl;./fnl/?/init.fnl where
each . prefix represents the result path of (vim.fn.stdpath :config).
(default: 5)
Keep the number of backups for rollback at most. Set 0 to disable it.
Note
The rollback system only works for compile error; nvim-thyme does not provide any rollback system for nvim runtime error. Such a feature should be realized independently of a runtime compiler plugin.
(default: vim.notify)
It is a function which takes the same arguments as vim.notify.
You can filter out specific notifications by this option. See .nvim-thyme.fnl.example for an example.
(default: false)
Disable treesitter highlights on the outputs
of [commands][commands] and keymaps.
nvim-thyme will just output plain texts instead.
This option is added
since it's unfeasible to continue to address every issues
on the unstable highlighting output rendering
of the experimental vim._extui feature in the nvim v0.12.0 nightly.
(default: nil)
The default compiler-options for
Fennel Wrapper Commands like :Fnl. If nil,
it inherits the values from the root compiler-options above.
(default: "overwrite")
With parinfer-rust integration, the arguments for :Fnl and :FnlCompile are modified before execution in Cmdline.
This option determines the command history behavior with the modified input.
Available methods:
"overwrite": Overwrite the original input with the modified input in the command history."append": Append the modified input to the command history in addition to the original input."ignore": Ignore the modified input. Just keep the original input.
(default: "omit")
This option determines the behavior for Fennel Wrapper Commands like :Fnl.
This option only works when parinfer-rust integration is
activated and the option
command.cmd-history.method is set to "overwrite"
or "append".
Available options:
"omit": Trim all the trailing parentheses in the command history."keep": Keep the trailing parentheses in the command history.
(default: nil)
The default compiler-options for nvim-thyme operator keymaps like
<Plug>(thyme-operator-eval). If nil, it inherits the values from the root
compiler-options above.
(default: {})
The format is {mode {action lhs}}. For example,
{:n {:alternate-file "<LocalLeader>a"}
[:n :x] {:operator-echo-compile-string "<LocalLeader>s"
:operator-echo-eval "<LocalLeader>e"
:operator-echo-eval-compiler "<LocalLeader>c"
:operator-echo-macrodebug "<LocalLeader>m"}}The keys will be only mapped on a buffer whose filetype is "fennel" other than
alternate-file; the key for alternate-file will be also mapped when the
filetype is "lua" addition to "fennel".
Available Actions:
- alternate-file
- operator-echo-compile-string
- operator-echo-eval
- operator-echo-eval-compiler
- operator-echo-macrodebug
- operator-print-compile-string
- operator-print-eval
- operator-print-eval-compiler
- operator-print-macrodebug
They are internally translated into <Plug> keymaps. See Keymaps.
(default: [:BufWritePost :FileChangedShellPost])
What autocmd events should check the changes of Fennel source file.
Note that the watch system on autocmd events can only detect the changes on the buffers loaded in current nvim session.
(default: "*.{fnl,fnlm}")
The autocmd pattern for match (path) to check the changes of Fennel source file.
(default: "clear-all")
The strategy how to handle Fennel runtime module updates on the autocmd detection on watch.event.
Available Strategies:
"clear-all": clear all the Lua caches by nvim-thyme"clear": clear the cache of the module and its dependencies"recompile": recompile the module and its dependencies
(default: "clear-all")
The same as the option watch.strategy, but for Fennel macro modules.
Caution
The macro-strategy "recompile" is unstable yet.
Important
The functions exposed to the users are limited to require("thyme") module.
The other modules would cause breaking changes without any deprecation notice.
The core function of nvim-thyme. The loader is to be appended to package.loaders manually by user before loading any Fennel modules.
-- Wrapping the `require` in `function-end` is important for lazy-load.
table.insert(package.loaders, function(...)
return require("thyme").loader(...) -- Make sure to `return` the result!
end)Important
Before loading any Fennel module, you also have to prepend
/a/path/to/thyme/compile which contains a substring "/thyme/compile" in
&runtimepath, for example,
vim.opt.rtp:prepend(vim.fn.stdpath('cache') .. '/thyme/compiled').
It also defines an autocmd group ThymeWatch to keep compiled lua files
up-to-date.
Important
No arguments are allowed by thyme.setup.
You should manage all the options in .nvim-thyme.fnl
instead.
For the Lua ideom require("thyme").setup() in Fennel, the method call syntax
(thyme:setup) is supported. Therefore, the following weird syntax with . and
additional parentheses
((require :thyme) (. :setup))
;; or
((-> (require :thyme) (. :setup)))can be replaced by the following syntax with :
(-> (require :thyme) (: :setup))This function is to be called after VimEnter wrapped in vim.schedule, or later. For example,
vim.api.nvim_create_autocmd("VimEnter", {
once = true,
callback = vim.schedule_wrap(function()
require("thyme").setup()
require("others")
end,
})or if you carefully manage your config files where some Fennel file are loaded
in vim.schedule on VimEnter elsewhere, put the following code in such a
Fennel file:
(-> (require :thyme)
(: :setup))Provides a set of Fennel wrapper functions corresponding to Fennel Wrapper Commands.
Unless otherwise noted, the functions named with _ are equivalent to those
with -.
:= require("thyme").fennelSome thyme.call.<foo.bar.baz>-modules are provided.
They are useful to call them without worrying about thyme's validity, and about the interface dependencies when you are considering another Fennel compiler system.
Equivalent to :ThymeCacheClear, but it should work without thyme.setup.
This function is useful to be called on githooks without worrying about thyme's validity, and about the interface dependencies when you were considering another Fennel compiler system.
For example, add the following lines in .githooks/post-checkout with
executable permission:
if type nvim >/dev/null; then
nvim --headless -c "lua pcall(require, 'thyme.call.cache.clear')" +q
fiEquivalent to :ThymeCacheOpen, but it should work without thyme.setup.
The keymaps are defined with thyme.setup. You can change the mappings by the keymap.mappings option in .nvim-thyme.fnl.
Note
Currently, the keymaps only supports the Fennel modules on &runtimepath.
This is a keymap version of :FnlAlternate.
The operator keymapping to pass {motion} text to
fennel.compile-string and echo the results.
The echo version does not mess up cmdline-history as :echo does not.
The operator keymapping to pass {motion} text to fennel.eval
and echo the results.
The echo version does not mess up cmdline-history as :echo does not.
The operator keymapping to pass (eval-compiler {motion}) text to
fennel.eval and echo the results.
The echo version does not mess up cmdline-history as :echo does not.
The operator keymapping to pass (macrodebug {motion}) text to
fennel.eval and echo the results.
The echo version does not mess up cmdline-history as :echo does not.
The operator keymapping to pass {motion} text to
fennel.compile-string and print the results.
The print version does not mess up cmdline-history as :print does not.
The operator keymapping to pass {motion} text to fennel.eval
and print the results.
The print version does not mess up cmdline-history as :print does not.
The operator keymapping to pass (eval-compiler {motion}) text to
fennel.eval and print the results.
The print version does not mess up cmdline-history as :print does not.
The operator keymapping to pass (macrodebug {motion}) text to
fennel.eval and print the results.
The print version does not mess up cmdline-history as :print does not.
The commands are defined by thyme.setup.
Display the result of applying fennel.eval to {fnl-expr}, but
respects your &runtimepath.
The evaluation can include the current buffer lines within the given range. The range support only works when the following conditions are satisfied:
- The filetype of current buffer is
"fennel". (:echo &ft == "fennel"should return1.) - One of them is satisfied:
- The config file
.nvim-thyme.fnlexists at the root of the current buffer. - The current buffer file is under
/tmpdirectory. - The current buffer is not a readable file.
- The config file
Display the result of applying fennel.dofile but to
[bufname], but respects your &runtimepath.
Without [bufname], it evaluates the current buffer.
Almost equivalent to :FnlBuf. However, it does not evaluate the
[bufname] (or current buffer), but only returns the compiled lua results.
It does not affect the file system.
Display the result of applying fennel.dofile to [file], but
respects your &runtimepath.
Without [file], it evaluates the current file.
Almost equivalent to :FnlFile; however, it does not evaluate the
[file] (or current file), but only returns the compiled lua results.
It does not affect the file system.
Almost equivalent to :Fnl. However, it does not evaluate the
{fnl-expr}, but only returns the compiled lua results.
It does not affect the file system.
(This range support is experimental.)
Same as :FnlBufCompile.
Same as :FnlFileCompile.
Try to open the alternate file of current buffer:
- For a Fennel file, find the corresponding Lua file.
- For a Lua file, find the corresponding Fennel file.
This command will search in the following order:
- The thyme's Lua caches
- The directory of the target file
- The corresponding
/fnl/or/lua/directory
Remove all the cache, data, state, and log files, which are implicitly managed by nvim-thyme, and remove the hash of .nvim-thyme.fnl from the trust database.
This command is so safe as it does not affect your .nvim-thyme.fnl and any of your configuration files.
When you have some issues with nvim-thyme, try :ThymeCacheClear first. When the command does not resolve your issue, then try this command :ThymeUninstall.
Open your .nvim-thyme.fnl file.
Open a readonly buffer to demonstrate the recommended configuration.
Clear all the Lua caches managed by nvim-thyme.
If you failed to define the command :ThymeCacheClear for some reasons, please execute :lua require('thyme.call.cache.clear') manually in Command line instead.
See also :ThymeUninstall.
Open the root directory of the Lua caches managed by nvim-thyme.
Two concepts:
-
Active backup: The backup to rollback if you fail to compile or evaluate a Fennel module at nvim runtime. You can switch to the active backup by :ThymeRollbackSwitch.
-
Mounted backup: The backup to rollback regardless of your corresponding Fennel module stability. You can mount an active backup by :ThymeRollbackMount, or all the active backups by :ThymeRollbackUnmountAll.
Prompt to switch to the active backup of the {target}.
Any compile errors of the {target} of Fennel module will be rolled back to the
active backup.
Note that switching the active backup also affects the mounted backup of
{target}.
Mount the active backup of the {target}.
Neovim will load the mounted backup instead of your module with the same name. You should run :ThymeRollbackUnmount or :ThymeRollbackUnmountAll to restore the mount state.
To select which backup to mount, use :ThymeRollbackSwitch.
Unmount the mounted backups for the {target}.
Unmount the mounted backups.