Skip to content

Commit

Permalink
feat!: replace config-file with config name
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: The `--config-file` option has been removed.
Custom configurations are now supplied in the setup() function instead
of separate config file. The config name correspondes to the key of
the table provided to `setup()`.

closes #16
closes #12
closes #2
  • Loading branch information
@mikesmithgh
mikesmithgh committed Nov 1, 2023
1 parent 99c7854 commit e16e96a
Show file tree
Hide file tree
Showing 48 changed files with 1,002 additions and 653 deletions.
13 changes: 13 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# kitty-scrollback.nvim

## Generating demos and wiki content (requires MacOS)

- `git clone [email protected]/mikesmithgh/kitty-scrollback.nvim.wiki.git`
- `cd kitty-scrollback.nvim.wiki`
- `./scripts/record_demo_videos.lua`
- `ls -1 assets/*.mov | xargs -I {} scripts/mov_to_gif.sh {}`
- Upload all `mov` files in the `assets` directory to Github by dragging them to a markdown file in the browser
- Copy all the generated embeded video urls and paste in `uploaded_movs` array in the `make_video_markdown_files.sh` script
- `./scripts/make_video_markdown_files.sh`
- `./scripts/make_adv_config_markdown_file.lua &> Advanced-Configuration.md`

139 changes: 117 additions & 22 deletions README.md
View file

Large diffs are not rendered by default.

135 changes: 114 additions & 21 deletions doc/kitty-scrollback.nvim.txt
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
*kitty-scrollback.nvim.txt* For NVIM v0.10+ Last change: 2023 October 31
*kitty-scrollback.nvim.txt* For NVIM v0.10+ Last change: 2023 November 01

==============================================================================
Table of Contents *kitty-scrollback.nvim-table-of-contents*

1. kitty-scrollback.nvim |kitty-scrollback.nvim-kitty-scrollback.nvim|
- Migrating to v2.0.0 |kitty-scrollback.nvim-migrating-to-v2.0.0|
- Features |kitty-scrollback.nvim-features|
- Example use cases |kitty-scrollback.nvim-example-use-cases|
- Prerequisites |kitty-scrollback.nvim-prerequisites|
Expand All @@ -25,6 +26,88 @@ Navigate your Kitty scrollback buffer to quickly search, copy, and execute
commands in Neovim.


MIGRATING TO V2.0.0 *kitty-scrollback.nvim-migrating-to-v2.0.0*


`IMPORTANT` v2.0.0 has breaking changes and requires steps to properly migrate
from v1.X.X.
You can ignore this section if you have not previously installed any verions of
kitty-scrollback.nvim
- Migration Steps



- If you are using the packer.nvim <https://github.com/wbthomason/packer.nvim>
package manager, then add the custom `User` event `KittyScrollbackLaunch` as a
trigger for lazy loading. See |kitty-scrollback.nvim-installation| for
additional details.
>lua
event = { 'User KittyScrollbackLaunch' }
<
- Regenerate default Kitten mappings and add to `kitty.conf`
>sh
nvim --headless +'KittyScrollbackGenerateKittens' +'set nonumber' +'set norelativenumber' +'%print' +'quit!' 2>&1
<
- Remove previous kitty-scrollback.nvim Kitten mappings in `kitty.conf`
- Migrate any customized configurations to the new format
- When you define your kitty-scrollback.nvim Kitten configuration, do not use
`--config-file` `yourconfigfile.lua`. Instead, move the contents of
`yourconfigfile.lua` to an entry in the configuration passed to the
kitty-scrollback.nvim setup function.
>lua
require('kitty-scrollback').setup({
yourconfig = function()
...
end,
})
<
Update your Kitten to use the name of the configuration defined in the setup
function. In this example, `--config-file yourconfigfile.lua` changes to
`--config yourconfig`
- Real example
The configuration to view the last command output now references a builtin
configuration instead of a file. The new configuation can be viewed by running
`:KittyScrollbackGenerateKittens`.
- Old configuration
The Kitten defined in `kitty.conf` references the configuration file `get_text_last_cmd_output.lua`
>kitty
# Browse output of the last shell command in nvim
map ctrl+shift+g kitty_scrollback_nvim --config-file get_text_last_cmd_output.lua
<
>lua
-- get_text_last_cmd_output.lua
local M = {}
M.config = function()
return {
kitty_get_text = {
extent = 'last_visited_cmd_output',
ansi = true,
},
}
end

return M
<
- New configuration
The Kitten defined in `kitty.conf` references the builtin configuration name `ksb_builtin_last_cmd_output`
>kitty
# Browse output of the last shell command in nvim
map ctrl+shift+g kitty_scrollback_nvim --config ksb_builtin_last_cmd_output
<
>lua
require('kitty-scrollback').setup({
ksb_builtin_last_cmd_output = function()
return {
kitty_get_text = {
extent = 'last_visited_cmd_output',
ansi = true,
},
}
end
})
<


FEATURES *kitty-scrollback.nvim-features*

- Navigate Kitty’s scrollback buffer with Neovim
Expand Down Expand Up @@ -91,6 +174,7 @@ INSTALLATION *kitty-scrollback.nvim-installation*
enabled = true,
lazy = true,
cmd = { 'KittyScrollbackGenerateKittens', 'KittyScrollbackCheckHealth' },
event = { 'User KittyScrollbackLaunch' },
-- version = '*', -- latest stable version, may have breaking changes if major version changed
-- version = '^1.0.0', -- pin major version, include fixes and features that do not have breaking changes
config = function()
Expand All @@ -107,6 +191,7 @@ INSTALLATION *kitty-scrollback.nvim-installation*
disable = false,
opt = true,
cmd = { 'KittyScrollbackGenerateKittens', 'KittyScrollbackCheckHealth' },
event = { 'User KittyScrollbackLaunch' },
-- tag = '*', -- latest stable version, may have breaking changes if major version changed
-- tag = 'v1.0.0', -- pin specific tag
config = function()
Expand All @@ -130,6 +215,10 @@ INSTALLATION *kitty-scrollback.nvim-installation*
CONFIGURATION *kitty-scrollback.nvim-configuration*


`NOTE` The Advanced Configuration
<https://github.com/mikesmithgh/kitty-scrollback.nvim/wiki/Advanced-Configuration>
section of the Wiki provides detailed demos of each configuration option.

KITTY ~

The following steps outline how to properly configure kitty.conf
Expand Down Expand Up @@ -176,14 +265,14 @@ The following steps outline how to properly configure kitty.conf
shell_integration enabled

# kitty-scrollback.nvim Kitten alias
action_alias kitty_scrollback_nvim kitten /Users/mike/gitrepos/kitty-scrollback.nvim/python/kitty_scrollback_nvim.py --cwd /Users/mike/gitrepos/kitty-scrollback.nvim/lua/kitty-scrollback/configs
action_alias kitty_scrollback_nvim kitten /Users/mike/gitrepos/kitty-scrollback.nvim/python/kitty_scrollback_nvim.py

# Browse scrollback buffer in nvim
map ctrl+shift+h kitty_scrollback_nvim
# Browse output of the last shell command in nvim
map ctrl+shift+g kitty_scrollback_nvim --config-file get_text_last_cmd_output.lua
map ctrl+shift+g kitty_scrollback_nvim --config ksb_builtin_last_cmd_output
# Show clicked command output in nvim
mouse_map ctrl+shift+right press ungrabbed combine : mouse_select_command_output : kitty_scrollback_nvim --config-file get_text_last_visited_cmd_output.lua
mouse_map ctrl+shift+right press ungrabbed combine : mouse_select_command_output : kitty_scrollback_nvim --config ksb_builtin_last_visited_cmd_output
<


Expand All @@ -195,10 +284,9 @@ kitty.conf <https://sw.kovidgoyal.net/kitty/conf/>.
-------------------------------------------------------------------------------------
Argument Description
---------------- --------------------------------------------------------------------
--config-file kitty-scrollback.nvim plugin configuration file. The configuration
file must return a Lua table with the function
config(kitty_data): table. You may specify multiple config files
that will merge all configuration options.
--config The name of the kitty-scrollback.nvim plugin configuration. The
configuration can be defined during plugin setup (i.e.,
require('kitty-scrollback').setup({ ... })).

--no-nvim-args Do not provide any arguments to the Neovim instance that displays
the scrollback buffer. The default arguments passed to Neovim are
Expand Down Expand Up @@ -281,8 +369,8 @@ KITTY-SCROLLBACK.NVIM CONFIGURATION FILE ~

paste_window.filetype string? The filetype of the paste window

paste_window.hide_footer boolean? If true, hide the footer when the paste window is initially
opened
paste_window.hide_footer boolean? If true, hide mappings in the footer when the paste window
is initially opened

paste_window.winblend integer? The winblend setting of the window, see :help winblend

Expand Down Expand Up @@ -332,26 +420,25 @@ in the status window. If you would like to use ASCII instead, set the option
`status_window.style_simple` to `true`.

- Status window with Nerd Fonts opts.status_window.style_simple = false
https://github.com/mikesmithgh/kitty-scrollback.nvim/assets/10135646/4cf5b303-5061-43da-a857-c99daea82332

- Status window with ASCII text opts.status_window.style_simple = true
https://github.com/mikesmithgh/kitty-scrollback.nvim/assets/10135646/a0e1b574-59ab-4abf-93a1-f314c7cd47b3


COMMANDS AND LUA API *kitty-scrollback.nvim-commands-and-lua-api*

The API is available via the `kitty-scrollback.api` module. e.g.,
`require('kitty-scrollback.api')`

------------------------------------------------------------------------------------------------------
Command API Description
------------------------------------ ---------------------------- ------------------------------------
:KittyScrollbackGenerateKittens[!] generate_kittens(boolean?) Generate Kitten commands used as
reference for configuring kitty.conf
------------------------------------------------------------------------------------------------------------------------------------------------------
Command API Description
----------------------------------------------------- ---------------------------------------------------------------- -------------------------------
:KittyScrollbackGenerateKittens[!] [generate_modes] generate_kittens(boolean?, table<string\|'commands'\|'maps'>)? Generate Kitten commands used
as reference for configuring
kitty.conf

:KittyScrollbackCheckHealth checkhealth() Run :checkhealth kitty-scrollback in
the context of Kitty
------------------------------------------------------------------------------------------------------
:KittyScrollbackCheckHealth checkhealth() Run
:checkhealth kitty-scrollback
in the context of Kitty
------------------------------------------------------------------------------------------------------------------------------------------------------

KEYMAPS AND LUA API *kitty-scrollback.nvim-keymaps-and-lua-api*

Expand Down Expand Up @@ -421,6 +508,12 @@ ALTERNATIVES *kitty-scrollback.nvim-alternatives*
- kitty_grab <https://github.com/yurikhan/kitty_grab> - Keyboard-driven screen grabber for Kitty
- kitty-kitten-search <https://github.com/trygveaa/kitty-kitten-search> - Kitten for the kitty terminal emulator providing live incremental search in the terminal history.

==============================================================================
2. Links *kitty-scrollback.nvim-links*

1. *style_simple_false*: https://github.com/mikesmithgh/kitty-scrollback.nvim/assets/10135646/662bf132-0b39-4028-b69f-eb85fbb69b60
2. *style_simple_true*: https://github.com/mikesmithgh/kitty-scrollback.nvim/assets/10135646/c19a1869-e4e4-40fd-b619-fed771d0153f

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl:
29 changes: 19 additions & 10 deletions doc/kitty-scrollback.nvim_spec.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,18 @@ KsbKittyOpts *kitty-scrollback.launch.KsbKittyOpts*
KsbKittyData *kitty-scrollback.launch.KsbKittyData*

Fields: ~
{scrolled_by} (integer) the number of lines currently scrolled in kitty
{cursor_x} (integer) position of the cusor in the column in kitty
{cursor_y} (integer) position of the cursor in the row in kitty
{lines} (integer) the number of rows of the screen in kitty
{columns} (integer) the number of columns of the screen in kitty
{window_id} (integer) the id of the window to get scrollback text
{window_title} (string) the title of the window to get scrollback text
{ksb_dir} (string) the base runtime path of kitty-scrollback.nvim
{config_files} (table)
{scrolled_by} (integer) the number of lines currently scrolled in kitty
{cursor_x} (integer) position of the cusor in the column in kitty
{cursor_y} (integer) position of the cursor in the row in kitty
{lines} (integer) the number of rows of the screen in kitty
{columns} (integer) the number of columns of the screen in kitty
{window_id} (integer) the id of the window to get scrollback text
{window_title} (string) the title of the window to get scrollback text
{ksb_dir} (string) the base runtime path of kitty-scrollback.nvim
{kitty_scrollback_config} (string) the config name of user config options
{kitty_opts} (KsbKittyOpts) relevent kitty configuration values
{kitty_config_dir} (string) kitty configuration directory path
{kitty_version} (table) kitty version


KsbPrivate *kitty-scrollback.launch.KsbPrivate*
Expand Down Expand Up @@ -94,7 +97,7 @@ KsbPasteWindowOpts
Fields: ~
{highlight_as_normal_win} (nil|fun():boolean) If function returns true, use Normal highlight group. If false, use NormalFloat
{filetype} (string|nil) The filetype of the paste window
{hide_footer} (boolean|nil) If true, hide the footer when the paste window is initially opened
{hide_footer} (boolean|nil) If true, hide mappings in the footer when the paste window is initially opened
{winblend} (integer|nil) The winblend setting of the window, see :help winblend
{winopts_overrides} (KsbWinOptsOverrideFunction|nil) Paste float window overrides, see nvim_open_win() for configuration
{footer_winopts_overrides} (KsbFooterWinOptsOverrideFunction|nil) Paste footer window overrides, see nvim_open_win() for configuration
Expand Down Expand Up @@ -164,6 +167,12 @@ M.toggle_footer() *kitty-scrollback.api.toggle_footer*
open or closed. Otherwise, no operation


KsbGenKittenModes *kitty-scrollback.api.KsbGenKittenModes*

Type: ~
string|"maps"|"commands"


M.generate_kittens() *kitty-scrollback.api.generate_kittens*


Expand Down
Loading

0 comments on commit e16e96a

Please sign in to comment.