Skip to content

Commit

Permalink
docs: lint
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrisgrieser
chrisgrieser committed Nov 2, 2023
1 parent 20340d1 commit b49bf00
Showing 1 changed file with 56 additions and 22 deletions.
78 changes: 56 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
<!-- LTeX: enabled=false -->
# nvim-spider 🕷️🕸️
<!-- LTeX: enabled=true -->
<a href="https://dotfyle.com/plugins/chrisgrieser/nvim-spider"><img src="https://dotfyle.com/plugins/chrisgrieser/nvim-spider/shield" /></a>
<a href="https://dotfyle.com/plugins/chrisgrieser/nvim-spider">
<img src="https://dotfyle.com/plugins/chrisgrieser/nvim-spider/shield" /></a>

Use the `w`, `e`, `b` motions like a spider. Move by subwords and skip insignificant punctuation.
Use the `w`, `e`, `b` motions like a spider. Move by subwords and skip
insignificant punctuation.

A lua implementation of [CamelCaseMotion](https://github.com/bkad/CamelCaseMotion), with extra consideration of punctuation. Works in normal, visual, and operator-pending mode. Supports counts and dot-repeat.
A lua implementation of
[CamelCaseMotion](https://github.com/bkad/CamelCaseMotion), with extra
consideration of punctuation. Works in normal, visual, and operator-pending
mode. Supports counts and dot-repeat.

<!-- toc -->

Expand All @@ -21,10 +26,12 @@ A lua implementation of [CamelCaseMotion](https://github.com/bkad/CamelCaseMotio
<!-- tocstop -->

## Features
The `w`, `e`, `b` (and `ge`) motions work the same as the default ones by vim, except for two differences:
The `w`, `e`, `b` (and `ge`) motions work the same as the default ones by vim,
except for two differences:

### Subword Motion
The movements happen by subwords, meaning it stops at the sub-parts of a camelCase, SCREAMING_SNAKE_CASE, or kebab-case variable.
The movements happen by subwords, meaning it stops at the sub-parts of a
camelCase, SCREAMING_SNAKE_CASE, or kebab-case variable.

```lua
-- positions vim's `w` will move to
Expand All @@ -37,7 +44,8 @@ local myVariableName = FOO_BAR_BAZ
```

### Skipping Insignificant Punctuation
A sequence of one or more punctuation characters is considered significant if it is surrounded by whitespace and does not include any non-punctuation characters.
A sequence of one or more punctuation characters is considered significant if it
is surrounded by whitespace and does not include any non-punctuation characters.

```lua
foo == bar .. "baz"
Expand All @@ -47,7 +55,8 @@ foo:find("a")
-- ^ ^ ^ insignificant punctuation
```

This speeds up the movement across the line by reducing the number of mostly unnecessary stops.
This speeds up the movement across the line by reducing the number of mostly
unnecessary stops.

```lua
-- positions vim's `w` will move to
Expand All @@ -59,7 +68,9 @@ if foo:find("%d") and foo == bar then print("[foo] has" .. bar) end
-- ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ -> 14
```

If you prefer to use this plugin only for subword motion, you can disable this feature by setting `skipInsignificantPunctuation = false` in the `.setup()` call.
If you prefer to use this plugin only for subword motion, you can disable this
feature by setting `skipInsignificantPunctuation = false` in the `.setup()`
call.

> __Note__
> This plugin ignores vim's `iskeyword` option.
Expand All @@ -73,9 +84,8 @@ use { "chrisgrieser/nvim-spider" }
-- lazy.nvim
{
"chrisgrieser/nvim-spider",
-- example for lazy-loading and keymap
keys = {
{
{ -- example for lazy-loading and keymap
"e",
"<cmd>lua require('spider').motion('e')<CR>",
mode = { "n", "o", "x" },
Expand All @@ -84,7 +94,8 @@ use { "chrisgrieser/nvim-spider" }
},
```

No keybindings are created by default. Below are the mappings to replace the default `w`, `e`, and `b` motions with this plugin's version of them.
No keybindings are created by default. Below are the mappings to replace the
default `w`, `e`, and `b` motions with this plugin's version of them.

```lua
vim.keymap.set(
Expand Down Expand Up @@ -114,10 +125,13 @@ vim.keymap.set(
```

> __Note__
> For dot-repeat to work, you have to call the motions as Ex-commands. When calling `function() require("spider").motion("w") end` as third argument of the keymap, dot-repeatability <!-- vale Google.Will = NO -->will *not* work.
> For dot-repeat to work, you have to call the motions as Ex-commands. When
> calling `function() require("spider").motion("w") end` as third argument of
> the keymap, dot-repeatability <!-- vale Google.Will = NO -->will *not* work.
## Configuration
The `.setup()` call is optional. Currently, its only option is to disable the skipping of insignificant punctuation:
The `.setup()` call is optional. Currently, its only option is to disable the
skipping of insignificant punctuation:

```lua
-- default value
Expand All @@ -132,25 +146,40 @@ You can also pass this configuration table to the `motion` function:
require("spider").motion("w", { skipInsignificantPunctuation = false })
```

Any options passed here will be used, and any options not passed will use the default configuration (from `setup()` or the default configuration)
Any options passed here will be used, and any options not passed will use the
default configuration (from `setup()` or the default configuration)

## Notes on Operator-pending Mode
<!-- vale Google.FirstPerson = NO -->
In operator pending mode, vim's `web` motions are actually a bit inconsistent. For instance, `cw` will change to the *end* of a word instead of the start of the next word, like `dw` does. This is probably done for convenience in vi's early days before there were text objects. In my view, this is quite problematic since it makes people habitualize inconsistent motion behavior.

In this plugin, such small inconsistencies are therefore deliberately not implemented. Apart from the inconsistency, such a behavior can create unexpected results when used in subwords or near punctuation. If you absolutely want to, you can map `cw` to `ce` though. (Remember to add `remap = true` as option for the keymap.)
In operator pending mode, vim's `web` motions are actually a bit inconsistent.
For instance, `cw` will change to the *end* of a word instead of the start of
the next word, like `dw` does. This is probably done for convenience in vi's
early days before there were text objects. In my view, this is quite problematic
since it makes people habitualize inconsistent motion behavior.

In this plugin, such small inconsistencies are therefore deliberately not
implemented. Apart from the inconsistency, such a behavior can create unexpected
results when used in subwords or near punctuation. If you absolutely want to,
you can map `cw` to `ce` though. (Remember to add `remap = true` as option for
the keymap.)
<!-- vale Google.FirstPerson = YES -->

## Subword Text Object
This plugin supports `w`, `e`, and `b` in operater-pending mode, but does not include a subword-variant of `iw`. For a version of `iw` that considers camelCase, check out the `subword` text object of [nvim-various-textobjs](https://github.com/chrisgrieser/nvim-various-textobjs).
This plugin supports `w`, `e`, and `b` in operater-pending mode, but does not
include a subword variant of `iw`. For a version of `iw` that considers
camelCase, check out the `subword` text object of
[nvim-various-textobjs](https://github.com/chrisgrieser/nvim-various-textobjs).

## Credits
__Thanks__
To `@vypxl` and `@ii14` [for figuring out dot-repeatability](https://github.com/chrisgrieser/nvim-spider/pull/4).

<!-- vale Google.FirstPerson = NO -->
__About Me__
In my day job, I am a sociologist studying the social mechanisms underlying the digital economy. For my PhD project, I investigate the governance of the app economy and how software ecosystems manage the tension between innovation and compatibility. If you are interested in this subject, feel free to get in touch.
In my day job, I am a sociologist studying the social mechanisms underlying the
digital economy. For my PhD project, I investigate the governance of the app
economy and how software ecosystems manage the tension between innovation and
compatibility. If you are interested in this subject, feel free to get in touch.

__Blog__
I also occasionally blog about vim: [Nano Tips for Vim](https://nanotipsforvim.prose.sh)
Expand All @@ -160,9 +189,14 @@ __Profiles__
- [Discord](https://discordapp.com/users/462774483044794368/)
- [Academic Website](https://chris-grieser.de/)
- [Twitter](https://twitter.com/pseudo_meta)
- [Mastodon](https://pkm.social/@pseudometa)
- [ResearchGate](https://www.researchgate.net/profile/Christopher-Grieser)
- [LinkedIn](https://www.linkedin.com/in/christopher-grieser-ba693b17a/)

__Buy Me a Coffee__
<br>
<a href='https://ko-fi.com/Y8Y86SQ91' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
<a href='https://ko-fi.com/Y8Y86SQ91' target='_blank'><img
height='36'
style='border:0px;height:36px;'
src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3'
border='0'
alt='Buy Me a Coffee at ko-fi.com'
/></a>

0 comments on commit b49bf00

Please sign in to comment.