Reorganize the readme files
This commit is contained in:
XeroOl
parent
d015776f5e
commit
e493b0e21f
116
README.md
116
README.md
@ -3,116 +3,20 @@
|
||||
|
||||
Provides intelligent editing features for fennel files.
|
||||
|
||||
## 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
|
||||
```
|
||||
will create a bleeding-edge latest git `fennel-ls` binary for you.
|
||||
|
||||
#### Arch Linux
|
||||
I think `fennel-ls` and `fennel-ls-git` is in the AUR.
|
||||
|
||||
#### Luarocks
|
||||
`fennel-ls` is available in LuaRocks.
|
||||
```sh
|
||||
luarocks install fennel-ls
|
||||
```
|
||||
#### NixOS
|
||||
If you are using NixOS, you can use the included `/flake.nix` or `/default.nix`.
|
||||
|
||||
### 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"}
|
||||
}
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
## Usage
|
||||
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.
|
||||
|
||||
## CLI Usage
|
||||
```sh
|
||||
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.
|
||||
|
||||
# Default Settings
|
||||
fennel-ls can be configured over LSP. Any setting that's not provided will be filled in with the defaults, which means that `{}` will be a valid configuration with default settings. You can provide different settings in the same shape as the default settings in order to override the defaults.
|
||||
|
||||
fennel-ls default settings:
|
||||
```json
|
||||
{
|
||||
"fennel-ls": {
|
||||
"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",
|
||||
"version": "lua54",
|
||||
"checks": {
|
||||
"unused-definition": true,
|
||||
"unknown-module-field": true,
|
||||
"unnecessary-method": true,
|
||||
"bad-unpack": true,
|
||||
"var-never-set": true,
|
||||
"op-with-no-arguments": true,
|
||||
"multival-in-middle-of-call": true
|
||||
},
|
||||
"native-libraries": []
|
||||
"extra-globals": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
extra-globals: Space separated list of allowed global identifiers; in addition to a set of predefined lua globals.
|
||||
|
||||
version: one of lua51, lua52, lua53, or lua54.
|
||||
|
||||
native-libraries: either [] or ["tic80"] for now. This setting controls which extra documentation fennel-ls can load in to your environment.
|
||||
|
||||
Your editor can send these settings using one of these two methods:
|
||||
* The client sends an `initialize` request with the structure `{initializationOptions: {"fennel-ls": {...}}, ...}`
|
||||
* The client sends a `workspace/didChangeConfiguration` notfication containing the field `{settings: {"fennel-ls": {YOUR_SETTINGS}}}`
|
||||
## Quick Links
|
||||
* [Install](docs/manual.md#installation)
|
||||
* [Configuration](docs/manual.md#configuration)
|
||||
* [Features](docs/feature-matrix.md)
|
||||
* [Packaging](docs/packaging.md)
|
||||
|
||||
## License
|
||||
fennel-ls is licensed under the MIT license. See LICENSE for more info.
|
||||
This project also contains files from other projects:
|
||||
* fennel and deps/fennel.lua are compiled from [fennel](https://git.sr.ht/~technomancy/fennel) [MIT license]
|
||||
* deps/faith.lua is from [faith](https://git.sr.ht/~technomancy/faith) [MIT license]
|
||||
* deps/pl/stringio.lua is from [Penlight](https://github.com/lunarmodules/Penlight) [MIT license]
|
||||
* deps/dkjson.lua is from [dkjson](http://dkolf.de/dkjson-lua/) [MIT license]
|
||||
* `fennel` and `deps/fennel.lua` are compiled from [fennel](https://git.sr.ht/~technomancy/fennel) [MIT license]
|
||||
* `deps/faith.lua` is from [faith](https://git.sr.ht/~technomancy/faith) [MIT license]
|
||||
* `deps/pl/stringio.lua` is from [Penlight](https://github.com/lunarmodules/Penlight) [MIT license]
|
||||
* `deps/dkjson.lua` is from [dkjson](http://dkolf.de/dkjson-lua/) [MIT license]
|
||||
|
||||
* src/fennel-ls/docs/generated/* contains files generated from other sources. It contains information from:
|
||||
* `src/fennel-ls/docs/generated/*` contains files generated from other sources. It contains information from:
|
||||
* the [lua](https://lua.org) reference [MIT license]
|
||||
* [TIC80's "learn" webpage](https://tic80.com/learn) [MIT license]
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
# Creating a new lint
|
||||
# How to add a new lint
|
||||
|
||||
## Creating a new lint
|
||||
To start, you can set up all the plumbing:
|
||||
|
||||
1. Go into `src/fennel-ls/lint.fnl` and create a new function.
|
||||
@ -10,7 +12,7 @@ To start, you can set up all the plumbing:
|
||||
3. Enable your lint! In `src/fennel-ls/state.fnl`, find the
|
||||
`default-configuration` variable, and turn your check on by default.
|
||||
|
||||
# Writing your lint
|
||||
## Writing your lint
|
||||
Now, the fun part: writing your lint function.
|
||||
|
||||
The goal is to check whether the given arguments should emit a warning, and
|
||||
@ -20,7 +22,7 @@ what message to show. The current loops in `check` go over every:
|
||||
|
||||
More loops might have been added since I wrote this document.
|
||||
|
||||
## Input arguments
|
||||
### Input arguments
|
||||
All lints give you `self` and `file`. They're mostly useful to pass to other
|
||||
functions.
|
||||
* `self` is the table that represents the language server. It carries metadata
|
||||
@ -35,7 +37,7 @@ macroexpansion. Make sure that the AST you're checking is inside of
|
||||
the user won't be able to see or edit the code your lint is warning about.
|
||||
|
||||
The next arguments depend on which loop the lint is in:
|
||||
### If your lint is linting definitions:
|
||||
#### If your lint is linting definitions:
|
||||
* `symbol` is the symbol being bound. It is just a regular fennel sym.
|
||||
* `definition` is a table full of information about what is being bound:
|
||||
* `definition.binding` is the symbol again.
|
||||
@ -66,11 +68,11 @@ the definitions will be:
|
||||
{:definition `(my-expression) :binding `y :multival 2 :keys [:foo :bar]}
|
||||
```
|
||||
|
||||
### If your lint is linting calls (to functions or specials, not macros)
|
||||
#### If your lint is linting calls (to functions or specials, not macros)
|
||||
* `head` is the symbol that is being called. It is the same as `(. call 1)`.
|
||||
* `call` is the list that represents the call.
|
||||
|
||||
## Output:
|
||||
### Output:
|
||||
Your lint function should return `nil` if there's nothing to report, or
|
||||
return a diagnostic object representing your lint message.
|
||||
|
||||
@ -92,5 +94,5 @@ The return value should have these fields:
|
||||
tests that only check for the presence or absence of a lint.
|
||||
* `codeDescription`: Use the name of your function.
|
||||
|
||||
## Testing:
|
||||
### Testing:
|
||||
I will think about this later. :)
|
||||
118
docs/manual.md
Normal file
118
docs/manual.md
Normal file
@ -0,0 +1,118 @@
|
||||
# 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
|
||||
```
|
||||
will create a bleeding-edge latest git `fennel-ls` binary for you.
|
||||
|
||||
#### Arch Linux
|
||||
I think `fennel-ls` and `fennel-ls-git` may be in the AUR.
|
||||
|
||||
#### Luarocks
|
||||
Alternatively, `fennel-ls` is available in LuaRocks. Luarocks is kind of a pain to support though.
|
||||
```sh
|
||||
luarocks install fennel-ls
|
||||
```
|
||||
#### NixOS
|
||||
If you are using NixOS, you can use the included `/flake.nix` or `/default.nix`.
|
||||
|
||||
### 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"}
|
||||
}
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
```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 "lua54"
|
||||
:libraries {:tic-80 false}
|
||||
:extra-globals ""
|
||||
:lints {:unused-definition true
|
||||
:unknown-module-field true
|
||||
:unnecessary-method true
|
||||
:bad-unpack true
|
||||
:var-never-set true
|
||||
:op-with-no-arguments true
|
||||
:multival-in-middle-of-call true}}
|
||||
```
|
||||
|
||||
extra-globals: Space separated list of allowed global identifiers; in addition to a set of predefined lua globals.
|
||||
|
||||
version: One of lua51, lua52, lua53, or lua54.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
## CLI Usage
|
||||
```sh
|
||||
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, without launching a server.
|
||||
|
||||
60
docs/packaging.md
Normal file
60
docs/packaging.md
Normal file
@ -0,0 +1,60 @@
|
||||
# Packaging
|
||||
Sorry packagers, I have committed two ultimate sins.
|
||||
1. I checked in some generated code into my repository.
|
||||
2. I have copied others' code into my repository, also known as "vendoring" code.
|
||||
|
||||
## Generated Code
|
||||
The files inside `src/fennel-ls/docs/generated/` are not hand-written, they are
|
||||
generated. The documentation embedded into `fennel-ls` needs to come from
|
||||
various documentation websites on the internet, such as
|
||||
[the Lua Manual](https://www.lua.org/manual/5.1/manual.html), and I use
|
||||
scripts to download and parse these sites into these generated files.
|
||||
|
||||
The content of these websites is available under the MIT license, so there isn't
|
||||
any licensing issue.
|
||||
|
||||
I understand if you want to build from source instead of relying on the output.
|
||||
You can rebuild these by running `make rm-docs` to remove the docs, and
|
||||
`make docs` to regenerate these files.
|
||||
```sh
|
||||
$ make rm-docs
|
||||
$ make docs
|
||||
```
|
||||
|
||||
## Vendored Dependencies
|
||||
The vendored dependencies are very easy to solve. You delete the dependency
|
||||
files by running `make rm-deps`.
|
||||
```sh
|
||||
$ make rm-deps
|
||||
rm -rf fennel deps/
|
||||
$
|
||||
```
|
||||
Once these files are removed, you can safely use `make` to build the program.
|
||||
```sh
|
||||
# Not shown here: install fennel and lua and make and lua-dkjson
|
||||
|
||||
# building
|
||||
make
|
||||
|
||||
# testing (only works if faith and penlight and dkjson is installed)
|
||||
make test
|
||||
```
|
||||
|
||||
# Dependencies Overview
|
||||
Things marked with (vendored) are from the `deps/` folder, or from your
|
||||
environment if you've built a clean one.
|
||||
|
||||
* Runtime Dependencies:
|
||||
* Lua
|
||||
* Fennel (vendored)
|
||||
* dkjson (vendored)
|
||||
* Build Dependencies:
|
||||
* Make
|
||||
* Lua
|
||||
* Fennel (vendored)
|
||||
* Test Dependencies:
|
||||
* Faith (vendored)
|
||||
* Penlight (vendored)
|
||||
|
||||
The specific versions of vendored packagens can be found in the
|
||||
[vendoring script](../tools/get-deps.fnl).
|
||||
Loading…
Reference in New Issue
Block a user