@cosense-toolbox/parser

v0.1.0-beta.7

Published

2 days ago

Cosense (Scrapbox) notation parser — every node carries its source position. Zero runtime deps except effect.

0High
0Medium
0Low

qaynam

cosense scrapbox parser ast syntax effect

@cosense-toolbox/parser

Cosense (旧 Scrapbox) の記法を、位置情報つきの AST に変換する。

ドキュメント → https://cosense-toolbox.qaynam.dev/parser/

依存は effect だけ。DOM も Node の API も使わないので、ブラウザでも Node でも Workers でも動く
どのノードも元のテキストの何行目の何文字目から始まるかを持つので、エディタの色付けやカーソル位置の判定に使える
AST はメソッドを持たないただのオブジェクト。JSON.stringify して保存しておき、あとで読み直せる
記法そのものを増やせる。プロジェクト固有の書きかたも元からある記法と同じように扱える
パースだけなら gzip 約 10 KB。HTML 変換や走査は別の import 元なので、使わなければバンドルに入らない

beta：公開 API はまだ変わりうる。安定するまではバージョンを固定して使うほうが安全。

0.1.0-beta.7 の変更

動画・音声・埋め込みのノードを足した。どれも Cosense Web がパースの段階で読み分けているもので、今までは外部リンクになっていた。
- video: [https://…/a.mp4] (拡張子は mp4 / webm / mov)。[[…]] で大きい動画 (large)、 URL を 2 つ並べるとリンク付き動画 (link) になる。単独の動画 URL にはクエリを付けられない。
- audio: [https://…/a.mp3] (拡張子は wav / mp3 / weba / ogg / aac)。前後に文字を書くと、その文字が label になる。
- embed: YouTube / Vimeo / Spotify / anchor.fm の URL。provider と、サービスの中での id (と kind) を持つ。 <iframe> に入れる URL は asEmbedSrc で作る。
toHtml / toHast は、動画を <video>、音声を <audio>、埋め込みを <iframe> にする。 class 名は classNames の video / audio / embed で変えられる。
地図のノード location を足した。[N35.68,E139.76] (ズームは ,Z14) で、座標の前後に書いた文字が label になる。緯度と経度は数値で、南緯と西経は負の数になる。Google マップの URL は asMapUrl で作り、toHtml はそこへのリンクを出す (class 名は classNames の location)。
Cosense Web が埋め込まないサービスは、拡張の bracketRules から独自の provider の embed を返せば足せる。既定の toHtml はプレーヤーの URL を知らない埋め込みを外部リンクとして出すので、見た目は handlers か extensions で決める。

0.1.0-beta.6 の変更

インラインコードが始まる括弧を、記法として読まないようにした。Cosense Web はコードを括弧より先に読むので、 [* 太字の `code` です] は装飾にならず、括弧はそのままの文字、`code` はインラインコードになる。数式 ([$ …]) も同じで、 [$ a] `` は数式にならない。閉じないバッククォートは括弧を妨げない。
コマンドの行を Cosense Web に合わせた。字下げの後が $ か % と空白で、その後に何かある行だけがコマンドになる (monospace: true)。コマンドの行は記法を読まず、children は書いたままの文字の text 1 つになる。 $aa のように空白が無い行と、引用の行 (> $ x) はコマンドにならない。 toHtml / toHast は、Cosense Web と同じくコマンドの行を記号・空白・コマンドの要素に分けて出す (<span class="prefix">$</span><span class="space"> </span><span class="command">ls</span>)。 class 名は classNames の commandPrefix / commandSpace / command で変えられる。

0.1.0-beta.5 の変更

タイトル行の記法を読まないようにした。Cosense Web と同じく、[x] も #tag も書いたままの文字になる。 TitleBlock の形は変わらず、children が書いたままの文字の text 1 つになる。

0.1.0-beta.3 の変更

Cosense の文字装飾の記号 !"#%&'()*+,-./{|}<>_~= からなる並びを、拡張なしですべて装飾として読むようにした。 Cosense Web と同じ読み方で、[! 注意] は内部リンクではなく markers: ['!'] の装飾になる。見た目 (bold などのフラグ) が付くのは今までどおり * / - _ だけ。ほかの記号の見た目は CSS で付ける。
customDecorations を削除した。集合の中の記号は既定で読むので、この拡張で足せるのは Cosense Web が装飾にしない記号だけになり、Web 版と違う AST を作るため。渡していた箇所は消すだけでよい。

0.1.0-beta.2 の変更

記法の拡張 (InlineConstruct / BracketRule) は、成立しなければ null を返す普通の関数になった。これまでは effect の Option を返す必要があり、拡張を書くのに effect が要った。 Option.none() は null に、Option.some(x) は x に書き換える。
拡張のルールに渡る文脈から bracketRules を外した。拡張から使う場面が無く、中の型が漏れていたため。

0.1.0-beta.1 の変更

beta.0 から上げるときは次の 2 点に注意。

サブパス ./plugin を ./extensions に改名した。渡すものが Extension でオプション名も extensions なのに、置き場所だけ別の語彙だったため。コンパイラを書くための型 (NodeHandlers 等) は ./compile にある。
decoration ノードに markers を足した (必須)。書かれた装飾記号が出現順・重複なしで入る。toHtml はこれを deco-* のような class として出す。装飾ノードを自分で組み立てている拡張は追随が要る。

インストール

npm i @cosense-toolbox/parser

既定の見た目が要るなら @cosense-toolbox/style を別途入れる。

使ってみる

import { parse } from "@cosense-toolbox/parser"
import { collectLinks } from "@cosense-toolbox/parser/utils"
import { toHtml } from "@cosense-toolbox/parser/html"

const page = parse(`今日のメモ
[プロジェクトA] の進捗を確認する
#あとで読む`)

collectLinks(page) // → ['プロジェクトA', 'あとで読む']
toHtml(page) // → '<div class="page"><h1 class="title">今日のメモ</h1>…'

API

モジュールごとに export が分かれている。使うものだけ import すればよい。

parse はページ全体を読む。1 行目はタイトルで、Cosense Web と同じく記法を読まない。記法を読みたい文字列がページでないなら、本文の 1 行は parseLine、文章の断片は tokenizeInline で読む。

各 API の詳細はドキュメントにある。

互換性の方針

ノード型は minor で増えうるので、switch (node.type) には default を置いておく。

開発

規約は CLAUDE.md にある。

bun install
bun run test
bun run build

ライセンス

MIT。

このパッケージは Cosense (Scrapbox) の記法を解釈する非公式の実装である。開発元である Helpfeel 社とは関係がなく、公認も受けていない。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@cosense-toolbox/parser

0.1.0-beta.7 の変更

0.1.0-beta.6 の変更

0.1.0-beta.5 の変更

0.1.0-beta.3 の変更

0.1.0-beta.2 の変更

0.1.0-beta.1 の変更

インストール

使ってみる

API

互換性の方針

開発

ライセンス