道具とエラー — Ponte

REFERENCE

道具とエラー

このページは Ponte の実装から作っています。道具の例はすべてテストで動かしているため、ここに書いてある例は実際に動きます。

コマンド

python -m ponte か、pip install -e . のあとは ponte だけで使えます。

コマンドすること
ponte check spec決めてないことを探す
--publish 公開する時の検査
--save-shape 通ったら thing の形を残す
--json 結果を JSON で出す(エディタや AI のループ向け)
--watch 保存するたびに流す(Ctrl+C で止める)
ponte test specrule の example を全部流す
--strict 穴(example で確かめていない所)があれば失敗にする
--json 結果を JSON で出す
ponte fill specby ai の action の中身をAIに書かせる(example と never を通るまで)
--action この action だけ
--ai anthropic(ANTHROPIC_API_KEY が要る)か file:返事.md
--again もう中身があっても書き直す
ponte fmt spec…誰が書いても同じ見た目に整える
--check 書き換えず、整形が要るかだけ見る
ponte build specspec と中身と実行エンジンを1つの .pyz にまとめる
ponte run spec動かす(ブラウザで開く)
--data データを残すファイル(既定は <spec>.data.jsonl)
--login 名前と合言葉でログインする(登録は ponte user add)
--signup --login に加えて、画面から誰でも登録できる
--reload spec を書き直したら読み直して、画面も読み直す(作っている間に)
ponte user add|remove|list spec [name]ログインする人(例: user add spec/lend.ponte taro)
ponte new nameひな形から新しいアプリを作る
--from 見本のアプリから始める(todo / lend / kakeibo)
ponte guideAIに渡す書き方の説明を出す(実装から作る)
--spec 仕様書 10章の道具の表を書き直す
--rules rule の書き方(when / do / 値)を出す
ponte role spec name role最初の管理者を決める(例: role spec/lend.ponte taro admin)
--data データのファイル(既定は <spec>.data.jsonl)
ponte data export|import|compact spec [thing] [file]保存したデータを書き出す(export)・CSV から入れる(import)・詰める(compact)
--as import: 作った人(User を指す項目の既定)
--data データのファイル(既定は <spec>.data.jsonl)
--csv export を thing ごとの CSV にする
ponte doc spec決めごとを、コードを読まない人にも読める1枚の HTML に
--out 書き出す先(既定は <spec>.html)
ponte lspエディタ向けの言語サーバー(標準入出力。エラー・説明・補い)
ponte explain [code]エラーの意味と直し方(例: explain E32。無しなら一覧)
ponte ir speccheck を通った仕様を、下の層の言語に渡す中間の形(JSON)にする
-o 書き出すファイル(省略時は画面に出す)
--cases 共通テスト(example)だけを出す
ponte train specmodel を、保存したレコード(か --csv)から学ぶ
--model この model だけ学ぶ
--data レコードのファイル(省略時はアプリのデータ)
--csv CSV から学ぶ(1行目は項目の名前)
ponte job spec [name]job を走らせ、報告された事実を約束と照合する
ponte conform irIR の共通テストを、基準の実装(Python)で流す

rule の書き方

rule は、きっかけ(when)とやること(do)の一組です。

when(きっかけ)

when に書けるのは出来事だけです。状態(「期限が近い」など)は where か list で絞ります。

書き方意味
every day at 21:00 / every monday at 9:00毎日・毎週その時刻に
every month on 1 at 9:00 / every month on last at 18:00毎月その日のその時刻に(last は月末。31 のように無い日の月は月末に)
at 9/24 23:00その日時に1回
user says "submitted {company}"人が言った({…} は変数になる)
user taps 名前 on 画面か thingボタンを押した(押された1件が this)
Loan is created箱ができた(this はその箱)
Loan moves to returned状態が動いた
Loan is removed箱が消えた
Gmail gives new messageconnect の gives が届いた(入力は届いた中身)

書き方は決まっているものの、まだ動かないもの(check でエラーになります): user holds 名前 / user swipes 名前 left / user drags 名前 to 名前 / user types in 名前 / user opens 画面 / user leaves 画面

do(すること)

1つの rule ですることは1つだけです。2つあるときは rule を分け、relate の then でつなぎます。

書き方意味
notify me "..." / notify borrower "..."通知する(宛先は me か、人を指す項目。{項目} は中身に)
notify owner each of DueSoon一覧のそれぞれを、その箱の人へ
move this to 状態押された1件の状態を動かす(flow の矢印だけ)
move 項目 of this to 状態this が指している箱を動かす
move 箱 where 条件 to 状態絞った箱を全部動かす
remove this押された1件を消す(gone の通り)
go 画面 / go 画面 with this画面を移る
create 箱(下に「項目 値」)箱を作る
set 項目 to 値項目を書き換える(状態は move で)
action名 with 項目action を呼ぶ。入力は this の項目

値

create の「項目 値」と set に書けるものです。

書き方意味
this押された1件
me押した人
result直前の action の答え(relate の then で渡る。答えが無ければ、この rule は静かに起きない)
項目 of thisthis の項目の値
"文字"そのままの値
{名前}when の {…} で取り出した値
7 days from now今から(年まで入れて保存。推測しない)
状態の名前・数そのまま

do で使える道具

action の中身に書ける道具は、ここに載せたものですべてです。ここにないものを書くとエラーになります。

文字

書き方意味例(テストで動かしています)
normalize X数字、英字、記号の全角を半角に変換normalize t t = '12/3' → 12/3
trim X前後の空白を削除trim t t = ' a ' → a
lower X / upper X小文字に変換 / 大文字に変換lower t t = 'AbC' → abc
split X by ","区切り文字で分割して集まりに変換split t by "," t = 'a,b' → ['a', 'b']
join X by ","集まりを連結して文字に変換join split t by "," by "-" t = 'a,b' → a-b
replace "a" with "b" in X文字の置き換えreplace "," with "" in t t = '1,980' → 1980
X contains "a"文字を含むかどうか(答えは yes / no で、match で分岐)t contains "締切" t = '締切は明日' → yes
X starts with "a"指定の文字で始まるかどうか(答えは yes / no)t starts with "Re:" t = 'Fw: 件名' → no

形

書き方意味例(テストで動かしています)
find all 形 in Xshape に当たった部分すべてを集まりで返すcount of find all D in t t = '1 と 22' → 2
名前 of X当たりのうち、shape で名前を付けた部分n of first of find all D in t t = 'a12b' → 12
text of X当たった部分の文字text of last of find all D in t t = '1 と 22' → 22

集まり

書き方意味例(テストで動かしています)
count of X要素の数(length of X と同じ)count of split t by "," t = 'a,b,c' → 3
first of X / last of X最初の要素 / 最後の要素(空のときは停止するため、先に count で分岐)last of split t by "," t = 'a,b,c' → c
["a", "b", "c"]その場で作るリスト(do の中だけで使用し、保存するデータは thing に書く)count of ["朝", "昼", "夜"] t = '' → 3
X contains "a"(リスト)リストにその値が含まれるかどうか(答えは yes / no)["朝", "昼", "夜"] contains "昼" t = '' → yes
sort X / sort X desc並べ替え(数は数値の順)/ 逆順に並べ替えsort split t by "," t = 'b,a,c' → ['a', 'b', 'c']
take 3 of X先頭から3つを取得take 2 of split t by "," t = 'a,b,c' → ['a', 'b']
unique of X重複の削除(順番は維持)unique of split t by "," t = 'a,b,a' → ['a', 'b']

数

書き方意味例(テストで動かしています)
number of X文字を数に変換(1,980 や 1.5 にも対応し、読めないときは停止)number of t t = '1,980' → 1980
a + b / a - b足し算 / 引き算(結合の優先順位は最も低い)count of split t by "," + 10 t = 'a,b' → 12
sum of X / min of X / max of X合計 / 最小値 / 最大値(空の sum は 0)sum of split t by "," t = '1,2,3' → 6
round X四捨五入して整数に変換(2.5 は 3)round avg of split t by "," t = '2,3' → 3
avg of X平均(空のときは停止)avg of split t by "," t = '1,2' → 1.5
abs X絶対値abs number of t t = '-7' → 7

日時

書き方意味例(テストで動かしています)
monthday of X月と日(時と分を含むこともある)を取り出した当たりを "10/15 12:00" の形に変換monthday of first of find all M in t t = '締切10/15まで' → 10/15
date of X年月日を取り出した当たりを "2026/10/15" の形に変換(年が必要)date of first of find all Y in t t = '2026年10月15日' → 2026/10/15
time of X当たり、または時刻を含む文字から、時と分を "12:00" の形で取り出すtime of t t = '開始は 9:05 から' → 9:05
add 3 days to X年を含む日付に日数を足す(年を推測しないため、年のない日付では停止)add 3 days to t t = '2026/12/30' → 2027/1/2
weekday of X年を含む日付の曜日(mon〜sun を返し、match で分岐)weekday of t t = '2026/9/23' → wed
days until X今日から X までの日数(現在時刻が必要なため part の中で使用)—

shape(正規表現の代わり)

見出しの下に、部品を1行に1つずつ並べます。名前を付けた部分は 名前 of 当たり で取り出せます。

部品意味
"文字"書いたとおりの文字
space空白(1つ以上)
digits 1..2 / digits 4数字(範囲か、ちょうどの桁数を指定)
letters 1..10文字(日本語を含む)
word 1..10文字、数字、_(日本語を含む)
word with "._-" 1..64ASCII の英数字と指定した記号だけ(メールアドレスなどに使用)
any 1任意の1文字
名前 digits 1..2取り出す部分への名前付け(名前 of 当たり で使用)
maybe ...行の残りの部分を省略可能にする
one of "/" "-" "年"いずれか1つの文字(month one of "1" "2" … のように名前も付けられる)
edge数字や英字の途中で始まらない、または終わらないことの指定(最初の行か最後の行に書く。123-4567 は 0123-45678 に当たらない)
Clock / maybe Clock別の shape の利用(その shape で付けた名前も取り出せる)
shape Deadline
  month digits 1..2
  "/"
  day digits 1..2
  maybe Clock

shape Clock
  space
  hour digits 1..2
  ":"
  minute digits 2

標準ライブラリ

中身も Ponte で書かれており、example が付いています。

書き方中身action
use std/contact文の中からメールアドレスと電話番号を取り出す(use std/contact)FindEmail text text → found text | missing
FindPhone text text → found text | missing
FindPostal text text → found text | missing
use std/date文の中から日付を取り出す(use std/date)FindMonthDay text text → found monthday | missing
FindDate text text → found date | missing
use std/money文の中から金額(円)を取り出す(use std/money)FindYen text text → found number | missing

エラー

ponte check がエラーにする理由と直し方です。ponte explain E32 でも同じ内容を表示できます。

E01 match に else がない

なぜ止めるか 書いていない値が来たときに、何をするかが決まっていないためです。

どう直すか 最後に else -> 結果 を書きます。宣言した状態をすべて書いた場合、else は不要です。

E02 until に上限がない

なぜ止めるか 終わらない可能性のある待ちは、アプリを止めてしまうためです。

どう直すか repeat ... until 〇〇 or 1 hour passed のように、回数か時間の上限を書きます。

E03 action の example が2つ未満

なぜ止めるか 例が1つだけでは、中身(自分で書いても AI が書いても)が正しいかを確かめられないためです。

どう直すか 当たる例と当たらない例(-> missing など)を、少なくとも1つずつ書きます。

E04 action に else がない

なぜ止めるか action の中身が答えを出せなかったときの動きが必要なためです。

どう直すか else skip や else ask user のように、答えが出なかったときの動きを書きます。

E05 tbd が残っている

なぜ止めるか 決まっていないことを残したまま動かすと、その部分を誰かが推測で決めてしまうためです。

どう直すか 内容を決めて tbd を消します。決められない場合は、その部分を使わない形に書き換えます。

E06 ## が残っている

なぜ止めるか ## は、書いた人が確認を保留している箇所を示す印です。

どう直すか 内容を確かめてから、## を消すか #(通常のコメント)に変えます。

E07 when に状態を書いている

なぜ止めるか 「期限が近い」のような状態は、いつ起きるかが決まっていないためです。

どう直すか when には出来事(every day at 8:00 や user taps ...)を書き、状態は where か list で絞り込みます。

E08 move の対象が絞り込まれていない

なぜ止めるか どの1件を動かすかが決まらないまま、複数のレコードがまとめて動いてしまうためです。

どう直すか move this to 状態 にするか、list で1件に絞り込みます。

E10 競合する move の優先順位が決まっていない

なぜ止めるか 同じ1件に異なる move が同時に届いたとき、どちらを優先するかが決まらないためです。

どう直すか flow に failed > passed のように優先順位を書きます。

E11 list の参照が循環している

なぜ止めるか A の元が B で、B の元が A だと、中身が決まらないためです。

どう直すか どちらかを thing から直接絞り込む形に変えます。

E12 入れ子

なぜ止めるか 入れ子は読み違えやすいため、1段で書く決まりにしています。

どう直すか 内側の部分に名前を付けて外に出し、その名前を使います。

E13 action の約束が食い違っている

なぜ止めるか example の答えや never が out の形に合っていないと、確かめることができないためです。

どう直すか out に書いた形(found monthday | missing など)に合わせて、example と never を書き直します。

E14 relate の then / before が循環している

なぜ止めるか A の後に B、B の後に A が動くと、処理が終わらないためです。

どう直すか どこかの then を外すか、条件付きの rule に分けます。

E15 relate の優先順位が双方向になっている

なぜ止めるか A > B と B > A が両方あると、どちらも優先されないためです。

どう直すか どちらか一方だけを残します。

E16 before の前の rule が起きない

なぜ止めるか A before B と書いても A が起きる経路がなければ、B はいつまでも起きないためです。

どう直すか A のきっかけ(when)を書くか、before を外します。

E17 失敗したときの動きが2つある

なぜ止めるか action の else と relate の else が両方あると、どちらが動くかが決まらないためです。

どう直すか どちらか1つにします。

E18 match に宣言されていない状態がある

なぜ止めるか 宣言にない状態の枝は、打ち間違いであることが多いためです。

どう直すか 宣言にある状態名に直すか、宣言に状態を追加します。

E19 who がない thing がある

なぜ止めるか 書いていない操作は誰にもできない決まりのため、このままでは誰も見ることができません。

どう直すか who に user can see Thing where ... などを書きます。

E20 他のレコードを指す項目に gone がない

なぜ止めるか 指している先が消えたときに、こちらのレコードをどうするかが決まっていないためです。

どう直すか gone[remove too]、gone[leave empty]、gone[block] のいずれかを付けます。

E21 thing の形を変えたのに change がない

なぜ止めるか 保存済みのデータを新しい形にどう合わせるかが、決まっていないためです。

どう直すか change Thing to v2 に、追加した項目の初期値(add memo text = )や名前の変更を書きます。

E22 ask ai に上限がない

なぜ止めるか AI への問い合わせが止まらないと、費用と時間がかかり続けるためです。

どう直すか how に時間か費用の上限(limit 5 seconds や limit 1 yen)を書きます。

E23 connect が失敗したときの動きがない

なぜ止めるか 外部サービスは失敗することがあり、そのときの動きが決まっていないためです。

どう直すか relate に rule名 else 〇〇 を書きます。

E24 flow scene にない画面の移動

なぜ止めるか 画面の移動も flow と同じく、書いた経路しか通れないためです。

どう直すか flow scene に矢印を追加するか、移動先を直します。

E25 words の訳が足りない

なぜ止めるか 一方の言語だけ文字が欠けていると、その言語の利用者に意味が伝わらないためです。

どう直すか words ja と words en の両方に、同じ名前で書きます。1つの言語だけのアプリでは、words を書かずに "文字" と直接書くこともできます。

E26 名前のないボタンまたは説明のない画像

なぜ止めるか 読み上げ機能の利用者に、ボタンの役割が伝わらないためです。公開するときだけエラーになります。

どう直すか ボタンには named 名前 を、画像には説明を付けます。

E27 通貨の異なる money の足し算

なぜ止めるか 円とドルをそのまま足すと、意味のない数になるためです。

どう直すか 同じ通貨どうしで足すか、通貨ごとに分けて表示します。

E28 定義されていない名前、または知らない言葉

なぜ止めるか 存在しない部品、list、項目、アイコンを指したり、節や操作の言葉を打ち間違えたりすると、その行は無視されます。書いたつもりの動きが起きないため、エラーにします。

どう直すか エラーに表示された「もしかして」の名前に直すか、定義を追加します。

E29 rule に do が2つ以上ある

なぜ止めるか 1つの rule には1つの処理だけを書きます。2つあると、片方だけ失敗したときの結果が決まらないためです。

どう直すか rule を2つに分けて、relate の A then B でつなぎます。

E30 通知の宛先がない

なぜ止めるか 誰に知らせるかが決まっていないと、通知が誰にも届かないためです。

どう直すか notify owner ... のように、人を指す項目か me を書きます。

E31 書き方が正しくない(do、example の手順、読めない行)

なぜ止めるか 決まった形以外は、実行エンジンが動かせないためです。また、example の手順の打ち間違いを見逃すと、確かめていない例が通ってしまいます。

どう直すか do は ponte guide --rules の表にある形で書きます。example の手順は given / adds / at / says / taps / gets / expect のいずれかです。

E32 型が合わない、または存在しない状態や項目

なぜ止めるか 存在しない状態や項目、型の違う値は、空の一覧や起きない rule になります。動かす前に見つけるため、エラーにします。

どう直すか エラーに表示された候補(「todo / done」など)から選んで直します。

W09 (注意)flow の状態に対応する rule がない

なぜ止めるか 他の状態には rule があるのに、その状態のときの rule だけがありません。考慮漏れの可能性があります。

どう直すか その状態のときに起きることを rule に書きます。何もしない場合は、この注意は無視してかまいません。

W26 (注意)名前のないボタンまたは説明のない画像

なぜ止めるか 試作中は注意だけを表示します。公開するとき(--publish)はエラーになります。

どう直すか ボタンには named 名前 を、画像には説明を付けます。