DEV Community: hikerpig

为 Pintora 写一个 VSCode 插件

hikerpig — Sat, 15 Jan 2022 00:00:00 +0000

Pintora 是我最近在折腾的一个开源项目，类似于 Mermaid.js 和 PlantUML，由文字生成图表。

光是有在线编辑器还不太够，花了几天折腾了一个 VSCode 插件 - pintora-vscode，支持语法高亮、实时预览和导出图片。由于有上面两个项目的开源的 VSCode 插件珠玉在前，实现起来不难，也很有趣。

功能实现

语法高亮

pintora 内置了几种类型的图表，语法几乎无相同之处，通过首单词来决定图表类型。首先熟读官方的代码高亮指南 Syntax Highlight Guide，接着跟着 vscode-mermaid-syntax-highlight 的源码结构照猫画虎。然后和 TextMate 的语法规则搏斗一下就行。

看 package.json 中关于语法的 contributes:

"languages": [
  {
    "id": "pintora",
    "extensions": [
      ".pintora"
    ],
    "configuration": "./language-configuration.json"
  }
],
"grammars": [
  {
    "language": "pintora",
    "scopeName": "source.pintora",
    "path": "./out/pintora.tmLanguage.json"
  },
  {
    "scopeName": "source.pintora",
    "path": "./out/pintora.tmLanguage.json",
    "injectTo": [
      "text.html.markdown"
    ],
    "embeddedLanguages": {
      "meta.embedded.block.pintora": "pintora"
    }
  }

该插件提供了两种情形下的代码高亮

pintora 语言文件，由 languages 处定义，后缀为 .pintora 的文件
markdown 文件中的 pintora 块（由 embeddedLanguages 指定），将其也认为是 pintora 语言。

由于这个语言不断会有新的图表类型加进来，同时它不是标准的编程语言，而是类似于标记语言的 DSL，匹配规则比较长，因此采用了 yaml 来写语法配置 pintora.tmLanguage.yaml，使用 yaml-import 包来将其转化为最终的 json 文件。

---
fileTypes: []
injectionSelector: L:markup.fenced_code.block.markdown
patterns:
  - include: '#pintora-code-block'
  - include: '#pintora'
repository:
  pintora-code-block:
    begin: (?<=[`~])pintora(\s+[^`~]*)?$
    end: (^|\G)(?=\s*[`~]{3,}\s*$)
    patterns:
      - include: '#pintora'
  pintora:
    patterns: !!import/deep
      - diagrams/
  'component__element': !!import/single repository/component__element.yaml
  'activity__element': !!import/single repository/activity__element.yaml
  'style__clause': !!import/single repository/style__clause.yaml
  'style__part': !!import/single repository/style__part.yaml
scopeName: source.pintora

!!import/deep 和 !!import/single 都是 yaml-import 支持的指令，分别指引入一个目录内所有文件和引入一个文件，这样子不同图表的语法规则可以放在各自的文件里维护，看起来清晰简洁。

以下以组件图 Component Diagram 为例。

以 componentDiagram 开头的，进入组件图的匹配规则里
patterns 里只有两个 includes，主要是 component__element 这个在上面配置中的 repository 中声明的可重用语法规则，是因为组件图的语法支持多层嵌套，嵌套内外的语法相同，这样一个分形的结构，需要在顶层的 repository 里声明好，才能复用。

- comment: Component Diagram
  begin: \b(componentDiagram)
  beginCaptures:
    '1':
      name: keyword.control.pintora

  patterns:
    - include: '#component__element'
    - include: '#style__clause'

  end: (^|\G)(?=\s*[`~]{3,}\s*$)

下面再给出 component__element.yaml 的局部示意。

patterns:
  - comment: 'package'
    begin: !regex |-
      (package|node|folder|frame|cloud|database|rectangle|component)\s+"([^"]+)"
      \s*({)
    beginCaptures:
      '1':
        name: keyword.control.pintora
      '2':
        name: string
      '3':
        name: punctuation.bracket.open.pintora
    end: '(})'
    endCaptures:
      '1':
        name: punctuation.bracket.close.pintora
    patterns:
      - include: '#component__element'

在 package这个语法规则中，花括号中的内容，会通过 - include: '#component__element' 继续使用此语法规则来解析。

待解析的语言示意如下，详细语法可见组件图说明

database "MySql" {
  folder "This is my folder" {
    [Folder 3]
  }
  frame "Foo" {
    [Frame 4]
  }
}

在 Webview 中实时预览

当打开一个 .pintora 文件，并执行了 Preview Pintora Diagram command 时，会在右侧新建一个新的 Webview，在里面展示当前文件所生成的图表。

由于 pintora 具有在浏览器环境和 Node.js 环境下执行的能力，比起 PlantUML 这样的 Java 程序，实时预览对 Web 更加友好，在 Webview 中展示，是再合适不过的了。能根据用户对源文件的更改，实时更新右侧预览效果，而且此过程中不会写临时文件到磁盘。

在内置 Markdown 预览内展示 pintora 代码块

参考了 vstirbu/vscode-mermaid-preview 插件才发现 VSCode 的内置 markdown 预览也是能支持扩展的，官方文档在 Markdown Extension，也将 vscode-mermaid-preview 作为一个推荐例子。

下面是 pintora-vscode 预览 markdown 文件的效果。

内置 Markdown 预览界面也是一个 Webview，使用 markdown-it 作为渲染库，因此需要扩展的话，也是基于 markdown-it 的插件来实现的。

contributes 的写法如下：

    "markdown.markdownItPlugins": true,
    "markdown.previewScripts": [
      "./out/markdown-script.js"
    ],

markdown.markdownItPlugins，表示 pintora 插件会提供 markdown-it 的插件，在 pintora extension 的隔离环境中运行。通过这种方式提供的插件，可以通过 vscode 接口拿到一些配置，生成 html 的时候可以通过 data- 属性带上，之后在 Webview 里可以根据这些属性来得到 pintora 主题和渲染器(renderer)等用户设置。注意此时生成的 html 里会保留 pintora DSL 的文本，转成图表的工作需要在 Webview 中进行。
markdown.previewScripts，在预览的 Webview 里插入可执行的脚本，这里主要是使用 @pintora/standalone 处理 pintora 文本，生成 svg 或 canvas 展示在页面上，这个会是最终用户看到的样子。

导出图表图片

这部分就比较简单，就是使用 require('child_process').spawn 新建一个子进程，使用 node 执行 @pintora/cli （pintora 本身提供的 node 命令行程序）即可。

之所以采用子进程而不是在 extension 环境下直接 import { render } from '@pintora/cli' 来渲染，是因为使用 rollup 打包 node-canvas 的时候报错了（其实好像也是能实现的，见 How to pack canvas.node by rollup? · Issue #1504 · Automattic/node-canvas）。之后可以看一下能不能集成进来，目前看起来效果其实也挺好的，而且子进程的方式倒是也有优势，执行不会阻塞插件主线程。

参考

顺藤摸瓜可以看到一些优秀的工具。

万物皆可 fzf

hikerpig — Fri, 08 Jan 2021 00:00:00 +0000

fzf 是一个速度和适用范围都极好的工具，借助 UNIX 管道，可以接入日常几乎所有终端 CLI 操作中，对所有的 list 都能有美好的可交互式模糊过滤体验。

It's an interactive Unix filter for command-line that can be used with any list; files, command history, processes, hostnames, bookmarks, git commits, etc.

一些技巧

使用 `-m` 参数支持多选

cat $(fzf -m)

然后就可以实用 tab 或者 shift+tab 实现多选。在使用 cat/rm 等命令时很好用。

使用 `**` 作为 trigger

unset **<Tab>
unalias **<Tab>

善用 `--preview`

交互式地选择 git branch。

# git interactive checkout
gcb() {
  result=$(git branch -a --color=always | grep -v '/HEAD\s' | sort |
    fzf --height 50% --border --ansi --tac --preview-window right:70% \
      --preview 'git log --oneline --graph --date=short --pretty="format:%C(auto)%cd %h%d %s" $(sed s/^..// <<< {} | cut -d" " -f1) | head -'$LINES |
    sed 's/^..//' | cut -d' ' -f1)

  if [[$result != ""]]; then
    if [[$result == remotes/*]]; then
      git checkout --track $(echo $result | sed 's#remotes/##')
    else
      git checkout "$result"
    fi
  fi
}

实用脚本

fzf-tab 替换 zsh 的默认补全选择菜单

Aloxaf/fzf-tab ，如其自我介绍

Replace zsh's default completion selection menu with fzf!

这个脚本可以将 zsh 的默认 completion 结果转给 fzf 显示，让你在选择补全结果的时候获得 fzf 加持。

若使用 zimfw 安装，在 .zimrc 内添加:

zmodule Aloxaf/fzf-tab

fzf-fasd, 配合 fasd 可代替 `z`

wookayin/fzf-fasd: 🌸 fzf + fasd integration ，实现了类似 z 的效果， z<Tab> 后使用 fzf 选择最近进入过的目录。

其他零零散散

bindkey | fzf # 搜索当前 shell 里所有绑定了的快捷键

fzf --preview "bat {} --color=always" # 快速预览当前以及子目录下文件内容，不在乎颜色的话 bat 可以换成 cat

cd $(find . -type d | fzf) # 可选择进入某个深层子目录
cd $(fd --type directory | fzf) # 与上面类似，不过使用更便捷的 fd

参考文章

使用 zimfw 作为 zsh 配置框架

hikerpig — Wed, 14 Oct 2020 00:00:00 +0000

之前使用 oh-my-zsh 的自带 git/nvm 等插件有时候有性能问题，同时据说其框架本身相比其他一些主打速度的配置框架(prezto/zimfw 等)也会慢一点。

稍微折腾了一下，使用 zimfw 作为 zsh 配置框架，它在速度和可配置性间达到了很好的平衡。

个人切换后，试了下跑 zprof，启动时间只有原先的一半，度量方式参考 Profiling zsh startup time。

插件加载

用上自带的模块和zsh-users里一些优秀的插件，就已经有很好的表现，其中 zsh-users/zsh-autosuggestions 和 zsh-users/zsh-syntax-highlighting 能让 zsh 也有类似于 fish 一样友好的代码高亮反馈和输入自动补全功能。zimfw 比较友好的一点就在于默认配置（使用其提供的安装脚本）里给出的组合就已经很棒了。

添加插件的方式与 oh-my-zsh 不太一样，后者需要把插件添加到指定的 plugins 目录（一般为 clone repo 或者拷贝文件），然后在 .zshrc 文件里 plugins=() 数组里添加插件名。

而 zimfw 的方式则稍微方便一点，除了类似后者的方式外，还可以不用手动操作目录而是在 .zimrc 文件中添加模块名（一般为 github 上的 user/repo 名），可在 awesome-zsh-plugins 里寻找合适插件，多数与配置框架无关(可以不局限在 oh-my-zsh 提供的插件目录里)。

修改配置文件后，使用命令 zimfw install 下载并编译插件(会使用 zsh builtin 的 zcompile 将 .zsh 文件编译为 .zwc 字节码，提高下次加载的速度)，打开新 shell 时新插件生效。

外观和主题

zimfw 的主题远不如 oh-my-zsh 丰富，自己的 gallery 里都是偏向极简的风格，不过我们可以自己找一些成熟的主题 powerlevel10k 使用，带有问答式的新手配置指导，功能丰富，推荐使用。

一些配置

~/.zimrc

# Start configuration added by Zim install {{{
# -------
# Modules
# -------
# Sets sane Zsh built-in environment options.
zmodule environment
# Applies correct bindkeys for input events.
zmodule input
# Sets a custom terminal title.
zmodule termtitle
# Utility aliases and functions. Adds colour to ls, grep and less.
zmodule utility
zmodule directory

#
# Prompt
#
# Exposes git repository status information to prompts.
zmodule git-info

# Theme
zmodule romkatv/powerlevel10k

# Additional completion definitions for Zsh.
zmodule zsh-users/zsh-completions
# Enables and configures smart and extensive tab completion.
# completion must be sourced after zsh-users/zsh-completions
zmodule completion
# Fish-like autosuggestions for Zsh.
zmodule zsh-users/zsh-autosuggestions
# Fish-like syntax highlighting for Zsh.
# zsh-users/zsh-syntax-highlighting must be sourced after completion
zmodule zsh-users/zsh-syntax-highlighting
# Fish-like history search (up arrow) for Zsh.
# zsh-users/zsh-history-substring-search must be sourced after zsh-users/zsh-syntax-highlighting
zmodule zsh-users/zsh-history-substring-search
# }}} End configuration added by Zim install

# Custom 个人推荐的插件
zmodule DarrinTisdale/zsh-aliases-exa
zmodule zsh-users/zaw
zmodule wookayin/fzf-fasd

介绍一些程序和插件:

快速跳转工具--FASD 简单介绍

参考文章

Toc Bar, table of content for dev.to, finally.

hikerpig — Sun, 05 Jul 2020 12:00:53 +0000

Toc Bar is a userscript I wrote to add floating widget displaying table of content of current page.

Currently only tailored for some personal most-visited sites, including dev.to .

✨Features

Use tocbot for toc generation.
For some sites, there are no ids on header elements so it would be impossible to navigate by clicking the toc link. Toc Bar will generate ids - which are derived from a simple hash of the header textContent, and prefixed with tocbar- - for these headers.
A toggle button is offered, if you don't want toc bar to cover current page content.
For some sites in SPA mode, if you navigate to another article, there is no easy way detecting url change in userscript, so I add a refresh button to refresh TOC contents.

DEV Community: hikerpig

为 Pintora 写一个 VSCode 插件

功能实现

语法高亮

在 Webview 中实时预览

在内置 Markdown 预览内展示 pintora 代码块

导出图表图片

参考

万物皆可 fzf

一些技巧

使用 -m 参数支持多选

使用 ** 作为 trigger

善用 --preview

实用脚本

fzf-tab 替换 zsh 的默认补全选择菜单

fzf-fasd, 配合 fasd 可代替 z

其他零零散散

参考文章

使用 zimfw 作为 zsh 配置框架

插件加载

外观和主题

一些配置

参考文章

Toc Bar, table of content for dev.to, finally.

✨Features

Screenshots

使用 `-m` 参数支持多选

使用 `**` 作为 trigger

善用 `--preview`

fzf-fasd, 配合 fasd 可代替 `z`