docs: Add readme
This commit is contained in:
parent
6d065862b0
commit
b878a73f82
GPG key ID:
22BEAC760B3333D6
1 changed files with 298 additions and 0 deletions
298
README.md
Normal file
298
README.md
Normal file
|
|
@ -0,0 +1,298 @@
|
|||
# JQuote.nvim
|
||||
|
||||
A powerful Neovim plugin for cycling through quote characters with intelligent auto-jump functionality.
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://lua.org)
|
||||
[](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 - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## 🙏 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://github.com/your-username/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**
|
||||
Loading…
Add table
Add a link
Reference in a new issue