fey.naomi/fennel-ls
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add docsets information and some reorg

Browse Source
This commit is contained in:
Michele Campeotto 2025-02-28 23:46:50 +01:00 committed by Phil Hagelberg
parent 32350ec44b
commit 1f123c6baa
3 changed files with 286 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
docs/docsets.md Normal file
View File

@ -0,0 +1,124 @@
# fennel-ls external library documentation
fennel-ls can load external documentation and completion information for
situations where it's not available at runtime.
## Installing docsets
The documentation files (also called docsets) are loaded from
`~/.local/share/fennel-ls/docsets/` and they are regular Lua files that contain
a single table describing the information to be displayed by the language
server.
> fennel-ls follows the XDG base directory convention, so if you changed
> `$XDG_DATA_HOME` the files will be loaded from the location you specified.
To install a new docset and make it available to fennel-ls, download the `.lua`
file for your library and place it in `~/.local/share/fennel-ls/docsets/`.
> You can find a list of the available docsets on the [Fennel
> wiki](http://wiki.fennel-lang.org/LanguageServer).
Next, you have to tell fennel-ls to load this library by adding it to the
`flsproject.fnl` file at the root of your project.
```fnl
{:libraries {:library-name true}}
```
The library name you specify here must match the name of the docset file you
downloaded.
Restart the LSP client or your editor and the new completions should be
available.
## Creating docsets
The top level Lua table in the docset should contain symbol names as keys and
*bindings* as values.
```fnl
{:symbol-a {
;; binding table
}
:symbol-b {
;; binding table
}}
```
Each binding is table that describes that symbol. This is an example from the
Tic-80 library:
```fnl
{:binding "elli"
:metadata {:fls/itemKind "Function"
:fnl/arglist ["x" "y" "a" "b" "color"]
:fnl/docstring "This function draws a filled ellipse of the desired
a, b radiuses and color with its center at x, y.
"}}
```
- `binding` is the full name of the symbol, so if this symbol is part of a
module the name should be in the form `module.symbol`
- `fls/itemKind` describes the kind of this symbol, it can be any one of the
[CompletionItemKind](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#completionItemKind)
values from the LSP specification.
- `fnl/arglist` and `fnl/docstring` should follow the usual Fennel conventions.
Symbols can also have sub-symbols, represented as fields in the binding
table. This is an example from the LÖVE library:
```fnl
{:love {:binding "love"
:metadata {:fls/itemKind "Module"
:fnl/docstring "Modules can have documentation too"}
:fields {:conf {:binding "love.conf"
:metadata {:fls/itemKind "Function"
:fnl/arglist ["t"]
:fnl/docstring "Using the love.conf function,
you can set some configuration options, [...]"}
```
### Complete example
Here is a simplified complete example to show all the pieces together, mainly
the top level table that contains all the bindings.
```fnl
{
{:math {:binding "math"
:metadata {:fls/itemKind "Module"
:fnl/docstring "A module for math functions"}
:fields {:atan {:binding "math.atan"
:metadata {:fls/itemKind "Function"
:fnl/arglist [a]
:fnl/docstring "Arc tangent"}}
:phi {:binding "math.phi"
:metadata {:fls/itemKind "Constant"
:fnl/docstring "It's golden!"}}}}}
{:config {:binding "config"
:metadata {:fls/itemKind "Function"
:fnl/arglist []
:fnl/docstring "A function to read the config options"}}}
}
```
The easiest way of generating this format is to create the table in a Fennel
script and then serializing it using the `fennel.view` function.
## Compilation
Finally, to be usable by fennel-ls the table needs to be compiled to Lua and
installed in the docsets directory.
```sh
fennel library-docset.fnl > library-docset.lua
cp library-docset.lua $HOME/.local/share/fennel-ls/docsets/
```
Refer to the
[fennel-ls-docsets](http://git.sr.ht/~technomancy/fennel-ls-docsets) repository
for an example of how to script these steps.

116
docs/installation.md Normal file
View File

@ -0,0 +1,116 @@
# Installation
## Manual installation
To install from source on Linux or macOS, run:
```sh
$ git clone https://git.sr.ht/~xerool/fennel-ls
$ cd fennel-ls
$ make docs-love2d # if you plan to use love2d
$ make
```
The only dependency is a Lua installation.
This build will create a `fennel-ls` executable for you using your default
system `lua`; use `make LUA=luajit` etc to use a different Lua version.
Run `make install PREFIX=$HOME` to put it in `~/bin` or `sudo make install` for
a system wide install.
The default build will not include documentation for [LÖVE](https://love2d.org)
due to the unfortunate licensing of their documentation. You can opt-in to
build with these docs anyway with `make docs-love2d` but the resulting build
may have legal complications when distributed.
## Packages
#### Arch Linux
I think `fennel-ls` and `fennel-ls-git` may be in the AUR.
#### NixOS
If you are using NixOS, you can use the included `/flake.nix` or
`/default.nix`.
#### Debian/Ubuntu
Unofficial `.deb` packages are available at
[https://apt.technomancy.us](https://apt.technomancy.us).
#### Luarocks
Alternatively, `fennel-ls` is available in LuaRocks, but recommendation is to
use one of the other packaging solutions over LuaRocks, if available.
```sh
luarocks install fennel-ls
```
## Editor integration
The following instructions assume you have installed `fennel-ls` as described
in the previous section.
### Emacs
On Emacs 30+, eglot will use fennel-ls automatically if it can be found in your `$PATH`.
For older versions:
```lisp
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs '(fennel-mode . ("fennel-ls"))))
```
This code tells eglot to connect fennel-ls to your fennel-mode buffers.
### Neovim
If you're using neovim+lspconfig, use this snippet:
```lua
require("lspconfig").fennel_ls.setup({})
```
If you're also using mason and you want to install fennel-ls that way, you can
use mason-lspconfig to ensure fennel-ls is installed:
```lua
require("mason-lspconfig").setup {
ensure_installed = {"fennel_ls"}
}
```
### Sublime Text
Install the the [LSP
package](https://packagecontrol.io/packages/LSP) from Package Control.
You can configure the LSP plugin to use fennel-ls directly by editing your
`Packages/User/LSP.sublime-settings` file, which can be opened via "Preferences
\> Package Settings \> LSP \> Settings" from the menu or with the Preferences: LSP
Settings command from the Command Palette.
You should add an entry to the top-level `"clients"` object (creating it if it
doesn't exist), with this configuration:
```json
"clients": {
"fennel-ls": {
"enabled": true,
"selector": "source.fennel",
"command": ["fennel-ls"]
}
}
```
If you run into problems, check the [LSP Client Configuration
reference](https://lsp.sublimetext.io/client_configuration/) and double-check
the location of fennel-ls on the $PATH is visible to Sublime Text.
### Other editors
It should be possible to set up for other text editors, but the instructions
depend on which editor you use. Generally you need to tell your editor:
* "fennel-ls" is a language server program on the $PATH
* it should be run for fennel files.

152
docs/manual.md
View File

@ -1,128 +1,67 @@
# Manual # Manual
This document goes over how to set up fennel-ls.
## Installation
### fennel-ls Language Server Binary
On Linux or Mac OS,
```sh
$ git clone https://git.sr.ht/~xerool/fennel-ls
$ cd fennel-ls
$ make docs-love2d # if you plan to use love2d
$ make
```
will create a `fennel-ls` executable for you using your default system `lua`;
use `make LUA=luajit` etc to use a different Lua version.
Run `make install PREFIX=$HOME` to put it in `~/bin` or `sudo make install` for
a systemwide install.
The default build will not include documentation for [LÖVE](https://love2d.org)
due to the unfortunate licensing of their documentation. You can opt-in to
build with these docs anyway with `make docs-love2d` but the resulting build
may have legal complications when distributed.
#### Arch Linux
I think `fennel-ls` and `fennel-ls-git` may be in the AUR.
#### NixOS
If you are using NixOS, you can use the included `/flake.nix` or `/default.nix`.
#### Debian/Ubuntu
Unofficial `.deb` packages are available at
[https://apt.technomancy.us](https://apt.technomancy.us).
#### Luarocks
Alternatively, `fennel-ls` is available in LuaRocks. Luarocks is kind of a pain to support though.
```sh
luarocks install fennel-ls
```
### Emacs
prerequisites: You have installed the [fennel-ls binary](#fennel-ls-language-server-binary).
For Emacs 30+, eglot will use fennel-ls automatically if its on the $PATH.
For older versions:
```lisp
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs '(fennel-mode . ("fennel-ls"))))
```
This code tells eglot to connect fennel-ls to your fennel-mode buffers.
### Neovim
prerequisites: You have installed the [fennel-ls binary](#fennel-ls-language-server-binary).
If you're using neovim+lspconfig, use this snippet:
```lua
require("lspconfig").fennel_ls.setup({})
```
If you're also using mason and you want to install fennel-ls that way, you can
use mason-lspconfig to ensure fennel-ls is installed:
```lua
require("mason-lspconfig").setup {
ensure_installed = {"fennel_ls"}
}
```
### Sublime Text
prerequisites: You have installed the [fennel-ls binary](#fennel-ls-language-server-binary) and the [LSP Sublime Text package](https://packagecontrol.io/packages/LSP) from Package Control.
You can configure the LSP plugin to use fennel-ls directly by editing your `Packages/User/LSP.sublime-settings` file, which can be opened via "Preferences > Package Settings > LSP > Settings" from the menu or with the Preferences: LSP Settings command from the Command Palette.
You should add an entry to the top-level `"clients"` object (creating it if it doesn't exist), with this configuration:
```json
"clients": {
"fennel-ls": {
"enabled": true,
"selector": "source.fennel",
"command": ["fennel-ls"]
}
}
```
If you run into problems, check the [LSP Client Configuration reference](https://lsp.sublimetext.io/client_configuration/) and double-check the location of fennel-ls on the $PATH is visible to Sublime Text.
### Other editors
It should be possible to set up for other text editors, but the instructions
depend on which editor you use. Generally you need to tell your editor:
* "fennel-ls" is a language server program on the $PATH
* it should be run for fennel files.
This document has information on how to configure and use fennel-ls after you [installed it](installation.md).
## Configuration ## Configuration
fennel-ls can be configured by creating a file named `flsproject.fnl` in your
workspace root. Any setting that isn't provided will be filled in with the
defaults, which means that `{}` is a valid configuration with default settings.
You can provide different settings in the same shape as the default settings to
override the defaults.
The default `flsproject.fnl` settings are: 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 ```fnl
{:fennel-path "./?.fnl;./?/init.fnl;src/?.fnl;src/?/init.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" :macro-path "./?.fnl;./?/init-macros.fnl;./?/init.fnl;src/?.fnl;src/?/init-macros.fnl;src/?/init.fnl"
:lua-version "lua5.4" :lua-version "lua5.4"
:libraries {:love2d false ; requires building with love2d support :libraries {}
:tic-80 false}
:extra-globals "" :extra-globals ""
:lints {:unused-definition true :lints {:unused-definition true
:unknown-module-field true :unknown-module-field true
:unnecessary-method true :unnecessary-method true
:unnecessary-tset true
:unnecessary-do true
:redundant-do true
:match-should-case true
:bad-unpack true :bad-unpack true
:var-never-set true :var-never-set true
:op-with-no-arguments true :op-with-no-arguments true
:multival-in-middle-of-call true}} :multival-in-middle-of-call true
:no-decreasing-comparison false}
``` ```
extra-globals: Space separated list of allowed global identifiers; in addition to a set of predefined lua globals. - `extra-globals`: Space separated list of allowed global identifiers that will
be added to a set of predefined lua globals.
version: One of lua51, lua52, lua53, lua54, intersection, or union. 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.
libraries: This setting controls which extra documentation fennel-ls can load in to your environment. I've only done this for tic-80 for now. - `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 and `false` to disable it.
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 `love2s.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 ## Usage
@ -134,7 +73,6 @@ to be macro files.
## Features ## Features
Feature | Locals | Fields | Builtin Globals | Across Files | Builtins | Macros | User globals | Feature | Locals | Fields | Builtin Globals | Across Files | Builtins | Macros | User globals |
--------------- | ------ | ------ | --------------- | ------------ | -------- | ------ | ------------ | --------------- | ------ | ------ | --------------- | ------------ | -------- | ------ | ------------ |
Completions | [X] | [X] | [X] | [X] | [X] | [X] | [ ] | Completions | [X] | [X] | [X] | [X] | [X] | [X] | [ ] |
@ -155,10 +93,12 @@ purposes, it's recommended to put an underscore at the end. For example:
``` ```
## CLI Usage ## CLI Usage
fennel-ls can be used as a linter from the command line:
```sh ```sh
fennel-ls --lint my-file.fnl f2.fnl # prints diagnostics for the files given fennel-ls --lint my-file.fnl f2.fnl # prints diagnostics for the files given
``` ```
This will analyze the given files, and print out all compiler errors and lints, This will analyze the given files and print out all compiler errors and lints,
without launching a server. A successful exit code indicates no problems found. without launching a server. A successful exit code indicates no problems found.