147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
## NAME
|
|
|
|
fennel-ls - Intelligent editing features for fennel files.
|
|
|
|
## SYNOPSIS
|
|
|
|
**fennel-ls** [**-\-lint** _filename_] | [**-\-fix** _filename_] | [**-\-help**]
|
|
|
|
## DESCRIPTION
|
|
|
|
This document has information on how to configure and use fennel-ls after you
|
|
[installed it](installation.md).
|
|
|
|
## OPTIONS
|
|
|
|
**-\-lint** _filename [...filename]_
|
|
Prints diagnostics for the files given. A successful exit code
|
|
indicates no problems were found.
|
|
|
|
**fennel-ls** **-\-fix** [-y] [_filename_] [...]
|
|
|
|
Run suggested fixes from linters on files.
|
|
|
|
**-\-help** Display usage summary.
|
|
|
|
With no arguments, it waits for Language Server Protocol messages on stdin.
|
|
|
|
fennel-ls can be used with no configuration beyond connecting it to your text
|
|
editor, but if you are using external libraries you will need to add them to
|
|
the configuration to get completions, documentation, and correct diagnostics.
|
|
|
|
If a [docset is available](http://wiki.fennel-lang.org/LanguageServer) for the
|
|
library you are using:
|
|
|
|
- download it and place it in `~/.local/share/fennel-ls/docsets/`
|
|
- create a `flsproject.fnl` in the root directory of your project
|
|
- add the docset to it, it must match the name of the file you downloaded,
|
|
without the `.lua` extension:
|
|
```fnl
|
|
{:libraries {:library-name true}}
|
|
```
|
|
|
|
If a docset is not available, add the globals created by the library to the
|
|
`extra-globals` field, separated by spaces, so that they are not reported as
|
|
errors:
|
|
|
|
```fnl
|
|
{:extra-globals "module1 module2 function1 function2"}
|
|
```
|
|
|
|
The rest of this document provides additional details on the configuration and
|
|
usage of fennel-ls.
|
|
|
|
## CONFIGURATION
|
|
|
|
fennel-ls can be configured by creating a file named `flsproject.fnl` in the
|
|
root of your project.
|
|
|
|
The default settings are below, you only need to provide the settings you want
|
|
to change. An empty table `{}` is a valid configuration and serves as a marker
|
|
to indicate where the project root is located.
|
|
|
|
```fnl
|
|
{:fennel-path "./?.fnl;./?/init.fnl;src/?.fnl;src/?/init.fnl"
|
|
:macro-path "./?.fnl;./?/init-macros.fnl;./?/init.fnl;src/?.fnl;src/?/init-macros.fnl;src/?/init.fnl"
|
|
:lua-version "lua5.4"
|
|
:libraries {}
|
|
:extra-globals ""
|
|
:lints {:unused-definition true
|
|
:unknown-module-field true
|
|
:unnecessary-method true
|
|
:unnecessary-tset true
|
|
:unnecessary-do true
|
|
:redundant-do true
|
|
:match-should-case true
|
|
:bad-unpack true
|
|
:var-never-set true
|
|
:op-with-no-arguments true
|
|
:multival-in-middle-of-call true
|
|
:no-decreasing-comparison false}
|
|
```
|
|
|
|
- `extra-globals`: Space separated list of allowed global identifiers that will
|
|
be added to a set of predefined lua globals.
|
|
|
|
These identifiers and any of their fields will be considered valid and won't
|
|
produce diagnostics. Use this when importing a library for which
|
|
documentation is not available.
|
|
|
|
- `version`: One of `lua5.1`, `lua5.2`, `lua5.3`, `lua5.4`, `intersection`, or
|
|
`union`.
|
|
|
|
`intersection` represents the APIs that are available in *every* supported
|
|
Lua version, `union` represents APIs available in *any* version.
|
|
|
|
- `libraries`: This setting controls which extra documentation fennel-ls will
|
|
load in your environment. Each entry in the table is the name of the library
|
|
and a boolean, `true` to enable the library.
|
|
|
|
The name of the library is the name of a file that will be loaded from
|
|
`~/.local/share/fennel-ls/docsets/` after appending the `.lua` extension.
|
|
|
|
For example, if the table contains `{:love2d true}` the file `love2d.lua`
|
|
will be loaded from `~/.local/share/fennel-ls/docsets/`.
|
|
|
|
The available docsets are listed on the [Fennel
|
|
wiki](http://wiki.fennel-lang.org/LanguageServer).
|
|
|
|
See the full [docsets documentation](docsets.md) for more information on how
|
|
to find, install, or create docsets.
|
|
|
|
> fennel-ls respects the XDG convention, so if you changed `$XDG_DATA_HOME`
|
|
> the files will be loaded from the location you specified.
|
|
|
|
## USAGE
|
|
|
|
Fennel-ls *cannot* tell the difference between a regular file and a macro file.
|
|
You can ask fennel-ls to **treat your file as a macro file** if the first line
|
|
exactly matches `;; fennel-ls: macro-file`. Expect this to change at some point
|
|
in the future when I come up with a better way to specify which files are meant
|
|
to be macro files.
|
|
|
|
## FEATURES
|
|
|
|
| Feature | Locals | Fields | Builtin Globals | Across Files | Builtins | Macros | User globals |
|
|
| --------------- | ------ | ------ | --------------- | ------------ | -------- | ------ | ------------ |
|
|
| Completions | [X] | [X] | [X] | [X] | [X] | [X] | [ ] |
|
|
| Hover | [X] | [X] | [X] | [X] | [X] | [X] | [ ] |
|
|
| Goto Definition | [X] | [X] | N/A | [X] | N/A | [ ] | [ ] |
|
|
| Rename | [X] | [ ] | N/A | [ ] | N/A | [ ] | [ ] |
|
|
| Goto Reference | [X] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
|
|
|
Fennel-ls can report all fennel compiler errors, plus a few custom lints.
|
|
|
|
Unused locals will be flagged unless they begin or end with an underscore. If
|
|
you have a local that is unused in your code but necessary for pattern matching
|
|
purposes, it's recommended to put an underscore at the end. For example:
|
|
|
|
```fennel
|
|
(case [1 1 2 3 5 8]
|
|
[a_ a_] (print "First two elements are equal"))
|
|
```
|
|
|
|
## LICENSE
|
|
|
|
Copyright © 2023-2025, Released under the MIT/X11 license
|