l-zeuch / yagpdb.vim

(N)Vim plugin for YAGPDB Custom Commands.

👋 Welcome

The "m" in "code" stands for magic.

Hey there! My name is Luca Zeuch, a programming enthusiast and spare time tutor from Germany.

Currently I study chemistry at the University of Bremen.

Outside of code, I enjoy cooking, swimming, reading, and playing Badminton. I like learning new stuff and forgetting them almost immediately.

Current Projects

(In no particular order)

• studip-nord - A Nord theme for StudIP
• lzeuch.de - My own website and blog
• yagpdb.vim - An (N)Vim plugin to support syntax highlighting of YAGPDB Custom Commands.

Maybe the one or other side project here and there, but overall I try to focus on the above ones.

Statistics

Just a few numbers some people would want to see:

Provided by GitHub Readme Stats

Programs / Platforms I Use

If you want to chat, feel free to ping lzodd via the Discord server linked below. Please say you're coming from GitHub so I know you're not spam. I do not accept friend requests.

---

GPG Key | Website | Discord

yagpdb.vim's Issues

[Tracking] Regenerating completions for PRs/merges

#24 introduced nvim-cmp-compatible, Lua-based completion support. This is a great feature, though it comes with a few catches for our workflow.

We've opted to commit the generated completions as we go (though end users, and developers, can always regenerate them with make generate). However, this means we need to ensure they're up to date, especially when PRs are merged or direct commits to master are made. This sounds like an ideal use case for GitHub Actions, and it nearly is. However, things get messy when our Generate workflow makes updates and pushes a new commit to the relevant PR branch.

We run tests and linter checks on PRs and pushes to master, so these checks should also be run on any new commits that the Generate workflow adds. In fact, in order for auto-merging to work in the GitHub UI, a PR's most recent commit must pass these checks. However, to prevent recursive loops, GitHub does not trigger Actions workflows on commits that are pushed by other workflows. This means that, if the most recent commit on a PR is one that causes completions to be rengenerated, the workflow will push a new commit to include those new completions. This new most recent commit will then be one on which our checks do not run, and auto-merging will not be available.

Ideally, there would be some way to tell GitHub, "hey, run this workflow first, and if it creates a new commit, run our other checks on that, since it's newer." This doesn't appear to be an option at the moment, so we'll have to find a workaround. The simplest is to have us, the developers, ensure that we've regenerated sources before merging anything, but as a manual task, this is inconvenient and prone to being missed during the flurry of finalizing a PR.

Please feel free to add comments below regarding this issue and any potential solutions you might have.
This issue exists primarily for documentation purposes, and will be closed with a PR that resolves this issue, one way or another.

[Feature] Yank to System Clipboard

This issue serves as a record of a proposed feature for this extension. I'll be implementing it myself soon (probably tonight, if I have nothing better to do), but having a place for discussion might be helpful.

Rationale

Since YAGPDB CCs are managed though the online dashboard, they must be copy/pasted when edits are made in another platform. With a standard GUI editor like VSCode, this isn't too painful, especially with the Ctrl + A shortcut, but when using a terminal editor like Vim, it can be painful (especially if you have line numbers enabled, or another pane on the side). As such, a function (which can be bound to a shortcut by the user) would be quite useful.

Notes

(N)Vim can access the system clipboard using the "* and "+ registers. "+ seems to be the preferred one, though I'm not certain about that. On Windows, both appear to work equivalently, and do in fact add to the Clipboard History feature.

Syntax here is just like with any other register - yank to it using "+y{motion} or {Visual}"+y, and paste with "+p.

Clipboard Register Broken

Expected Behaviour

The buffer's content is properly written to the system clipboard with the :YagCopy command.

Actual Behaviour

Instead, nothing is written to the system clipboard.

Steps to Reproduce

• Write something
• run :YagCopy
• Paste whatever content is in your clipboard (ctrl + V)
• See error

Additional Context

$ nvim --version
NVIM v0.6.1
Build type: Release
LuaJIT 2.1.0-beta3
Compiled by builduser

Features: +acl +iconv +tui
See ":help feature-compile"

   system vimrc file: "$VIM/sysinit.vim"
  fall-back for $VIM: "/usr/share/nvim"

Run :checkhealth for more info

$ Xorg -version
X.Org X Server 1.21.1.3
X Protocol Version 11, Revision 0
Current Operating System: Linux 5.16.7-arch1-1 #1 SMP PREEMPT Tue, 01 Feb 2022 21:42:50 +0000 x86_64
Kernel command line: BOOT_IMAGE=/vmlinuz-linux root=UUID=659b7f90-bb02-4c6e-b3a4-af7daf2b11d3 rw rootflags=subvol=root quiet loglevel=3 udev.log-priority=3 splash vt.global_cursor_default=0
 
Current version of pixman: 0.40.0
	Before reporting problems, check http://wiki.x.org
	to make sure that you have the latest version.

Presumably something might be not quite right with my Neovim installation, however I noticed that the "* register is labelled as X11 primary, whereas "+ is labelled as X11 clipboard -- both however have the description "clipboard"; see also this handy cheatsheet.

Thus, I am not quite sure how to write a patch for this, let me know your thoughts -- perhaps attempting to write to both registers, or finding out which one actually works consistently, and going with that instead?. I doubt it is an issue with upstream Neovim and Xorg, though.

Additionally, I noticed that "+ works as expected.

Code of Conduct

• I agree to follow this project's Code of Conduct.

[Issue]: `yagChar` is Not up to Spec

Expected Behaviour

According to the Go specification on Rune literals¹, following sequences are allowed:

'a'
'ä'
'本'
'\t'
'\000'
'\007'
'\377'
'\x07'
'\xff'
'\u12e4'
'\U00101234'
'\''         // rune literal containing single quote character

Thus, it is expected that the yagChar syntax group also recognises those.

Actual Behaviour

Instead, we see the following behaviour:

Here, through some tricky code, we try to let the user know when they are creating/using an illegal rune literal. However, according to the Go specification¹ the sequences in the above screenshot are actually valid, as I copied them directly from there.

Steps to Reproduce

1. Go to the Go spec (https://go.dev/ref/spec#Rune_literals)
2. copy any valid rune literal longer than two characters
3. Insert to a *.yag file (or any accepted file extension)
4. See screenshot

Additional Context

I understand that validating Unicode may be a hard task to do; if this seems unfeasible, we could just resort to finding the longest Unicode sequence available and use that as the maximum allowed.

If memory serves me right, Unicode ranges from 0 to 0x10FFFF, though not all are assigned. Perhaps we could call out to Python if we really want to validate any given Unicode sequence², and maybe even display it as virtual text of sorts.³⁴⁵
(Given that the user's (Neo)Vim supports said virtual text)

Code of Conduct

• I agree to follow this project's Code of Conduct.

Footnotes

1. https://go.dev/ref/spec#Rune_literals ↩ ↩²

2. https://docs.python.org/3/howto/unicode.html ↩

3. https://neovim.io/doc/user/api.html#api-extmark ↩

4. https://vimhelp.org/textprop.txt.html ↩

5. https://vimhelp.org/textprop.txt.html#virtual-text ↩

Proposal: "Include" directive

Description

This feature is not related to a problem, but does draw inspiration from a suggestion made in the YAGPDB support server:

Vloralys#3408
Suggestion: #1814
One centralized template file for all custom commands

Currently you can use define to create some templates for your custom commands, which make life easier by containing things that get repeated very often in a custom command. Unfortunately templates that are used in multiple commands are hard to maintain, because you need to copy&paste around every little change to each single command and hopefully not miss a single one. Therefor it would be easier to maintain one single file/source/thing which gets included into each single custom command automagically.

Example:

1. Manage YAGPDB
2. Click "Command Settings"
3. Click the tab "Templates" (new)
4. Have one (or multiple) textarea to fill in some define.
5. Reuse them in any Custom Command

Suggestion ID 528415266577842196, made on 05/15/2022

Solution

While it doesn't make much sense to implement this in Yag itself, file substitution (á la #include) would be quite doable for an editor plugin.

We would simply define our own "include" directive, and when the appropriate action is triggered, replace instances of the directive with the specified file. The resulting processed code would be saved to a new location (probably using the original filename, plus a suffix of some sort).

Code of Conduct

• I agree to follow this project's Code of Conduct.

Consider Using `yagfuncdata`

Discussed in #64

^{Originally posted by jo3-l August 1, 2022}
https://github.com/jo3-l/yagfuncdata is a little CLI tool I wrote to
automatically fetch names of YAGPDB template functions. From the README:

yagfuncdata aims to simplify workflows of projects that require a list
of YAGPDB template functions, such as language support extensions for
editors. For example, one could imagine setting up a cronjob in CI to
run yagfuncdata regularly to check for updates and regenerate some
asset file if anything changed.

Note, however, that it is not recommended to run yagfuncdata directly
as part of an application as the command is not infallible. Changes to
the structure of relevant files defining template functions may cause
the generated list to be incomplete or downright wrong. (We elaborate
on why this is the case below.) Thus, its output should be manually
vetted by a human against a reliable baseline.

Perhaps yagfuncdata could be of use to this project, which seems to
maintain a similar list as part of the syntax definition that requires
manual updating.

---

I'll be working on this in the coming week. A sample of the output
follows.

$ go install github.com/jo3-l/yagfuncdata/cmd/lytfs@latest
$ lytfs
editMessage
editMessageNoEscape
pinMessage
# [...]

I'm fine with us parsing this output line-by-line and then doing the
following to syntax/yagpdbcc/functions.vim:

syn keyword yagFunc editMessage contained
syn keyword yagFunc editMessageNoEscape contained
syn keyword yagFunc pinMessage contained
" [...]

Obviously, this will really bloat that file up — however I think this is
the easiest sh / Python / whatever way achievable without having to
do some funky character counting to adhere to our max line width as
specified in .editorconfig.

In case you're opposed to that idea, do let me know — we'll be marking
that file as generated as well via .gitattributes, just to be on the
safe(r) side.

As Joe outlined, the possibly simplest way would be to use the cron
feature of GitHub's workflows.

Of course this workflow will create an automated PR we still have to
manually review (just in case), but it'll be a lot less work than us
updating the list.
Compatibility to the make generate target will be kept as far as I
can tell. (It's been a while since I wrote that script).

Though I still will want to have a script that can be run locally to
generate the list, so that users can easily update it themselves,
should they want to.

Tangentially, I'll also be filing a feature request at yagfuncdata for
a flag to pass a custom URL and suchlike, to make the above also
possible for custom forks of YAGPDB.

Add Option to Override Filetypes

Expected Behaviour

When entering NVim with a *.go.tmpl file, it is expected that the plugin changes the filetype to yagpdbcc, thus granting syntax highlighting.

Actual Behaviour

Instead, the filetype remains on gohtmltmpl, which seems to be set by (Neo)vim itself.

Steps to Reproduce

(Make sure the plugin is loaded already or loads on-demand)

$ nvim demo.go.tmpl

:set verbose ft?

See ft=gohtmltmpl instead of ft=yagpdbcc.

Additional Context

$ nvim --version
NVIM v0.6.1
Build type: Release
LuaJIT 2.0.5
Compiled by builduser

Features: +acl +iconv +tui
See ":help feature-compile"

   system vimrc file: "$VIM/sysinit.vim"
  fall-back for $VIM: "/usr/share/nvim"

Run :checkhealth for more info

I'm not entirely sure where to begin troubleshooting -- I suspect the double extension is throwing our code off.

Code of Conduct

• I agree to follow this project's Code of Conduct.

[Bug]: Cmp Sources Aren't Loaded

Expected Behaviour

When writing custom command code, it is expected that (given proper configuration) items for completion are suggested.

Actual Behaviour

Instead, no items for completion were suggested.

Steps to Reproduce

1. Install the plugin as instructed
2. Activate nvim-cmp sources as instructed
3. Type some code
4. See nothing happening

Additional Context

When you run

:lua require('yagpdbcc')

It is loading the sources (technically the Lua plugin) and thus fixing this issue.

I've already hunted the bug down and have a patch ready, this issue is solely for bookkeeping issues, a PR follows.

Code of Conduct

• I agree to follow this project's Code of Conduct.

[Bug]: `g:yagpdbcc_override_ft` without effect

Expected Behaviour

For *.go.tmpl and .gotmpl files:

:set verbose ft?
filetype=yagpdbcc

Actual Behaviour

Without another's plugin interference:
For *.go.tmpl files:

:set verbose ft?
filetype=template

*.gotmpl files are working as expected.

Steps to Reproduce

In init.vim

let g:yagpdbcc_override_ft = 1
lua << EOF
require('plugins')
EOF

in lua/plugins.lua with packer.nvim:

return require('packer').startup({function(use)
    use 'l-zeuch/yagpdb.vim'
end
})

Additional Context

I've confirmed that this only happens for files with *.go.tmpl extensions, even with fatih/vim-go loaded and active (which was the initial reason for #32 and #14). Overriding associations for *.gotmpl works as expected.

Nvim version

NVIM v0.6.1
Build type: Release
LuaJIT 2.1.0-beta3
Compiled by builduser

Features: +acl +iconv +tui
See ":help feature-compile"

   system vimrc file: "$VIM/sysinit.vim"
  fall-back for $VIM: "/usr/share/nvim"

Run :checkhealth for more info

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Validate Top-Level Objects

Description

This proposal asks to implement some sense of validation for top-level objects like .User, .Guild, etc.

Additionally, it'd be nice if we can find a way to also have auto-completion available for them.

Solution

Initial thoughts: Have some sort of dict lookup table from which we can determine:

1. If it is a valid top-level object
2. Validate its fields alongside

However, this might cause issues within range and other structures that manipulate the dot context. We'd have to parse the context around the object and then determine whether to launch validation, or not.

This also poses an issue with the auto-completion engine: My knowledge around the engine we provide sources for is heavily limited, and their documentation on such pretty "advanced" stuff is... lacking to say the least.

Perhaps we can consider implementing our own completion engine, entirely tailored to our needs. If possible, even in pure Vim Script, so that both Vim and Neovim can benefit from this feature.

The last point is, at least currently, not trivial -- here it is worth looking further into it and pushing Vim Script to its absolute limits.

As easy as it might seem to just look at other completion engines's code, I believe a clean-room implementation is both beneficial to us, as developers, as well as avoiding potential license / copyright claims. An active development branch should be considered.

---

Thinking further, the classic RegEx ways are quite excessive and inherently slow; though Vim's RegEx is powerful, it is still RegEx in the end and comes with its shortcomings, such as

1. Hard to read
2. Hard to maintain

There might be a third way, which I am missing, but I'll update this comment whenever I have a new idea.

With this feature implemented, we can also consider validating the syntax on some basic level -- though, at some point, we should consider implementing an LSP, which defines the grammar proper rather than admittedly hacks via Vim Script.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Minify Code

Description

In a similar fashion to jo3-l/cc-minifier, add a command (and/or binding) to generate a minified version of the current buffer contents.

Solution

To begin with, I'm not entirely sure if this feature is even possible in pure Vim script, or if we have to resort to the Lua API, and thus make this a Neovim-only feature.
I'll do some research in those regards and see if I can come up with results that bring this forward.

However, before I further go into the discussion of a potential solution, we first have to consider the dreaded feature creep — is such a feature really necessary and needed?
To me it sure seems convenient to just enter a command and have a minimal version of my code.

Finally, we have to consider multiple things:

• Sane defaults that are not too aggressive but still show some decent results
• A way to conveniently and easily manipulate the result

Regarding my first point, this definitely needs some discussion. Perhaps we can take inspiration at jo3-l/cc-minifier?
With respect to the second point however, we'll have to decide a way.

Comments feel rather clunky and unnecessarily complicated to me — their format and what argument does what would have to be documented well.

If we can pass arguments to our command, then I suggest we go with that, in a very similar fashion to command line programs that already do text manipulation. We would then also be able to bundle multiple effects into one single argument, say --aggressive.

The format, whether we use the flag syntax or pass arguments surely is up to debate. Personally, I like the flags style more, they feel to me more appropriate.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Setup Vint (Vim Lint)

Description

As the codebase grows and contributions are made, some sort of linting and basic code check for correctness should be made, mainly for consistency reasons.

Solution

Thus, I propose to setup vint, a highly extensible linter for the Vim Script language.

It is moreover a rather easy task to set up a workflow launching said software, for which I'd be happy to submit a pull request.

Let me know what you think.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Makefile: Deal with Windows

Description

It is possible to install GNU make on Windows.

Currently, our Makefile is untested on Windows, and is likely to misbehave at best. We can try to detect the current OS, and react as we deem appropriate.

Solution

Windows OS detection can apparently be accomplished with:

ifeq ($(OS),Windows_NT)
	@echo 'Do stuff here...'
endif

If we detect that we are running on Windows, we have two main options:

1. Return an error message and exit
   • Plugin managers are, in my experience, quite usable on Windows, with proper configuration, so we might recommend this in our message
2. Change the appropriate paths and install anyway
   • I believe this also changes depending on whether Vim or Neovim is in use
   • Higher complexity

I personally feel that the first option is perfectly acceptable, since anyone who's running Vim and Make on Windows should be comfortable configuring things themselves.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Move Documentation to Repository Wiki

Description

As it stands, we have quite a substantial and rather massive README file, consisting of installation instructions and other irrelevant information to the development of this project.

Solution

Because the README file is, in my opinion, meant for contributors and developers rather than users, I suggest that we move all such irrelevant information to the repository's wiki, which is meant for users.

Of course, it might be not that much currently, however in the long run, as this project grows, it is definitely a feasible option to do so.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Request: Remove Modelines and Use EditorConfig

Seeing as Vim modelines pose a security concern and are generally frowned upon, I suggest to instead resort to EditorConfig.

Reading from their documentation, everything we already do via the modelines throughout the repository is just as possible using EditorConfig. Moreover, EditorConfig allows for consistent configuration across a larger set of editors, rather than solely Vim and its derivatives.

See also https://security.stackexchange.com/questions/36001/vim-modeline-vulnerabilities for a discussion, as well as:

• CVE-2002-1377
• CVE-2005-2368
• CVE-2007-2438
• CVE-2016-1248
• CVE-2019-12735

Although it is not impossible that these vulnerabilities are already patched, it is nonwithstanding still a good practise to abandon modelines and instead use a universal format.

Proposal: Deprecate Some File Extensions

Description

Currently, we support a plethora of file extensions, namely the
following:

yagpdb.vim/ftdetect/yagpdbcc.vim

Lines 31 to 38 in 83f3fae

	" Detect our 'own' extensions, which are usually used by a
	" vast majority of the userbase.
	au BufRead,BufNewFile *.yag setfiletype yagpdbcc
	au BufRead,BufNewFile *.yagpdb setfiletype yagpdbcc
	au BufRead,BufNewFile *.yagcc setfiletype yagpdbcc
	au BufRead,BufNewFile *.yag-cc setfiletype yagpdbcc
	au BufRead,BufNewFile *.yagpdbcc setfiletype yagpdbcc
	au BufRead,BufNewFile *.yagpdb-cc setfiletype yagpdbcc

This is certainly a lot, and potentially way too much. There are also
some potential issues with a hyphenated file extension (just a gut
feeling, I haven't tested it) — moreover, long file extensions are just
really weird.

Solution

I propose we drop support for yagpdb, yagpdbcc, yag-cc, and
yagpdb-cc in favour of just yag and maybe yagcc. The option to
override tmpl and go.tmpl should be kept, though, as
yagpdb-cc/yagpdb-cc uses the latter one (for whatever reason, Joe
doesn't remember why).

Obviously this will be a breaking change, and thus needs proper
announcement, at the very least inside the commit message. Keeping this
issue open for a while will also help with that.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Support Discord Markdown

Description

When writing output of custom commands, it is quite a regular thing to use Discord's markdown to spice it up a little and make it more appealing.

Solution

For this, I suggest to detect and highlight Discord's markdown markers, just like some markdown extensions already do. I understand that some formatting might get a little weird, for this we'd have to think of a way and maybe look laterally, how other extensions specifically for markdown handle that.

Furthermore it might be worthwhile to highlight markdown only when it makes sense, i.e. in print*, cembed field values and descriptions, and of course in plain text.

Code of Conduct

• I agree to follow this project's Code of Conduct.

Proposal: Rename Project

Considering current trends in the (N)Vim-Plugin community, I think it would be feasible to rename this project to something similarly catchy, such as any of the following:

• yagpdb.nvim
• yagpdb.vim

This is not an exhaustive list and only contains proposals I could think of off the top of my hat. Feel free to comment and suggest more new names, following a similar simplistic pattern.
Regarding branding rights, I'll do some research and talking to the right people.