Neovim node.js クライアント

CI (node >= 14, Linux/macOS/Windows)	カバレッジ	npm

インストール

「リモートプラグイン」の場合、Nvim Node.js プロバイダ は neovim パッケージがグローバルにインストールされていることを期待します

npm install -g neovim
Copy

または、プラグイン以外の目的で、neovim は他の NPM パッケージと同様に動作します。コピーしてすぐに実行できるクイックスタートの例については、以下を参照してください。

使用方法

関数

neovim パッケージは、以下の関数を提供します

• attach(): 主要なインターフェース。プロセス、ソケット、または書き込み/読み込みストリームのペアを受け取り、nvim プロセスに接続された NeovimClient を返します。
• findNvim(): 現在のシステムで使用可能な nvim バイナリを見つけようとします。

ロギング

• ロード時に、neovim モジュールは console を logger インターフェースに置き換え（「モンキーパッチ」）、console.log は標準出力に書き込む代わりに logger.info を呼び出します（標準出力に書き込むと stdio RPC チャネルが破損するため）。
  • console.log のこのパッチをスキップするには、カスタム logger を attach() に渡します。
  • いずれの場合も、console ロギング関数ではなく、attach() によって返される NeovimClient から利用可能な logger を使用することをお勧めします。
• $NVIM_NODE_LOG_FILE 環境変数を設定して、ログをファイルにも書き込みます。
• $ALLOW_CONSOLE 環境変数を設定して、ログを標準出力にも書き込みます。 これは、標準出力に書き込まれたログは無効な RPC メッセージであるため、（stdio）RPC チャネルを破損します。

クイックスタート: Nvim に接続する

以下は、完全な動作例です。

1. neovim パッケージを任意のディレクトリに*ローカル*にインストールします（つまり、-g なしでインストールします。スクリプトが*グローバル*にインストールされたパッケージをインポートすると、Node は ERR_MODULE_NOT_FOUND をスローします）。

   npm install neovim
   Copy

2. 以下のスクリプトを demo.mjs ファイルに貼り付けて実行します！

   ALLOW_CONSOLE=1 node demo.mjs
   Copy

   • ログは通常標準出力に出力されないため、$ALLOW_CONSOLE 環境変数を設定する必要があります。
     • 注: $ALLOW_CONSOLE はデモ目的のみです。標準出力にログを書き込むと RPC チャネルが破損するため、リモートプラグインや stdio が RPC チャネルである場合は使用できません。
   • スクリプト

   import * as child_process from 'node:child_process'
   import * as assert from 'node:assert'
   import { attach, findNvim } from 'neovim'
   
   // Find `nvim` on the system and open a channel to it.
   (async function() {
     const found = findNvim({ orderBy: 'desc', minVersion: '0.9.0' })
     console.log(found);
     const nvim_proc = child_process.spawn(found.matches[0].path, ['--clean', '--embed'], {});
     const nvim = attach({ proc: nvim_proc });
   
     nvim.command('vsp | vsp | vsp');
   
     const windows = await nvim.windows;
     assert.deepStrictEqual(windows.length, 4);
     assert.ok(windows[0] instanceof nvim.Window);
   
     nvim.window = windows[2];
     const win = await nvim.window;
     assert.ok(win.id !== windows[0].id);
     assert.deepStrictEqual(win.id, windows[2].id);
   
     const buf = await nvim.buffer;
     assert.ok(buf instanceof nvim.Buffer);
     const lines = await buf.lines;
     assert.deepStrictEqual(lines, []);
   
     await buf.replace(['line1', 'line2'], 0);
     const newLines = await buf.lines;
     assert.deepStrictEqual(newLines, ['line1', 'line2']);
   
     if (nvim_proc.disconnect) {
       nvim_proc.disconnect();
     }
     nvim.quit();
     while (nvim_proc.exitCode === null) {
       await new Promise(resolve => setTimeout(resolve, 100))
       console.log('waiting for Nvim (pid %d) to exit', nvim_proc.pid);
     }
     console.log('Nvim exit code: %d', nvim_proc.exitCode);
   })();
   Copy

リモートプラグインを作成する

Neovim は、Nvim API クライアントとして実装されたプラグインである リモートプラグイン をサポートしています。このパッケージには、「API クライアント」（nvim と通信する）と「リモートプラグインホスト」（Nvim node.js リモートプラグインを検出して実行する）の両方が含まれています。

リモートプラグインは、Nvim の 'runtimepath' 上の rplugin/node/ ディレクトリ内のファイルまたはフォルダとして定義できます。プラグインがフォルダの場合、package.json の main スクリプトがロードされます。

プラグインは、唯一のパラメータとして NvimPlugin オブジェクトを受け取る関数をエクスポートする必要があります。その後、NvimPlugin オブジェクトのメソッドを呼び出すことによって、autocmd、コマンド、および関数を登録できます。 Nvim は実際に使用することなくプラグインに関する情報を収集しているだけかもしれないため、この段階では、重い初期化や非同期関数は避けてください。 代わりに、処理を開始する前に、autocmd、コマンド、または関数のいずれかが呼び出されるのを待ちます。

リモートプラグインの例

リモートプラグインの例については、examples/ を参照してください。

リモートプラグイン API

  NvimPlugin.nvim
Copy

これは、プラグインから nvim にコマンドを送信するために使用できる nvim api オブジェクトです。

  NvimPlugin.setOptions(options: NvimPluginOptions);

  interface NvimPluginOptions {
    dev?: boolean;
    alwaysInit?: boolean;
  }
Copy

プラグインを開発モードに設定します。これにより、モジュールは呼び出されるたびにリロードされます。 alwaysInit は、常にプラグインの再インスタンス化を試みます。たとえば、プラグインのコマンドが呼び出されるたびに、プラグインクラスは常に呼び出されます。

  NvimPlugin.registerAutocmd(name: string, fn: Function, options: AutocmdOptions): void;
  NvimPlugin.registerAutocmd(name: string, fn: [any, Function], options: AutocmdOptions): void;

  interface AutocmdOptions {
    pattern: string;  // See `:help autocmd-pattern`.
    eval?: string;    // Vimscript expression evaluated by the Nvim peer.
    sync?: boolean;   // Force blocking (non-async) behavior.
  }
Copy

イベント name の autocmd を登録し、options を使用して関数 fn を呼び出します。パターンは唯一の必須オプションです。オブジェクトのメソッドを呼び出す場合は、fn を [object, object.method] の配列として渡すことができます。

デフォルトでは、autocmd、コマンド、および関数はすべて非同期として扱われ、Promises を返す必要があります（または async 関数である必要があります）。

  NvimPlugin.registerCommand(name: string, fn: Function, options?: CommandOptions): void;
  NvimPlugin.registerCommand(name: string, fn: [any, Function], options?: CommandOptions): void;

  interface CommandOptions {
    sync?: boolean;   // Force blocking (non-async) behavior.
    range?: string;   // See `:help :range`.
    nargs?: string;   // See `:help :command-nargs`.
  }
Copy

name という名前のコマンドを登録し、options を使用して関数 fn を呼び出します。これは、ノーマルモードで :name と入力することで nvim から呼び出されます。

  NvimPlugin.registerFunction(name: string, fn: Function, options?: NvimFunctionOptions): void;
  NvimPlugin.registerFunction(name: string, fn: [any, Function], options?: NvimFunctionOptions): void;

  interface NvimFunctionOptions {
    sync?: boolean;   // Force blocking (non-async) behavior.
    range?: string;   // See `:help :range`.
    eval?: string;    // Vimscript expression evaluated by the Nvim peer.
  }
Copy

name という名前の関数を登録し、options を使用して関数 fn を呼び出します。これは、ノーマルモードで :call name() などと入力することで nvim から呼び出されます。

デバッグ/トラブルシューティング

デバッグとロギングの設定のために、neovim パッケージ（または nvim 自体、注記がある場合）で使用される以下の環境変数を設定できます

• NVIM_NODE_HOST_DEBUG: neovim-client-host を --inspect-brk で呼び出すノードプロセスを生成するため、デバッガを使用できます。これを Node Inspector Manager Chrome プラグイン と組み合わせて使用​​します
• ロギング: ロギングは、logger モジュールを介して winston を使用して行われます。このパッケージは console をこのインターフェースに置き換えます。
  • NVIM_NODE_LOG_LEVEL: winston のログレベルを設定します。デフォルトは debug です。使用可能なレベル: { error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5 }
  • NVIM_NODE_LOG_FILE: ログファイルのパスを設定します。
• ノード REPL を介した使用法
  • NVIM_LISTEN_ADDRESS:
    1. 既知のアドレスで Nvim を起動します（または、実行中のインスタンスの $NVIM_LISTEN_ADDRESS を使用します）

       $ NVIM_LISTEN_ADDRESS=/tmp/nvim nvim
       Copy

    2. 別のターミナルで、ノード REPL を Nvim に接続します

       // `scripts/nvim` will detect if `NVIM_LISTEN_ADDRESS` is set and use that unix socket
       // Otherwise will create an embedded `nvim` instance
       require('neovim/scripts/nvim').then((nvim) => {
         nvim.command('vsp');
       });
       Copy

テストと scripts で、さらに例を参照してください。

開発

リポジトリのクローンを作成した後、npm install を実行して開発依存関係をインストールします。メインの neovim ライブラリは packages/neovim にあります。

テストを実行する

npm run build && NVIM_NODE_LOG_FILE=log npm run test

保守

リリース

neovim NPM パッケージ のメンテナのみがリリースを公開できます。リリースを公開するには、次の手順に従います

1. CHANGELOG.md を更新します。
2. バージョンを更新します。パッケージをビルドして公開します。リリースにタグを付けてプッシュします。

   # Choose major/minor/patch as needed.
   npm version --no-git-tag-version patch
   npm version -w packages/neovim/ patch
   git add package*.json packages/neovim/package.json
   git commit -m 'release'
   # Note: this copies the top-level README.md/CHANGELOG.md to packages/neovim/.
   npm run publish:neovim
   export _VERSION=$(grep -o 'version": "[^"]\+' packages/neovim/package.json | sed 's/.*"//')
   git tag "v${_VERSION}"
   git push --tags
   git push
   Copy

3. リリース後のタスク
   • CHANGELOG.md にスタブを追加します。
   • バンプしてコミットします。

     npm version --no-git-tag-version prerelease --preid dev
     npm version -w packages/neovim/ --no-git-tag-version prerelease --preid dev
     git add package*.json packages/neovim/package.json
     git commit -m bump
     git push
     Copy

ドキュメント Web サイトの再生成

ドキュメント Web サイトは現在自動化されていません。再生成するには、次の手順に従います

npm run doc -w packages/neovim
git checkout gh-pages
mv -f packages/neovim/doc/assets/* assets/
mv -f packages/neovim/doc/classes/* classes/
mv -f packages/neovim/doc/functions/* functions/
mv -f packages/neovim/doc/types/* types/
mv packages/neovim/doc/* .
rm -r packages/
git add *
git commit -m 'publish docs'
git push origin HEAD:gh-pages
Copy

貢献者

• リライトについて @billyvg
• TypeScript リライトについて @mhartington
• npm パッケージリポジトリ neovim の移行について @fritzy！
• 元の node-client の作業について @rhysd、@tarruda、@nhynes
• Neovim メンテナー @justinmk