REFERENCE
道具とエラー
このページは Ponte の実装から作っています。道具の例はすべてテストで動かしているため、ここに書いてある例は実際に動きます。
コマンド
python -m ponte か、pip install -e . のあとは ponte だけで使えます。
| コマンド | すること |
|---|---|
ponte check spec | 決めてないことを探す--publish 公開する時の検査--save-shape 通ったら thing の形を残す--json 結果を JSON で出す(エディタや AI のループ向け)--watch 保存するたびに流す(Ctrl+C で止める) |
ponte test spec | rule の example を全部流す--strict 穴(example で確かめていない所)があれば失敗にする--json 結果を JSON で出す |
ponte fill spec | by ai の action の中身をAIに書かせる(example と never を通るまで)--action この action だけ--ai anthropic(ANTHROPIC_API_KEY が要る)か file:返事.md--again もう中身があっても書き直す |
ponte fmt spec… | 誰が書いても同じ見た目に整える--check 書き換えず、整形が要るかだけ見る |
ponte build spec | spec と中身と実行エンジンを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 guide | AIに渡す書き方の説明を出す(実装から作る)--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 spec | check を通った仕様を、下の層の言語に渡す中間の形(JSON)にする-o 書き出すファイル(省略時は画面に出す)--cases 共通テスト(example)だけを出す |
ponte train spec | model を、保存したレコード(か --csv)から学ぶ--model この model だけ学ぶ--data レコードのファイル(省略時はアプリのデータ)--csv CSV から学ぶ(1行目は項目の名前) |
ponte job spec [name] | job を走らせ、報告された事実を約束と照合する |
ponte conform ir | IR の共通テストを、基準の実装(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 message | connect の 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 this | this の項目の値 |
"文字" | そのままの値 |
{名前} | 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 X | shape に当たった部分すべてを集まりで返す | 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..64 | ASCII の英数字と指定した記号だけ(メールアドレスなどに使用) |
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 | missingFindPhone text text → found text | missingFindPostal text text → found text | missing |
use std/date | 文の中から日付を取り出す(use std/date) | FindMonthDay text text → found monthday | missingFindDate 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 名前 を、画像には説明を付けます。