DEV Community: Ellison Leão

Gerando documentação vimdoc de plugins Neovim com Github Actions

Ellison Leão — Wed, 26 Jul 2023 20:40:59 +0000

Dificuldade: intermediário

Escrever documentação nem sempre é uma das tarefas mais prazerosas, mas ter uma boa documentação nos nossos projetos é o que realmente faz diferença. Ainda mais quando usamos ferramentas que nos auxiliam nessa escrita.

Nesse post vamos ensinar como automatizar a geração da documentação específica para plugins Neovim utilizando Github Actions

Entendendo o fluxo

Assumindo que entendemos o fluxo básico das Github Actions, temos o seguinte fluxo para a geração da doc:

Fazemos um push na branch principal (geralmente chamada de main)
Um job chamado docs é iniciado com os seguintes passos:
- Conversão do README.md do seu projeto em um arquivo .txt no formato vimdoc
- Criamos um commit e fazemos o push na mesma branch com o resultado da conversão

Convertendo isso para o Github Actions, temos:

Crie um arquivo .github/workflows/docs.yml com o seguinte conteúdo:

on:
  push:
    branches:
      - main # aqui nossa branch principal se chama `main`

jobs:
  docs:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v3
      - name: panvimdoc
        uses: kdheepak/panvimdoc@main
        with:
          vimdoc: nome-do-seu-projeto # sem extensão .txt
          version: "Neovim >= 0.8.0"
          demojify: true # coloque false caso queira manter os emojis
          treesitter: true
      - name: Push changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "auto-generate vimdoc"
          commit_user_name: "github-actions[bot]"
          commit_user_email: "github-actions[bot]@users.noreply.github.com"
          commit_author: "github-actions[bot] <github-actions[bot]@users.noreply.github.com>"

Preparando seu README

Para um bom resultado de uma documentação vimdoc, recomendamos que seu README tenha pelo menos:

Uma seção Sobre
Uma seção Instalação
Uma seção Como usar

O uso de tabelas, bullet points também é suportado e recomendado. Quanto mais detalhes conseguir colocar na documentação, melhor ficará o resultado (até emojis são suportados!)

Colocando tudo para funcionar

Antes de commitar e rodar a action pela primeira vez, crie o arquivo vazio da doc:

$ touch doc/nome-do-seu-projeto.txt
$ git add doc/nome-do-seu-projeto.txt
$ git commit -m 'adicionando arquivo vimdoc'
$ git push

Agora envie o novo worflow:

$ git add .github/workflows/docs.yml
$ git commit -m 'adicionando docs workflow'
$ git push

Se tudo deu certo, você já poderá ver o resultado do workflow com seu vimdoc gerado na branch principal. Exemplo do resultado na imagem abaixo

Exemplo pode ser visto aqui

Links úteis

Documentação da github action
Exemplo de um bom README vs o resultado em vimdoc

Se gostou do artigo, não esqueça de compartilhar em outras redes e aproveita e me segue também! https://linktr.ee/ellisonleao

Meus 10 plugins favoritos para o Neovim em 2022

Ellison Leão — Fri, 13 May 2022 17:56:41 +0000

Uma breve lista dos melhores plugins pra usar agora e aumentar sua produtividade

Quando comecei a usar o Neovim, lá por 2017, depois de passar 6 anos usando Vim, não tinha sentido uma diferença tão grande porque primeiro a API lua era praticamente inexistente e minha configuração ainda era puramente vimscript e meus plugins também.

Mas tudo mudou quando fiz o upgrade pras versões 0.4.x e gradualmente comecei a me aventurar no mundo do Lua, no final de 2019. De lá pra ca já consegui migrar minhas configurações 100% para Lua e 99% dos plugins que uso hoje também são feitos na linguagem. Aqui vai minha lista dos 10 melhores plugins que acho indispensáveis hoje:

#10

wbthomason / packer.nvim

A use-package inspired plugin manager for Neovim. Uses native packages, supports Luarocks dependencies, written in Lua, allows for expressive config

NOTICE:

This repository is currently unmaintained. For the time being (as of August, 2023), it is recommended to use one of the following plugin managers instead:

lazy.nvim: Most stable and maintained plugin manager for Nvim.
pckr.nvim: Spiritual successor of packer.nvim. Functional but not as stable as lazy.nvim.

packer.nvim

use-package inspired plugin/package management for Neovim.

Have questions? Start a discussion.

Have a problem or idea? Make an issue or a PR.

Packer is built on native packages. You may wish to read :h packages before continuing

Features

Declarative plugin specification
Support for dependencies
Support for Luarocks dependencies
Expressive configuration and lazy-loading options
Automatically compiles efficient lazy-loading code to improve startup time
…

View on GitHub

Começando por esse incrível gerenciador de plugins, que vai deixar sua vida bem mais fácil na hora de instalar, atualizar e configurar seus plugins, principalmente se você utiliza lua nas suas configurações. Tem suporte a instalação de pacotes do luarocks, lazy loading e mais.

#9

numToStr / Comment.nvim

🧠 💪 // Smart and powerful comment plugin for neovim. Supports treesitter, dot repeat, left-right/up-down motions, hooks, and more

// Comment.nvim

^{⚡ Smart and Powerful commenting plugin for neovim ⚡}

✨ Features

Supports treesitter. Read more
Supports commentstring. Read :h comment.commentstring
Supports line (//) and block (/* */) comments
Dot (.) repeat support for gcc, gbc and friends
Count support for [count]gcc and [count]gbc
Left-right (gcw gc$) and Up-Down (gc2j gc4k) motions
Use with text-objects (gci{ gbat)
Supports pre and post hooks
Ignore certain lines, powered by Lua regex

🚀 Installation

With lazy.nvim

-- add this to your lua/plugins.lua, lua/plugins/init.lua,  or the file you keep your other plugins:
{
    'numToStr/Comment.nvim',
    opts = {
        -- add any options here
    }
}

With packer.nvim

use {
    'numToStr/Comment.nvim',
    config = function()
        require('Comment').setup()
    end
}

With vim-plug

Plug 'numToStr/Comment.nvim'
" Somewhere after plug#end()

…

View on GitHub

Um poderoso plugin para inserir e remover comentários em códigos. Tem suporte ao treesitter, que vamos falar mais pra frente.

#8

neovim / nvim-lspconfig

Quickstart configs for Nvim LSP

nvim-lspconfig

nvim-lspconfig is a "data only" repo, providing basic, default Nvim LSP client configurations for various LSP servers. View all configs or :help lspconfig-all from Nvim.

Important ⚠️

These configs are best-effort and supported by the community (you). See contributions.
Ask questions on GitHub Discussions, not the issue tracker.
If you found a bug in Nvim LSP (:help lsp), report it to Neovim core
- Do not report it here. Only configuration data lives here.
This repo only provides configurations. Its programmatic API is deprecated and must not be used externally.
- The "framework" parts (not the configs) of nvim-lspconfig will be upstreamed to Nvim core.

Install

Requires Nvim 0.10 above. Update Nvim and nvim-lspconfig before reporting an issue.

Install nvim-lspconfig using Vim's "packages" feature:

git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig

Or use a 3rd-party plugin manager (consult the documentation for your plugin manager).

Quickstart

Install…

View on GitHub

Plugin obrigatório para quem quer utilizar o maravilhoso cliente nativo LSP. Com esse plugin a configuração dos LSP servers das linguagens fica extremamente fácil.

#7

williamboman / nvim-lsp-installer

Further development has moved to https://github.com/williamboman/mason.nvim!

ℹ️ Project status

This is an excerpt from the announcement here.

nvim-lsp-installer is no longer maintained.

mason.nvim is the next generation version of nvim-lsp-installer. It builds on top of the very same foundation as nvim-lsp-installer (which means it's easy to migrate), but with a majority of internals refactored to improve extensibility and testability.

More importantly, the scope of mason.nvim has also been widened to target more than just LSP servers. mason.nvim supports DAP servers, linters, formatters, and more. As of writing, mason.nvim provides 150+ packages for 100+ languages. It can be thought of as a general-purpose package manager, native to Neovim, that runs everywhere Neovim runs (Windows, macOS, Linux, etc.).

Another big change with mason.nvim is that executables are now linked to a single, shared, location, allowing seamless access from Neovim builtins (shell, terminal, etc.) as well as other 3rd party plugins.

There have also been other improvements…

View on GitHub

Plugin que fornece todo suporte para uma rápida instalação dos LSP servers com uma excelente UX. É um plugin que funciona em conjunto com o nvim-lspconfig

#6

jose-elias-alvarez / null-ls.nvim

Use Neovim as a language server to inject LSP diagnostics, code actions, and more via Lua.

ARCHIVED

null-ls is now archived and will no longer receive updates. Please see this issue for details.

null-ls.nvim

Use Neovim as a language server to inject LSP diagnostics, code actions, and more via Lua.

Motivation

Neovim's LSP ecosystem is growing, and plugins like telescope.nvim and trouble.nvim make it a joy to work with LSP features like code actions and diagnostics.

Unlike the VS Code and coc.nvim ecosystems, Neovim doesn't provide a way for non-LSP sources to hook into its LSP client. null-ls is an attempt to bridge that gap and simplify the process of creating, sharing, and setting up LSP sources using pure Lua.

null-ls is also an attempt to reduce the boilerplate required to set up general-purpose language servers and improve performance by removing the need for external processes.

Status

null-ls is in beta status. Please see below for steps to follow if something doesn't work the way…

View on GitHub

Gere diagnósticos, formate, realize ações de código e mais, utilizando esse plugin que utiliza o neovim como um servidor LSP, e faz a ponte entre ferramentas que não fazem uma conexão direta com o cliente nativo LSP. Entre os exemplos podemos citar:

Formatar código ao salvar o buffer com o prettier
Gerar relatório de erros e warnings com golangci-lint para Go
Formatar código Lua com stylua

e mais!

#5

nvim-treesitter / nvim-treesitter

Nvim Treesitter configurations and abstraction layer

nvim-treesitter

Treesitter configurations and abstraction layer for Neovim

Logo by @steelsojka

The goal of nvim-treesitter is both to provide a simple and easy way to use the interface for tree-sitter in Neovim and to provide some basic functionality such as highlighting based on it:

Traditional highlighting (left) vs Treesitter-based highlighting (right) More examples can be found in our gallery.

Warning: Treesitter and nvim-treesitter highlighting are an experimental feature of Neovim. Please consider the experience with this plug-in as experimental until Tree-Sitter support in Neovim is stable! We recommend using the nightly builds of Neovim if possible. You can find the current roadmap here. The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!

Nvim-treesitter is based on three interlocking features: language parsers, queries, and modules, where modules provide features – e.g., highlighting – based on…

View on GitHub

Um plugin que faz interface com o excelente projeto tree-sitter e traz funcionalides como _syntax highlighting _, indentação, seleção incremental, movimentação, folding, entre outros.

#4

L3MON4D3 / LuaSnip

Snippet Engine for Neovim written in Lua.

LuaSnip

javadoc.mp4

Features

Tabstops
Text-Transformations using Lua functions
Conditional Expansion
Defining nested Snippets
Filetype-specific Snippets
Choices
Dynamic Snippet creation
Regex-Trigger
Autotriggered Snippets
Easy Postfix Snippets
Fast
Parse LSP-Style Snippets either directly in Lua, as a VSCode package or a SnipMate snippet collection.
Expand LSP-Snippets with nvim-compe (or its' successor, nvim-cmp (requires cmp_luasnip))
Snippet history (jump back into older snippets)
Resolve filetype at the cursor using Treesitter

Drawbacks

Snippets that make use of the entire functionality of this plugin have to be defined in Lua (but 95% of snippets can be written in LSP-syntax).

Requirements

Neovim >= 0.7 (extmarks) jsregexp for lsp-snippet-transformations (see here for some tips on installing it).

Setup

Install

With your preferred plugin manager i.e. vim-plug, Packer or lazy
Packer:

use({
    "L3MON4D3/LuaSnip"
    -- follow latest release.
    tag = "v2.*", -- Replace <CurrentMajor> by the latest released major (first

…

View on GitHub

O melhor script para criação de snippets do Neovim. Simples assim. Tem uma curva de aprendizado um pouco alta, mas quando se pega o jeito, você não vai querer largar nunca. Aqui um vídeo explicando mais sobre as funcionalidades dele (Em inglês)

#3

hrsh7th / nvim-cmp

A completion plugin for neovim coded in Lua.

nvim-cmp

A completion engine plugin for neovim written in Lua Completion sources are installed from external repositories and "sourced".

demo.mp4

Readme!

There is a GitHub issue that documents breaking changes for nvim-cmp. Subscribe to the issue to be notified of upcoming breaking changes.
This is my hobby project. You can support me via GitHub sponsors.
Bug reports are welcome, but don't expect a fix unless you provide minimal configuration and steps to reproduce your issue.
The cmp.mapping.preset.* is pre-defined configuration that aims to mimic neovim's native like behavior. It can be changed without announcement. Please manage key-mapping by yourself.

Concept

Full support for LSP completion related capabilities
Powerful customizability via Lua functions
Smart handling of key mappings
No flicker

Setup

Recommended Configuration

This example configuration uses vim-plug as the plugin manager and vim-vsnip as a snippet plugin.

call plug#begin(s:plug_dir)
Plug 'neovim/nvim-lspconfig'
Plug 'hrsh7th/cmp-nvim-lsp

…

View on GitHub

Seguindo o melhor plugin para snippets, esse com certeza vai ser o melhor plugin para autocomplete que você irá ter no mercado até o momento. Seu design flexível permite incluir vários tipos diferentes de sources, desde sugestões de LSP, snippets, etc. A lista é gigantesca e você também conta com uma excelente documentação caso queira criar os seus próprios sources também.

#2

nvim-lualine / lualine.nvim

A blazing fast and easy to configure neovim statusline plugin written in pure lua.

lualine.nvim

A blazing fast and easy to configure Neovim statusline written in Lua.

lualine.nvim requires Neovim >= 0.7.

For previous versions of neovim please use compatability tags for example compat-nvim-0.5

Contributing

Feel free to create an issue/PR if you want to see anything else implemented. If you have some question or need help with configuration, start a discussion.

Please read CONTRIBUTING.md before opening a PR. You can also help with documentation in the wiki.

Screenshots

Here is a preview of what lualine can look like.

Screenshots of all available themes are listed in THEMES.md

For those who want to break the norms, you can create custom looks for lualine.

Example :

Performance compared to other plugins

Unlike other statusline plugins, lualine loads only the components you specify, and nothing else.

Startup time performance measured with an amazing plugin dstein64/vim-startuptime

Times are measured with a…

View on GitHub

Minha escolha para plugin de statusline. Simples, rápido e bem flexível.

#1

nvim-telescope / telescope.nvim

Find, Filter, Preview, Pick. All lua, all the time.

telescope.nvim

Gaze deeply into unknown regions using the power of the moon.

What Is Telescope?

telescope.nvim is a highly extendable fuzzy finder over lists. Built on the latest awesome features from neovim core. Telescope is centered around modularity, allowing for easy customization.

Community driven builtin pickers, sorters and previewers.

For more showcases of Telescope, please visit the Showcase section in the Telescope Wiki

Telescope Table of Contents

Getting Started

This section should guide you to run your first builtin pickers.

Neovim (v0.9.0) or the latest neovim nightly commit is required for telescope.nvim to work. The neovim version also needs to be compiled with LuaJIT, we currently do not support Lua5.1 because of some ongoing issues.

Required dependencies

nvim-lua/plenary.nvim is required.

Suggested dependencies

BurntSushi/ripgrep is required for live_grep and grep_string and…

View on GitHub

Talvez o plugin mais essencial de todos hoje. Faça buscas por arquivo, texto e muito mais, numa velocidade absurda, com esse plugin fantástico.

Conclusão

Com o ecossistema Lua se desenvolvendo cada dia mais, muitos plugins estão surgindo todos os dias e com certeza essa lista provavelmente precisará ser atualizada em um futuro próximo.

Faltou algum plugin nessa lista? Me conta ae nos comentários!

Criando plugins Lua para Neovim - Parte 3

Ellison Leão — Mon, 09 May 2022 17:20:28 +0000

Migrando do init.vim para o init.lua

Para fechar nossa série de criação de plugins em Lua para o Neovim, vamos mudar um pouco o foco na criação de plugins para um tutorial de como podemos migrar toda nossa configuração do Neovim usando o tradicional Vimscript, para Lua.

Mas por que Lua?

A decisão tomada pelo core team de desenvolvimento do Neovim tem várias respostas diversas, que vão desde velocidade a facilidade de escrita, pelo fato de Lua ser uma linguagem bem extensível. Para entender as principais motivações, sugiro dar uma pausa no post e apreciar a talk “We can have nice things”, do Justin M. Keyes, um dos atuais líderes de desenvolvimento do Neovim.

A migração

Caso você ainda não conheça a estrutura de diretórios do Neovim, toda configuração vai em:

Unix: ~/.config/nvim/init.vim
Windows: ~/AppData/Local/nvim/init.vim
ou, caso você queria um path de config customizado, onde $XDG_CONFIG_HOME é definido, fica assim:

$XDG_CONFIG_HOME/nvim/init.vim

Esse arquivo é o ponto de entrada para as configurações customizadas do editor, desde cores, tamanhos de fonte, a instalação de plugins.

No nosso caso, começaremos renomeando o arquivo init.vim para init.old e criando um novo arquivo chamado init.lua.

Por quê precisamos renomear o init.vim?

No neovim não é possível existir 2 pontos de entrada para as configurações, então você só poderá usar o init.vim ou o mais recente, init.lua

Para o nosso tutorial não ficar bastante extenso, iremos usar um init.vim relativamente pequeno, explicando as principais configurações e como portá-las para a versão em lua.

Mas primeiro precisamos relembrar como a API em Lua se comporta.

O namespace `vim`

Na implementação da API Lua para o Neovim, existe uma variável chamada vim, que é o ponto de entrada para todas as funções da chamada “biblioteca padrão” Lua para o Neovim. Essas funções servem diferentes propósitos, mas o principal sendo a ponte entre o código lua e o editor. Algumas APIs incluem:

vim.inspect - uma função de debug para inspecionar resultados. Geralmente em lua, os resultados vem em tables, e esses são difíceis de ser expostos em formato de “print”. Essa função “disseca” a váriável que você gostaria de expor de uma forma mais amigável.
vim.regex - Módulo que possibilita o uso de regexes diretamente no código Lua. Para mais info :h vim.regex
vim.api - Provavelmente o módulo mais importante dessa API. Aqui encontramos todas a funções para trabalhar com buffers, windows, chamar comandos do neovim, etc.
vim.loop - Módulo que funciona como uma camada de abstração da LibUV, a camada de event-loop do Neovim. Pra quem quer usar concorrência, timers, etc, esse módulo é o caminho.
vim.lsp - Pra quem trabalhar diretamente na fantástica implementação nativa de um cliente LSP dentro do Neovim.
vim.treesitter - O módulo que expõe algumas funções para se trabalhar diretamente com o tree-sitter.
vim.keymap - Inclua ou remova keymaps do vim

Para este post, focaremos apenas na vim.api e vim.keymap

Nosso arquivo init.lua

Levando em consideração que nosso init.vim tinha a seguinte cara:

" Parte 1
set colorcolumn=80
set expandtab
set tabstop=4
set autoindent
set incsearch
set hlsearch
set termguicolors

" Parte 2
let g:minha_config = 'valor'
let g:algumnamespace#teste#variavel = "valor"

" Parte 3
nmap <leader>, <Cmd>:noh<CR>
nnoremap <leader>h <Cmd>split<CR>
vnoremap < <gv

" Parte 4
autocmd BufEnter * echo "hello nvim"

" Parte 5
function! SayHello()
  echohl WarningMsg
  echo "Hello World"
  echohl
endfunction`

separamos a migração em 4 partes:

options
vars
mappings
autocmds
functions

Para a parte 1, temos as seguintes funções da vim.api:

vim.api.nvim_set_option
vim.api.nvim_buf_set_option
vim.api.nvim_win_set_option

Para facilitar a escrita, temos o atalho vim.opt:

vim.opt.termguicolors = true   -- set termguicolors
vim.opt.colorcolumn = 80       -- set colorcolumn=80
vim.opt.expandtab              -- set expandtab
vim.opt.tabstop=4              -- set tabstop=4
vim.opt.autoindent = true      -- set autoindent
vim.opt.incsearch = true       -- set incsearch
vim.opt.hlsearch = true        -- set hlsearch

Continuando com a parte 2, temos uma declaração de uma variável global (escopo g:). Na API, podemos utilizar as seguintes funções:

vim.api.nvim_set_var e suas variações (vim.api.nvim_get_var e vim.api.nvim_del_var)
Aqui também temos uma versão “minimalista” com seus respectivo meta-acessor (ver :h lua-vim-variables para mais detalhes):

vim.g - Também funciona como um getter/setter

Temos então nosso código lua, com a parte 2:

-- parte 1
vim.opt.termguicolors = true   -- set termguicolors
vim.opt.colorcolumn = 80       -- set colorcolumn=80
vim.opt.expandtab = true       -- set expandtab
vim.opt.tabstop = 4            -- set tabstop=4
vim.opt.autoindent = true      -- set autoindent
vim.opt.incsearch = true       -- set incsearch
vim.opt.hlsearch = true        -- set hlsearch

-- parte 2
vim.g.minha_config = "valor"
 -- o `meta-acessor` é uma table, então podemos atribuir valores usando também os colchetes
vim.g["algumnamespace#teste#variavel"] = "valor"

Para a parte 3 temos os mappings e para isso temos 2 funções que podem ser utilizadas:

vim.api.nvim_set_keymap - mappings que serão atribuídos para todos os buffers
vim.api.nvim_buf_set_keymap - mappings que serão exclusivos de algum buffer em particular

Para facilitar ainda mais, na versão 0.7 foi introduzida a API vim.keymap (:h lua-keymap), que deixa as coisas bem mais fáceis quando precisamos criar os mappings.

Temos então, no nosso arquivo lua:

-- parte 1
vim.opt.termguicolors = true   -- set termguicolors
vim.opt.colorcolumn = 80       -- set colorcolumn=80
vim.opt.expandtab = true       -- set expandtab
vim.opt.tabstop = 4            -- set tabstop=4
vim.opt.autoindent = true      -- set autoindent
vim.opt.incsearch = true       -- set incsearch
vim.opt.hlsearch = true        -- set hlsearch

-- parte 2
vim.g.minha_config = "valor"
 -- o `meta-acessor` é uma table, então podemos atribuir valores usando também os colchetes
vim.g["algumnamespace#teste#variavel"] = "valor"

-- parte 3
vim.keymap.set("n", "<leader>,", "<Cmd>:noh<CR>", nil) -- nmap <leader>, <Cmd>:noh<CR>
vim.keymap.set("n", "<leader>h", "<Cmd>split<CR>", {noremap = true}) -- nnoremap <leader>h <Cmd>split<CR>
vim.keymap.set("v", "<", "<gv", {noremap = true}) -- vnoremap < <gv

Já para a parte 4, vamos adicionar os autocmd e augroups. Para isso, iremos usar a função vim.api.nvim_create_autocmd, introduzida também na versão 0.7. Adicionando a parte 4 na nossa configuração, temos:

-- parte 1
vim.opt.termguicolors = true   -- set termguicolors
vim.opt.colorcolumn = 80       -- set colorcolumn=80
vim.opt.expandtab = true       -- set expandtab
vim.opt.tabstop = 4            -- set tabstop=4
vim.opt.autoindent = true      -- set autoindent
vim.opt.incsearch = true       -- set incsearch
vim.opt.hlsearch = true        -- set hlsearch

-- parte 2
vim.g.minha_config = "valor"
 -- o `meta-acessor` é uma table, então podemos atribuir valores usando também os colchetes
vim.g["algumnamespace#teste#variavel"] = "valor"

-- parte 3
vim.keymap.set("n", "<leader>,", "<Cmd>:noh<CR>", nil) -- nmap <leader>, <Cmd>:noh<CR>
vim.keymap.set("n", "<leader>h", "<Cmd>split<CR>", {noremap = true}) -- nnoremap <leader>h <Cmd>split<CR>
vim.keymap.set("v", "<", "<gv", {noremap = true}) -- vnoremap < <gv

-- parte 4
vim.api.nvim_create_autocmd("BufEnter", {
  callback = function()
    print("hello nvim")
  end
})

Para a última parte, temos uma função vimscript que poderá ser portada utilizando a função vim.api.nvim_exec, que avalia um código vimscript contendo várias linhas. A assinatura da função é da seguinte forma:

vim.api.nvim_exec(bloco_de_codigo, retorno)

Onde:

bloco_de_codigo: A string multiline ou não do bloco de código vimscript que será executado
retorno - true caso deseje retornar o resultado string da execução do bloco, false para retornar uma string vazia

Temos então a versão final da config lua:

-- parte 1
vim.opt.termguicolors = true   -- set termguicolors
vim.opt.colorcolumn = 80       -- set colorcolumn=80
vim.opt.expandtab = true       -- set expandtab
vim.opt.tabstop = 4            -- set tabstop=4
vim.opt.autoindent = true      -- set autoindent
vim.opt.incsearch = true       -- set incsearch
vim.opt.hlsearch = true        -- set hlsearch

-- parte 2
vim.g.minha_config = "valor"
 -- o `meta-acessor` é uma table, então podemos atribuir valores usando também os colchetes
vim.g["algumnamespace#teste#variavel"] = "valor"

-- parte 3
vim.keymap.set("n", "<leader>,", "<Cmd>:noh<CR>", nil) -- nmap <leader>, <Cmd>:noh<CR>
vim.keymap.set("n", "<leader>h", "<Cmd>split<CR>", {noremap = true}) -- nnoremap <leader>h <Cmd>split<CR>
vim.keymap.set("v", "<", "<gv", {noremap = true}) -- vnoremap < <gv

-- parte 1
vim.opt.termguicolors = true   -- set termguicolors
vim.opt.colorcolumn = 80       -- set colorcolumn=80
vim.opt.expandtab = true       -- set expandtab
vim.opt.tabstop = 4            -- set tabstop=4
vim.opt.autoindent = true      -- set autoindent
vim.opt.incsearch = true       -- set incsearch
vim.opt.hlsearch = true        -- set hlsearch

-- parte 2
vim.g.minha_config = "valor"
 -- o `meta-acessor` é uma table, então podemos atribuir valores usando também os colchetes
vim.g["algumnamespace#teste#variavel"] = "valor"

-- parte 3
vim.keymap.set("n", "<leader>,", "<Cmd>:noh<CR>", nil) -- nmap <leader>, <Cmd>:noh<CR>
vim.keymap.set("n", "<leader>h", "<Cmd>split<CR>", {noremap = true}) -- nnoremap <leader>h <Cmd>split<CR>
vim.keymap.set("v", "<", "<gv", {noremap = true}) -- vnoremap < <gv

-- parte 4
vim.api.nvim_create_autocmd("BufEnter", {
  callback = function()
    print("hello nvim")
  end
})

-- parte 5
vim.api.nvim_exec([[
function! SayHello()
  echohl WarningMsg
  echo "Hello World"
  echohl
endfunction
]], false)

Conclusão

Mostramos que, apesar de algumas limitações, portar uma configuração em vimscript para Lua está cada dia mais fácil com a API vigente. Para um exemplo de configuração mais extensa usando mais elementos da API Lua, visite a minha configuração do neovim, deixa seu star por lá também e caso tenha alguma dúvida, manda mensagem por aqui

Lembrando que faço lives esporádicas na Twitch! Caso deseje ver esse tipo de conteúdo ao vivo, não deixe de me seguir por lá e também acompanhar meu Twitter

Para ouvir

Criando plugins Lua para Neovim - Parte 2

Ellison Leão — Mon, 09 May 2022 17:19:46 +0000

Um plugin para o mundo real

Na segunda parte da nossa série vamos criar um plugin que poderá ser usado no dia-a-dia, onde iremos introduzir algumas funcionalidades legais do Neovim, como as floating windows e algumas funções da API lua.

Vamos começar relembrando a estrutura de um plugin. Nosso novo plugin vai possuir a seguinte estrutura:

weather.nvim
├── lua
│  └── weather.lua
└── plugin
   └── weather.lua

A idéia do plugin é mostrar a previsão do tempo atual em uma floating window, sendo chamado a partir de um comando.

Desenhando, vamos ter algo como:

Estrutura do módulo

Nosso módulo weather.lua vai conter a seguinte estrutura:

local M = {}

local function create_command()
-- vamos criar o comando :Weather aqui
end

M.create_window = function()
-- aqui vamos criar a janela, um mapping para fechá-la e mostrar o tempo
end

M.close_window = function()
-- uma função para fechar a janela atual, que sera usada em um mapping
end

return M

Analisando uma por uma, temos:

create_command()

A função create_command() vai criar nosso comando customizado (command!). Aqui introduzimos o vim.cmd, que pode ser utilizada para chamar comandos Ex nativos do vim, mais conhecidos como os comandos :.

defininos nosso comando como:

vim.api.nvim_create_user_command("Weather", M.create_window(), {nargs=0})

com isso, nosso commando, :Weather, vai chamar diretamente uma função do nosso módulo lua para esse plugin

create_window()

a função create_window() vai ser responsável por criar uma floating window no canto superior direito da tela e mostrar o conteúdo do tempo. Para criá-la, precisamos seguir os seguintes passos:

criar um buffer “descartável”, que será usado para o conteúdo da janela
criar as configurações da janela (tamanho de linhas, colunas, posicao x e y na tela, bordas)
chamar o comando que “abre” a janela
criar um mapping para poder fechar a janela
criar o conteúdo do buffer, no nosso caso, o tempo atual.

Para o passo 1, temos:

buf = vim.api.nvim_create_buf(false, true)

Aqui temos outra novidade também, o vim.api , um conjunto de métodos para o neovim dentro do módulo lua vim. nvim_create_buf aceita 2 parâmetros, se o buffer vai ser listado ou não (no nosso caso não, por isso o false) e se ele será descartável ou não (no nosso caso sim, por isso o true). Para saber mais sobre o método, chame :help nvim_create_buf .

O método retorna o id do novo buffer criado, e a informação desse id é importante porque ele será usado para fazer referência em outras funções mais pra frente. Note aqui também que não estamos criando a váriavel buf dentro desse método, mas uma variável “global” do módulo lua que também será usada por outros métodos dentro desse módulo.

Para o passo 2, temos:

  local columns = vim.api.nvim_get_option("columns")
  local lines = vim.api.nvim_get_option("lines")
  local win_width = math.ceil(columns * 0.3 - 10)
  local win_height = math.ceil(lines * 0.3 - 6)
  local x_pos = 1
  local y_pos = columns - win_width

  local win_opts = {
    style = "minimal",
    relative = "editor",
    width = win_width,
    height = win_height,
    row = x_pos,
    col = y_pos,
    border = "single",
  }

Primeiro pegamos as variáveis de total de linhas e colunas do buffer atual para fazer um cálculo proporcional do tamanho da nossa floating window.

relative="editor" é a opção que vai dizer que iremos usar as coordenadas x e y globais, relativas ao editor, tendo tamanho inicial (0,0) até (linhas-1, colunas-1)
style = "minimal", vai deixar nossa janela com configurações mínimas, removendo a maioria das opções de UI. Isso é essencial para janelas temporárias, onde não iremos precisar fazer nenhuma alteração.
width e height é o calculo proporcional do tamanho da janela, adicionando um padding para que ela não fique simplesmente “grudada” no canto superior direito da tela. Cada unidade de medida corresponde a um caracter
row e col vai setar a posição x e y da nossa janela
border vai passar a config da nossa borda da floating window, no caso single representa linhas simples

Para o passo 3, temos:

win = vim.api.nvim_open_win(buf, true, win_opts)

Aqui chamamos a vim.api.nvim_open_win, o método que vai abrir nossa janela, usando o buffer que criamos, com a configuração que passamos. Nos parâmetros, podemos também ver o true, que vai setar a janela como a atual. Vamos precisar disso para chamar o comando que gera o conteúdo da mesma. Note também que nossa variável win também é “global”, pois vamos precisar da informação dela para criar os mappings que vão poder fechá-la.

Para o passo 4, temos:

vim.keymap.set("n", "q", M.close_window(), {noremap = true, silent = true, buffer = buf})

Usamos a nova api introduzida no neovim 0.7 vim.keymap para criar um nnoremap local (somente para o buffer criado), que basicamente irá chamar outro método do nosso módulo, para fechar a janela. Iremos explicar o método close_window() mais pra frente.

Como parâmetros, primeiros temos o modo, no caso o modo Normal, depois o comando que esse mapping irá chamar e finalmente temos uma table com possíveis opções para o mapping, como noremap, silent, etc. No nosso caso, só queremos que o comando não coloque nenhum output na tela e não utilize nenhum outro mapping com a letra q, caso haja algum.

Finalmente para o passo 5, temos:

local command = "curl https://wttr.in/?0"
vim.fn.termopen(command)

Aqui fazemos uma ponte entre lua e vimscript, chamando a função termopen, que basicamente abre um terminal emulado dentro do neovim com o resultado do comando curl

close_window()

A função close window no nosso caso só vai ser uma chamada direta para o nvim_win_close:

vim.api.nvim_win_close(win, true)

Aqui passamos a variável win, que é o id da nossa janela criada e true fala que queremos forçar o fechamento da janela.

Conclusão

Com isso, nosso primeiro plugin “para o mundo real”, está pronto. A versão do código para esse post pode ser vista clicando aqui.

Para ver a versão completa do plugin, com mais customizações, clique aqui e já manda o star!. Para a parte 3 da nossa série, vamos mostrar como portar nossa config do neovim em vimscript totalmente para Lua. Não deixem de acompanhar!

Para ouvir

Criando plugins Lua para Neovim - Parte 1

Ellison Leão — Mon, 09 May 2022 17:17:38 +0000

Uma série mostrando um passo a passo na criação de plugins Lua para o Neovim

Desde que migrei para o Neovim em 2019, depois passar 8 anos usando vim com seus plugins fantásticos, comecei a descobrir as motivações que levaram os core devs a criar esse fork.

Podemos ficar um bom tempo aqui falando sobre elas (e você pode ver uma palestra muito interessante sobre clicando aqui), mas o intuito desde texto é apenas destacar uma delas, e a que eu considero uma das mais importantes: Lua

Quando você instala o Neovim hoje, a linguagem Lua, ou mais especificamente o LuaJIT, uma versão otimizada da linguagem está inserida no core e você consegue usá-la diretamente num vimscript ou chamando um arquivo lua diretamente. Mas como isso acontece?

Esse texto vai fazer parte de uma série onde vou mostrar como é possível criar seu primeiro plugin para o Neovim usando puramente Lua. Primeiro vamos voltar um pouco e mostrar a estrutura de um plugin convencional para o Vim:

~/seu-plugin/
|--plugin/
|--ftplugin/
|--after/
|--autoload/

Para nossa série, iremos focar na pasta plugin por enquanto.

A pasta plugin é usada como ponto de entrada no carregamento do vim. Lá é o lugar onde irão viver os plugins globais. Guarde essa informação pois ela vai ser importante na criação do nosso plugin.

Criando nosso hello-world.nvim plugin

TL;DR : Código para o plugin da primeira parte aqui

Como não utilizaremos de nenhum gerenciador de plugins nessa série, vamos facilitar um pouco o carregamento do mesmo e iremos criar os arquivos diretamente no runtimepath do neovim, mais precisamente em

~/.local/share/nvim/site/plugin

Caso essa pasta não exista em seu sistema, crie com

$ mkdir -p ~/.local/share/nvim/site/plugin

Nosso plugin irá utilizar a versão 0.7 (stable até o momento) do neovim.

Dentro da pasta plugin crie a pasta hello-world.nvim e a subpasta plugin.

$ mkdir -p hello-world.nvim/plugin

Desde a versão 0.6, podemos executar scripts lua diretamente da pasta plugin. Quando falamos no início do post sobre essa pasta e o valor especial que ela tem, estamos falando justamente sobre o ponto de partida do plugin. Se o seu plugin precisa ser carregado toda vez que o neovim abre, o código do seu projeto precisa ser inicializado ou feito diretamente na pasta plugin.

Dentro da pasta, crie o arquivo hello-world.lua e digite:

vim.api.nvim_create_user_command("HelloWorld", function() print("hello world lua!") end, {})

Podemos ver o uso do vim.cmd, uma ponte entre lua e a chamada da função ou de um comando vimscript. Iremos explicar mais exemplos dele e outras APIs, como o vim.api, a mais importante delas.

Agora você pode reiniciar o editor e testar o novo plugin. Depois de fechar e abrir, digite:

:HelloWorld

e poderá ver no prompt de comando a mensagem

hello world lua!

Conclusão

Esta é só a ponta do iceberg do que podemos fazer com Lua no neovim hoje. Nos próximos posts da série iremos abordar como criar floating windows, configurar seu Neovim para usar o LSP nativo (~~e fugir daquele plugin javascript que você deseja tanto~~) e no fim da série vou explicar como migrar seu vimfiles totalmente para lua usando o máximo de plugins puramente feitos em lua no dia-a-dia (sim, isso já é possível!)

Aguardem os próximos posts e não esqueçam de seguir nossas redes

Links Úteis

Documentação Oficial Neovim e Lua

Para ouvir

Não eram apenas copos rosas

Ellison Leão — Wed, 27 Apr 2022 22:12:21 +0000

Um relato sobre minha primeira Global Game Jam

Nos dias 27,28 e 29 de Janeiro aconteceu a Global Game Jam 2012 , o maior evento de game jam do mundo, que reuniu cerca de 10684 participantes espalhados por 42 países e mais de 2000 jogos realizados.

Curitiba foi, esse ano, a segunda maior sede do mundo, com 245 inscritos e só perdeu pra Dinamarca, que teve 290 inscritos. Nosso grupo foi composto por 5 pessoas ( 3 programadores e 2 artistas ). Sem nome inicialmente, chegamos por volta das 17h na sexta feira e já escolhemos um lugar para colocar as tralhas que iríamos usar durante todo o final de semana ( salgados, doces, energéticos, etc..). Às 18h começava o keynote oficial, com palestras de vários nomes da comunidade mundial dos jogos e o tema ainda não tinha sido divulgado.

Uma expectativa pairava o pessoal que estava lá sedendo pela vontade de criar coisas novas e divertidas. Após o keynote de Will Wright, o tema surgira e todos que estavam lá ficaram abismados com um tema tão diferente. Pela primeira vez, o tema da Global Game Jam não era uma palavra e sim uma imagem, Ouroboros.

Infinito, ciclo da vida, morte e ressureição. Esses foram as palavras que palpitavam na grande sala onde os grupos se reuniam para pensar como seria fazer um jogo com estes temas. Era a hora do brainstorm inicial. Nosso grupo ficou cerca de 2 horas jogando idéias num papel, misturando vários elementos e mecânicas, até que, chegamos num consenso.

Contaríamos a saga de um alquimista em busca da vida eterna. Na história, o alquimista Frangoi consegue transitar em 2 mundos paralelos (real e espiritual) e tem de percorrer um longo percurso, resolvendo enigmas e combatendo inimigos pelo caminho. Idéias concretizadas, fomos para o planejamento de o que daria pra fazer nessas 48 horas. Uns achavam que não sairíamos de um concept, outros já achavam que dava pra completar uma fase inteira. E ficou na base do “vamo ver no que vai dar”. Começando as atividades, resolvemos utilizar como ferramentas, o excelente framework MelonJS, já que tínhamos resolvido fazer nosso jogo em HTML5.

Vamos aos rabiscos. Nossos excelentes artistas Rafael Françoi e Carlos Iubel começaram a botar a mão na massa ainda a noite e lá por volta das 01 da manhã do sábado já tinhamos alguns concepts criados.

Realmente fiquei impressionado na primeira vez que já tínhamos alguns concepts do jogo em tão pouco tempo. Eu , Carlos (o programador) e o Pedro já estávamos preparando um esqueleto do código e conseguimos deixar a base do jogo bem sólida pra começar a introduzir a mecância que tínhamos atribuído pro jogo. Nessa hora, o sono ja começou a bater e Carlos pediu um timeout e foi dormir. Passadas mais umas 2 horas (provavelmente já passava das 3 da manhã) foi a vez do Pedro e do Carlos (o artista) de irem tirar uma soneca.

Ficariam de guarda eu e o Rafael que já estava super empolgado criando um concept mais bem feito do velhinho Frangoi. Sábado já estava claro e retomamos as atividades. O dia estava correndo bem e tanto código como arte estavam evoluíndo bem. Conseguimos montar um protótipo jogável ainda no começo da tarde de sábado. Agora era integrar o restante da arte e partir para os testes de balanceamento. Carlos ( o programador ) montou um mapa base e começamos a pensar nos possíveis desafios que o jogo poderia ter (e que o tempo nos permitisse fazer ).

Já era noite e alguns bugs começaram a aparecer. Víamos que a madrugada seria bem longa, pois a maioria desses bugs eram críticos e teriam de ser resolvidos o mais rápido possível. Felizmente, depois de muita pizza e energético tivemos força e conseguimos resolvê-los. Agora era terminar as últimas fases de polishing e partir para o abraço. Já era Domingo, por volta das 12:00 e tínhamos finalizado nosso protótipo do jogo. Como estávamos felizes. Nem o cansaço, dores musculares e outras coisas nocivas atrapalhariam aquela sensação de dever cumprido. Entregamos o jogo antes do prazo e após uma rápida apresentação no auditório da PUC, pudemos dar como finalizada a nossa primeira participação em uma Global Game Jam.

O Fuscshia Team (Nome dado de última hora pra equipe, devido aos nossos copos descartáveis rosas usados jam) nasceu nesse evento e espera dar continuação a esse jogo que até mesmo com um protótipo já conseguiu ficar entre os 3 jogos mais votados da GGJ Curitiba e ser citado no blog e galeria oficial do framework MelonJS, fatos estes que nos deixam cada vez mais motivados a finalizar uma versão jogável do protótipo.

Entrevista com desenvolvedores:

O jogo:

Este texto foi publicado originalmente em 2012 e repostado em homenagem ao nosso querido amigo Pedro Bueno, que infelizmente nos deixou em 2020. Sentiremos sua falta, irmão.

DEV Community: Ellison Leão

Gerando documentação vimdoc de plugins Neovim com Github Actions

Entendendo o fluxo

Preparando seu README

Colocando tudo para funcionar

Links úteis

Meus 10 plugins favoritos para o Neovim em 2022

#10

wbthomason / packer.nvim

A use-package inspired plugin manager for Neovim. Uses native packages, supports Luarocks dependencies, written in Lua, allows for expressive config

packer.nvim

Table of Contents

Features

#9

numToStr / Comment.nvim

🧠 💪 // Smart and powerful comment plugin for neovim. Supports treesitter, dot repeat, left-right/up-down motions, hooks, and more

// Comment.nvim

✨ Features

🚀 Installation

#8

neovim / nvim-lspconfig

Quickstart configs for Nvim LSP

nvim-lspconfig

Important ⚠️

Install

Quickstart

#7

williamboman / nvim-lsp-installer

Further development has moved to https://github.com/williamboman/mason.nvim!

ℹ️ Project status

#6

jose-elias-alvarez / null-ls.nvim

Use Neovim as a language server to inject LSP diagnostics, code actions, and more via Lua.

ARCHIVED

null-ls.nvim

Motivation

Status

#5

nvim-treesitter / nvim-treesitter

Nvim Treesitter configurations and abstraction layer

nvim-treesitter

#4

L3MON4D3 / LuaSnip

Snippet Engine for Neovim written in Lua.

LuaSnip

Features

Drawbacks

Requirements

Setup

Install

#3

hrsh7th / nvim-cmp

A completion plugin for neovim coded in Lua.

nvim-cmp

Readme!

Concept

Setup

Recommended Configuration

#2

nvim-lualine / lualine.nvim

A blazing fast and easy to configure neovim statusline plugin written in pure lua.

lualine.nvim

Contributing

Screenshots

Performance compared to other plugins

#1

nvim-telescope / telescope.nvim

Find, Filter, Preview, Pick. All lua, all the time.

telescope.nvim

What Is Telescope?

Telescope Table of Contents

Getting Started

Required dependencies

Suggested dependencies

Conclusão

Criando plugins Lua para Neovim - Parte 3

A migração

O namespace vim

Nosso arquivo init.lua

Conclusão

O namespace `vim`