From e493b0e21fe872d872775a484df5319b0f3bcdfd Mon Sep 17 00:00:00 2001 From: XeroOl Date: Sun, 7 Jul 2024 23:29:46 -0500 Subject: [PATCH] Reorganize the readme files --- README.md | 116 ++-------------------- Adding-a-Lint-Rule.md => docs/linting.md | 16 +-- docs/manual.md | 118 +++++++++++++++++++++++ docs/packaging.md | 60 ++++++++++++ 4 files changed, 197 insertions(+), 113 deletions(-) rename Adding-a-Lint-Rule.md => docs/linting.md (94%) create mode 100644 docs/manual.md create mode 100644 docs/packaging.md diff --git a/README.md b/README.md index 0a5a9f5..62b1704 100644 --- a/README.md +++ b/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] diff --git a/Adding-a-Lint-Rule.md b/docs/linting.md similarity index 94% rename from Adding-a-Lint-Rule.md rename to docs/linting.md index 92138e2..470f053 100644 --- a/Adding-a-Lint-Rule.md +++ b/docs/linting.md @@ -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. :) diff --git a/docs/manual.md b/docs/manual.md new file mode 100644 index 0000000..d3afa30 --- /dev/null +++ b/docs/manual.md @@ -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. + diff --git a/docs/packaging.md b/docs/packaging.md new file mode 100644 index 0000000..b4dab70 --- /dev/null +++ b/docs/packaging.md @@ -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).