lux/editors/nvim/README.md

# Lux Neovim Plugin

Neovim support for the Lux programming language.

## Features

- Syntax highlighting (vim regex and tree-sitter)
- LSP integration (diagnostics, hover, completions, go-to-definition)
- Tree-sitter text objects for code navigation
- Code folding
- REPL integration with send-to-REPL
- Commands for running, formatting, and testing

## Installation

### Using lazy.nvim

```lua
{
  "your-org/lux",
  config = function()
    require("lux").setup({
      -- Optional: specify path to lux binary
      -- lux_binary = "/path/to/lux",
      lsp = {
        enabled = true,
        autostart = true,
        inlay_hints = false, -- requires neovim 0.10+
      },
      format = {
        on_save = false,
      },
      repl = {
        position = "bottom", -- "bottom", "right", or "float"
        size = 30,           -- percentage of screen
      },
      diagnostics = {
        virtual_text = true,
        update_in_insert = false,
      },
    })
  end,
  ft = "lux",
}
```

### Using packer.nvim

```lua
use {
  "your-org/lux",
  config = function()
    require("lux").setup()
  end,
  ft = "lux",
}
```

### Manual Installation

Copy the contents of this directory to your Neovim config:

```bash
# Copy to nvim config
cp -r editors/nvim/* ~/.config/nvim/

# Or symlink
ln -s /path/to/lux/editors/nvim/ftdetect ~/.config/nvim/ftdetect
ln -s /path/to/lux/editors/nvim/ftplugin ~/.config/nvim/ftplugin
ln -s /path/to/lux/editors/nvim/syntax ~/.config/nvim/syntax
ln -s /path/to/lux/editors/nvim/lua/lux ~/.config/nvim/lua/lux
ln -s /path/to/lux/editors/nvim/after ~/.config/nvim/after
```

## Tree-sitter Support

For tree-sitter based highlighting, install the grammar:

```lua
-- In your tree-sitter config
require("nvim-treesitter.configs").setup({
  ensure_installed = { "lux" },
  highlight = { enable = true },
  indent = { enable = true },
  -- Enable text objects
  textobjects = {
    select = {
      enable = true,
      keymaps = {
        ["af"] = "@function.outer",
        ["if"] = "@function.inner",
        ["ac"] = "@class.outer",
        ["ic"] = "@class.inner",
        ["ab"] = "@block.outer",
        ["ib"] = "@block.inner",
      },
    },
    move = {
      enable = true,
      goto_next_start = {
        ["]f"] = "@function.outer",
        ["]c"] = "@class.outer",
      },
      goto_previous_start = {
        ["[f"] = "@function.outer",
        ["[c"] = "@class.outer",
      },
    },
  },
})

-- Register the parser
local parser_config = require("nvim-treesitter.parsers").get_parser_configs()
parser_config.lux = {
  install_info = {
    url = "/path/to/lux/editors/tree-sitter-lux",
    files = { "src/parser.c" },
  },
  filetype = "lux",
}
```

## Commands

| Command | Description |
|---------|-------------|
| `:LuxRun` | Run the current file |
| `:LuxFormat` | Format the current file |
| `:LuxTest` | Run tests |
| `:LuxCheck` | Type check the current file |
| `:LuxRepl` | Start the REPL in a terminal |
| `:LuxReplToggle` | Toggle the REPL window |
| `:LuxSendLine` | Send current line to REPL |
| `:'<,'>LuxSend` | Send selection to REPL |

## Key Mappings

Default mappings in Lux files (using `<localleader>`):

| Mapping | Action |
|---------|--------|
| `<localleader>r` | Run current file |
| `<localleader>f` | Format current file |
| `<localleader>t` | Run tests |
| `<localleader>c` | Type check file |
| `<localleader>R` | Toggle REPL |
| `<localleader>l` | Send line to REPL |
| `<localleader>s` (visual) | Send selection to REPL |

LSP mappings (when LSP is active):

| Mapping | Action |
|---------|--------|
| `gd` | Go to definition |
| `gD` | Go to declaration |
| `K` | Hover information |
| `gr` | Find references |
| `gi` | Go to implementation |
| `<leader>rn` | Rename symbol |
| `<leader>ca` | Code actions |
| `<leader>e` | Show diagnostics float |
| `<leader>q` | Diagnostics to location list |
| `[d` / `]d` | Previous/next diagnostic |

## REPL Integration

The REPL can be positioned at the bottom, right, or as a floating window:

```lua
require("lux").setup({
  repl = {
    position = "float", -- floating window
    size = 30,
  },
})
```

Send code to the running REPL:
- `<localleader>l` - Send current line
- Select code visually, then `<localleader>s` - Send selection

## Text Objects

With `nvim-treesitter-textobjects`, you can use:

| Object | Description |
|--------|-------------|
| `af`/`if` | Function outer/inner |
| `ac`/`ic` | Type/class outer/inner |
| `ab`/`ib` | Block outer/inner |
| `aa`/`ia` | Parameter outer/inner |

Example: `dif` deletes the body of a function, `vaf` selects the entire function.

## Configuration

```lua
require("lux").setup({
  -- Path to lux binary (searches PATH if not set)
  lux_binary = nil,

  lsp = {
    -- Enable LSP support
    enabled = true,
    -- Auto-start LSP when opening .lux files
    autostart = true,
    -- Show inlay hints (requires neovim 0.10+)
    inlay_hints = false,
  },

  format = {
    -- Format on save
    on_save = false,
  },

  repl = {
    -- Position: "bottom", "right", or "float"
    position = "bottom",
    -- Size as percentage of screen
    size = 30,
  },

  diagnostics = {
    -- Show virtual text for diagnostics
    virtual_text = true,
    -- Update diagnostics in insert mode
    update_in_insert = false,
  },
})
```