# JQuote.nvim

A powerful Neovim plugin for cycling through quote characters with intelligent auto-jump functionality.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Lua](https://img.shields.io/badge/Made%20with-Lua-blueviolet.svg)](https://lua.org)
[![Neovim](https://img.shields.io/badge/NeoVim-%2357A143.svg?&style=for-the-badge&logo=neovim&logoColor=white)](https://neovim.io)

## ✨ Features

- **🔄 Quote Cycling**: Seamlessly cycle through different quote characters (`'`, `"`, `` ` ``)
- **🎯 Auto Jump**: Automatically jump to the next quote pair when cursor is not inside quotes
- **⚙️ Configurable**: Customize quote characters, hotkeys, and jump behavior
- **🛡️ Enterprise-Grade**: Comprehensive error handling and defensive programming
- **📊 Health Monitoring**: Built-in health check and diagnostics
- **🏗️ Version Management**: Dynamic version detection from git tags
- **🧪 Thoroughly Tested**: Comprehensive unit test suite with 25+ test cases

## 📋 Requirements

- Neovim 0.5.0 or later
- Lua 5.1+

## 📦 Installation

### Using [lazy.nvim](https://github.com/folke/lazy.nvim)

```lua
{
  "your-username/jquote.nvim",
  config = function()
    require("jquote").setup({
      -- Optional configuration
      hotkey = "<leader>tq",
      quote_chars = { "'", '"', "`" },
      jump_behavior = "auto"
    })
  end,
}
```

### Using [packer.nvim](https://github.com/wbthomason/packer.nvim)

```lua
use {
  "your-username/jquote.nvim",
  config = function()
    require("jquote").setup()
  end
}
```

### Using [vim-plug](https://github.com/junegunn/vim-plug)

```vim
Plug 'your-username/jquote.nvim'

lua << EOF
require("jquote").setup()
EOF
```

### Manual Installation

```bash
# Clone the repository
git clone https://github.com/your-username/jquote.nvim.git ~/.config/nvim/lua/jquote

# Or use the Makefile
make install
```

## ⚙️ Configuration

### Default Configuration

```lua
require("jquote").setup({
  hotkey = "<leader>tq",              -- Key binding for quote toggle
  quote_chars = { "'", '"', "`" },    -- Quote characters to cycle through
  jump_behavior = "auto"              -- "auto" or "manual" jump behavior
})
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `hotkey` | `string` | `"<leader>tq"` | Key mapping for toggling quotes |
| `quote_chars` | `table` | `{ "'", '"', "`" }` | List of quote characters to cycle through |
| `jump_behavior` | `string` | `"auto"` | Jump behavior when cursor is not in quotes (`"auto"` or `"manual"`) |

### Custom Configuration Examples

```lua
-- Minimal setup with custom hotkey
require("jquote").setup({
  hotkey = "<leader>q"
})

-- Custom quote characters
require("jquote").setup({
  quote_chars = { "'", '"' }  -- Only single and double quotes
})

-- Manual jump behavior
require("jquote").setup({
  jump_behavior = "manual"  -- Don't auto-jump, only toggle quotes at cursor
})

-- Full customization
require("jquote").setup({
  hotkey = "<C-q>",
  quote_chars = { "'", '"', "`", "«", "»" },  -- Including Unicode quotes
  jump_behavior = "auto"
})
```

## 🚀 Usage

### Basic Usage

1. **Toggle Quotes**: Place your cursor inside or on a quoted string and press `<leader>tq` (or your configured hotkey)
2. **Auto Jump**: When cursor is not inside quotes, the plugin automatically jumps to the next quote pair forward

### Examples

```lua
-- Before: cursor anywhere in 'hello world'
'hello world'

-- After pressing <leader>tq
"hello world"

-- After pressing <leader>tq again
`hello world`

-- After pressing <leader>tq again (cycles back)
'hello world'
```

### Auto Jump Feature

```lua
-- Before: cursor at beginning of line
hello 'world' and "test"
^

-- After pressing <leader>tq (auto-jumps to first quote)
hello 'world' and "test"
      ^
-- And toggles the quotes
hello "world" and "test"
```

### Multiple Quote Pairs

```lua
-- Works with multiple quote pairs on the same line
print('Hello', "World", `Template`)

-- Handles nested quotes intelligently
outer "inner 'nested' text" end
```

## 🔧 Commands and Functions

### Available Functions

```lua
local jquote = require("jquote")

-- Setup the plugin
jquote.setup(options)

-- Toggle quotes at cursor position
jquote.toggle_quotes()

-- Get current plugin version
local version = jquote.get_version()

-- Get plugin health information
local health = jquote.health()
```

### Health Check

Check plugin status and configuration:

```lua
:lua print(vim.inspect(require("jquote").health()))
```

Output example:
```lua
{
  hotkey_configured = true,
  jump_behavior_valid = true,
  options = { ... },
  plugin_version = "1.2.0",
  quote_chars_count = 3
}
```

## 🧪 Development

### Running Tests

```bash
# Run all tests
make test

# Check syntax
make check

# Run development checks (syntax + tests)
make dev-check

# Quick development workflow
make quick
```

### Test Coverage

The plugin includes comprehensive unit tests covering:

- ✅ Plugin initialization and configuration
- ✅ Quote detection and cycling
- ✅ Auto jump functionality
- ✅ Error handling and edge cases
- ✅ Version management
- ✅ Health monitoring
- ✅ Boundary conditions and defensive programming

### Project Structure

```
jquote.nvim/
├── lua/
│   └── jquote/
│       └── init.lua          # Main plugin code
├── tests/
│   ├── init_spec.lua         # Comprehensive test suite
│   ├── test_runner.lua       # Custom test framework
│   └── README.md             # Testing documentation
├── Makefile                  # Development workflow
└── README.md                 # This file
```

## 🤝 Contributing

Contributions are welcome! Please ensure:

1. **Code Quality**: Follow the established corporate clean code standards
2. **Testing**: Add tests for new features and ensure all tests pass
3. **Documentation**: Update documentation for any new features or changes

### Development Workflow

```bash
# Clone the repository
git clone https://github.com/your-username/jquote.nvim.git
cd jquote.nvim

# Run tests
make test

# Check code quality
make check

# Install for local development
make install
```

## 📄 License

This project is licensed under the MIT License

## 🙏 Acknowledgments

- Inspired by the need for efficient quote management in Neovim
- Built with enterprise-grade reliability and comprehensive testing
- Designed for developer productivity and workflow optimization

## 📞 Support

If you encounter any issues or have suggestions:

1. Check the [Issues](https://git.kjan.de/jank/jquote.nvim/issues) page
2. Run the health check: `:lua print(vim.inspect(require("jquote").health()))`
3. Create a new issue with:
   - Your configuration
   - Health check output
   - Steps to reproduce the problem

---

**Made with ❤️ for the Neovim community**