Skip to content

Commit

Permalink
[optional]
Browse files Browse the repository at this point in the history
Problem:
Using _word() to define an optional arg leads to a lot of syntax errors in
real-world :help files because [brackets] are commonly used for non-args.

Solution:
Define (optional) with a regex, like (keycode) instead of using the more
"formal" mechanism. Regex has "best-effort" behavior, while seq() behaves more
strictly.

Don't treat `[{arg}]` as (optional), else it clobbers the nested `{arg}`.

fix #1
  • Loading branch information
justinmk committed Jun 19, 2024
1 parent d76e6b7 commit 2a569e7
Show file tree
Hide file tree
Showing 7 changed files with 23 additions and 28 deletions.
10 changes: 6 additions & 4 deletions grammar.js
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ module.exports = grammar({
$.taglink,
$.codespan,
$.argument,
$.optional_arg,
$.optional,
$.keycode,
$.note,
),
Expand Down Expand Up @@ -107,6 +107,10 @@ module.exports = grammar({
/ALT-./,
),

// Optional argument: [arg] (no whitespace allowed).
// This is the vimdoc style optional arg, as opposed to {arg}? (LuaLS style).
optional: () => /\[[^\]{\n\t ]+\]/,

// First part (minus tags) of h3 or column_heading.
uppercase_name: () => seq(
token.immediate(_uppercase_word), // No whitespace before heading.
Expand Down Expand Up @@ -223,10 +227,8 @@ module.exports = grammar({
taglink: ($) => _word($, prec(1, /[^|\n\t ]+/), '|', '|'),
// Inline code (may contain whitespace!): `foo bar`
codespan: ($) => _word($, /[^``\n]+/, '`', '`'),
// Argument: {arg} (no whitespace allowed), also {arg}? for LuaLS-style optional args.
// Argument: {arg} (no whitespace allowed), also {arg}? (LuaLS style "optional arg").
argument: ($) => seq(_word($, /[^}\n\t ]+/, '{', '}'), optional(token.immediate('?'))),
// Optional argument: [arg] (no whitespace allowed)
optional_arg: ($) => _word($, /[^\]\n\t ]+/, '[', ']'),
},
});

Expand Down
2 changes: 2 additions & 0 deletions queries/vimdoc/highlights.scm
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@

(argument) @variable.parameter

(optional) @variable.parameter

(keycode) @string.special

(url) @string.special.url
Expand Down
6 changes: 4 additions & 2 deletions test/corpus/argument.txt
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,10 @@ nvim_buf_detach_event[{buf}]
(word))
(line
(word)
(optional_arg
(word)))))
(word)
(argument
(word))
(word))))

================================================================================
NOT an argument
Expand Down
24 changes: 8 additions & 16 deletions test/corpus/argument_optional.txt
Original file line number Diff line number Diff line change
Expand Up @@ -11,30 +11,22 @@ optional [argument]
(block
(line
(word)
(optional_arg
(word))
(optional)
(word)
(optional_arg
(word))
(optional_arg
(word))
(optional)
(optional)
(argument
(word))
(tag
(word)))
(line
(word)
(optional_arg
(word))
(optional)
(word)
(optional_arg
(word))
(optional_arg
(word))
(optional_arg
(word))
(optional_arg
(word))
(optional)
(optional)
(optional)
(optional)
(argument
(word))
(word))))
3 changes: 1 addition & 2 deletions test/corpus/codeblock.txt
Original file line number Diff line number Diff line change
Expand Up @@ -398,8 +398,7 @@ codeblock stop and start on same line
(line
(word)
(word)
(optional_arg
(word)))
(optional))
(line
(argument
(word))))
Expand Down
3 changes: 1 addition & 2 deletions test/corpus/taglink.txt
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,7 @@ Hello |world| hello
(taglink
(word))
(word)
(optional_arg
(word))
(optional)
(word))
(line
(taglink
Expand Down
3 changes: 1 addition & 2 deletions test/corpus/url.txt
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,7 @@ markdown: [https://neovim.io/doc/user/#yay](https://neovim.io/doc/user/#yay).
(word))
(line
(word)
(optional_arg
(word))
(optional)
(word)
(url
(word))
Expand Down

0 comments on commit 2a569e7

Please sign in to comment.