Metadata-Version: 2.5
Name: ymmsl-lsp
Version: 0.0.5
Summary: YMMSL linter and LSP server
License-Expression: EUPL-1.2
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pygls
Requires-Dist: pyyaml
Requires-Dist: yatiml
Requires-Dist: ymmsl>=0.17.0
Description-Content-Type: text/markdown

# YMMSL Language Support

[Download the latest VS Code extension (.vsix)](https://github.com/multiscale/ymmsl-lsp/releases/latest)

[VS Code installation tutorial](https://www.youtube.com/watch?v=nlHnlmtvjF4)

YMMSL Language Support provides a Language Server Protocol (LSP) server built on top of the validation and consistency checks provided by [ymmsl-python](https://github.com/multiscale/ymmsl-python).

The server enables IDEs and editors such as VS Code, Emacs, and Neovim to provide inline diagnostics and highlight validation errors directly in YMMSL files.

# Installation

## Linux executable

On Linux, you can download the latest prebuilt executable:

https://github.com/multiscale/ymmsl-lsp/releases?q=server-

Place the executable under `bin/` in the repository root.

### Requirements

- glibc >= 2.34

If you use the VS Code extension, the executable is already bundled and ready to use.

## Installing with pip, pipx, or uv

You can directly install from this repository, or from [PyPi](https://pypi.org/project/ymmsl-lsp/).

As this is a tool it is recommended to use either ´uv tool´ or ´pipx´, after which you will find the executable ymmsl-language-server in /path/to/venv/bin and or have it exposed in your shell. 

For example, you could use
´´´
uv tool install ymmsl-lsp
´´´

# Usage

The LSP server must be connected to an editor or IDE to be useful.

You can either:

- Install the VS Code extension, or
- Generate configuration files for Emacs and Neovim

Generate editor configurations with:

```bash
python scripts/generate_editor_configs.py
```

Generated files are written to:

```text
editors/generated/
```

## Visual Studio Code

Download the extension from the [latest GitHub release](https://github.com/multiscale/ymmsl-lsp/releases/latest).

The VS Code extension and the Python language server are released separately. Extension releases are tagged `extension-vX.Y.Z`; server releases are tagged `server-vX.Y.Z`. Every server release also publishes a new extension release containing that server version.

Installation tutorial:

https://www.youtube.com/watch?v=nlHnlmtvjF4

The extension bundles the LSP server and should work out of the box.

If not, you need to install it yourself and set the environment variable ´YMMSL_LSP_PATH´
```bash
export YMMSL_LSP_PATH=/path/to/venv/bin/ymmsl-language-server
```

## Emacs

The generated file `ymmsl-mode_emacs.el` provides YMMSL language support for Emacs.

### Quick test

Load the generated mode directly:

```bash
emacs -l editors/generated/ymmsl-mode_emacs.el
```

Alternatively, start Emacs and load the file manually:

```text
M-x load-file
```

Select:

```text
editors/generated/ymmsl-mode_emacs.el
```

### Permanent installation

Copy or symlink the file into your Emacs configuration and load it from `init.el`:

```elisp
(add-to-list 'load-path "/path/to/editors/generated")
(load "ymmsl-mode_emacs")
```

Emacs package installation tutorial:

https://www.youtube.com/watch?v=at_fACZ_o9Q

## Neovim

The generated file `ymmsl-nvim.lua` provides YMMSL language support for Neovim.

### Quick test

```bash
nvim -c "source editors/generated/ymmsl-nvim.lua"
```

### Permanent installation

Copy the plugin into Neovim's plugin directory:

```bash
mkdir -p ~/.config/nvim/plugin
cp editors/generated/ymmsl-nvim.lua ~/.config/nvim/plugin/
```

Or create a symbolic link:

```bash
mkdir -p ~/.config/nvim/plugin
ln -s $(pwd)/editors/generated/ymmsl-nvim.lua \
      ~/.config/nvim/plugin/ymmsl-nvim.lua
```

Neovim will automatically load the plugin on startup.

# What is `YMMSL_PATH`?

The Python validator resolves imported YMMSL modules using the `YMMSL_PATH` environment variable.

When a YMMSL file imports another module, the validator searches the directories listed in `YMMSL_PATH`. If an import cannot be resolved, ensure that `YMMSL_PATH` points to the directory or directories containing the required YMMSL modules.

Example:

```bash
export YMMSL_PATH=/path/to/ymmsl/modules
```

Multiple directories can be specified using a colon-separated list:

```bash
export YMMSL_PATH=/path/one:/path/two:/path/three
```

This works similarly to `PATH` and `PYTHONPATH`.

## License

Copyright © 2026 Kristoffer Gustafsson

This repository, including its complete commit history, is licensed under
the European Union Public Licence (EUPL) v1.2.

See the LICENSE file for the full license text.