SPEC
仕様書 v0.3
v0.2 と、その後の追補を1つにまとめたものです。内容(ルールと書き方)は v0.2 から変えていません。 0〜2章、5章の主なパーツ、6章の「画面の小さな部品」、11〜12章、14章は確定しています。
0. コンセプト
Ponte は、プログラムのいちばん上の層に書く言語です。
- 書くのは、何が欲しいか、何をしてはいけないか、何がまだ決まっていないかです。どうやるかは書きません。
- Python や Java などの今までの言語は、Ponte の下で動く層になります。今の高級言語にとってのアセンブリと同じ位置です。
- 書いたことは必ず守られる約束です。決めていないことが残っていれば動かず、書いていない操作はできず、例に合わないものは通りません。
- 自分だけで書いても完結します。中身も Ponte の do で書けます。AI と作るときは、同じ仕様が AI への指示であり、AI が守る約束になります。
- if、for、true/false はありません。これらは「どうやるか」を書くための道具だからです。
目標は次の3つです。
- 覚える言葉を少なくし、読めばわかる言語にします。
- 9割は言語の中で書けるようにします。データとルールがあるもの(アプリ、API、定期処理、業務の流れ)は、この言語だけで作れます。
- 残りの1割は action の中身に閉じ込めます。約束(example、never、else)を先に書き、中身は自分で書くか、下の層の言語で書くか、AI に任せます。どれを選んでも、同じ約束で確かめます。
1. 設計原則
- パーツは少なくし、1つのパーツには1つの仕事だけを持たせます。複雑さはパーツを増やして出すのではなく、組み合わせで出します。
- 「何を」は必須、「どうやるか」は任意です。どうやるかは how と style にだけ書けます。書かなければ実行エンジンの標準の動きになり、書いたらその通りにしか作れません。
- 順序は書きません。並列が標準です。thing の1件は、それぞれ独立した1つのレコードです。レコードをまたぐ処理はすべて並列に、同じレコードの中の処理は1つずつ行います。順序が必要なときは、flow(状態)か relate(ルールの関係)で表します。
- 決めていないことはエラーになります。曖昧なまま渡すことはできません。
- 入れ子は禁止です。条件の中に条件を書かず、名前を付けて段階的に積み上げます。
- 何でも作れますが、危ないことは action の中身に閉じ込めます。外側(仕様と契約)は絞り、内側(action の中身)は契約を守れば何を書いてもかまいません。
- 同じ意味の語は1つだけにします。else はどこでも「逃げ道」、do はどこでも「やること」を表します。
>はどこでも「ぶつかったらこちらが勝つ」、|はどこでも「どれか1つ」を表します。
2. 型
| 型 | 意味 |
|---|---|
| text | 文字 |
| number | 数 |
| count | 0以上の整数 |
| money | お金。通貨付きで、小数の誤差なし。money yen |
| percent | 割合 |
| date | 日時 |
| monthday | 年のない月日と時刻。10/15 12:00 |
| duration | 期間。3 days 5 seconds |
| file / image / pdf | ファイル |
[a | b | c] | 決まった状態のどれか1つ(旧 one of [a, b, c]) |
| thing の名前 | 別のレコードを1つ指す。owner User(旧 ref User) |
list of thing の名前 | 別のレコードを複数指す(旧 many) |
- true / false はありません。
done [todo | done]のように、すべて名前の付いた状態にします。if を生まないためです。 - 組み込みの値には
nowとmeがあります。meは今使っている人を指します(旧 current user)。
3. 記号とコメント
| 記号 | 意味 | 使うところ |
|---|---|---|
| | または(どれか1つ) | 状態、flow の分かれ道、出力、match の左側 |
-> | 移る・対応する | flow、match、example |
> | ぶつかったらこちらが勝つ | flow、relate |
[ ] | 状態を並べる | 状態の宣言だけ |
{ } | 取り出した値 | user says など |
# | 普通のコメント | どこでも。ビルドに関係しない |
## | 止めるコメント | 1つでも残っていたらビルドできない |
- and を表す記号はありません。and は行を重ねて書きます。where を2行書けば、両方を満たすものが対象になります。
##は次のように使います。AI が仕様の穴に気づいたら、答えの案を##で書き、理由を後ろの#に書きます。人は##を外せば承認、行ごと消せば却下したことになります。人が「後で必ず見直す」ための印として使ってもかまいません。
list DueSoon of Application where status is draft where deadline within 3 days ## where deadline is after now # 締切が過ぎた応募も通知する?
4. パーツ一覧
見出し(行頭に書くもの): thing, flow, list, match, rule, relate, action, model, job, group, tbd, never, scene, look, part, style, input, words, who, change, connect
節(見出しの中に字下げして書くもの): of, where, sort, when, do, why, in, out, example, by, how, given, expect, learn, using, require, run, at, with, confirm, suspect
守り(言語が守らせるもの。赤で表示): never, else, >, ##, tbd, who, gone, limit
5. 各パーツ
thing(データの形。旧 entity)
thing Application company Company gone[block] deadline date owner User gone[remove too] memo text status [draft | submitted | passed | failed]
- 1件が1つのレコードです。レコードの中の書き換えは1つずつ処理されます。
- 項目は
名前 型を並べて書きます。:は付けません。名前と型は色分けで見分けます。 - 状態は
名前 [a | b]と書きます。 - 別のレコードを指す項目には、指した先が消えたときにどうするかを
gone[...]で必ず書きます(7.3)。
flow(状態の流れ)
flow Application.status draft -> submitted -> passed | failed failed > passed
- 状態は
->の通りにしか動けません。たとえば draft から passed へは飛べません。 - flow で管理する項目は move でしか変えられず、set は禁止です。
failed > passedは、同じレコードに矛盾する move が同時に来たときの勝者を表します(旧on conflict failed wins over passed)。同時に来る可能性があるのに書いていなければ、エラーになります。- flow には「状態の流れ」だけを書きます。動作の順番は書きません。
list(条件で絞った集まり)
list DueSoon of Application where status is draft where deadline within 3 days sort deadline
- where を複数行書くと、すべてを満たすもの(and)が対象になります。1行の中に and / or / かっこは書けません。
- list から list を作って積み重ねられます。循環参照はエラーです。
- for の代わりになるのが list です。ルールや通知は「当てはまるものすべて」に効きます。
within 3 daysは暦日で数え、今から3日後の日の終わりまでを含みます。sort deadline descと書くと逆の順(新しい順)になります。書かなければ昇順です。fromはofに、sort byはsortに変わりました(16章)。
match(値ごとの結果)
match Application.status to color draft -> red submitted -> gray passed -> blue else -> gray
- else がないとエラーになります。ただし、宣言された状態をすべて書いた match は else を省略できます。
- 宣言にない状態を左側に書くとエラーになります。打ち間違いを止めるためです。
- 左側は
|でまとめられます(saturday | sunday -> weekend)。 - match の中に match は書けません(入れ子)。
rule(きっかけとやること)
rule Remind why 締切を落とさないため when every day at 21:00 do notify owner each of DueSoon example given Application company "Osaka Gas" deadline "9/24 23:59" status draft at "9/21 21:00" expect notify "Osaka Gas"
- rule は
why(任意)、when、where(任意)、do、exampleで書きます。
when(きっかけ)
when に書けるのは出来事だけです。状態は where に書きます(when deadline within 3 days は禁止です)。
when に書ける出来事は次のものに限られます。
- 時間:
every day at 21:00/every monday at 9:00/at 9/24 23:00 - 人:
user says "..."/user taps X on 画面か thing - 書き方は決まっているものの、まだ実行エンジンが起こさない出来事もあります(check で E07 になります)。
user holds X/user swipes X left/user drags X to Y/user types in X/user opens Scene/user leaves Sceneがこれにあたります。board の列の移動は〇〇 moves to 状態として起きます。 - データ:
〇〇 is created/〇〇 moves to 状態/〇〇 is removed - 外:
Gmail gives new message(connect の gives)
一覧の元は ponte/forms.py にあり、python -m ponte guide --rules で表にして出せます。
{...} で取り出した値は変数になります。このとき、対象のレコードは必ず絞ります。 when user says "submitted {company}" → do move Application where company is {company} to submitted
画面で押された1件は this で指します。
where(起きる条件)
rule の where は、押された1件(this)の条件です。条件に合わないとき、その rule は静かに起きません。失敗の通知も出ず、画面のボタンも押せなくなります。
rule Borrow when user taps borrow-button on Item where status is free do create Loan item this due 7 days from now
do(やること)
do は1つだけ書けます。2つやりたいときは rule を分けて、relate の then でつなぎます。書ける形は次の表のものだけで、ほかの書き方は check でエラー(E31)になります。
| 書き方 | すること |
|---|---|
notify me "..." | きっかけの人に通知する |
notify owner each of DueSoon | 一覧のそれぞれのレコードの owner が指す人に通知する |
move this to submitted | 押された1件の状態を動かす |
move item of this to lent | this の item 項目が指すレコードを動かす |
move Application where company is {company} to submitted | 絞ったレコードを動かす |
remove this | 押された1件を消す(7.3) |
go Detail / go Detail with this | 画面を移る |
create Loan(下に字下げして「項目 値」) | レコードを作る |
set yen to result | 項目を書き換える(状態は set でなく move で変える) |
FindYen / FindYen with memo | action を呼ぶ。with で、入力を this の項目から渡す |
connect の does(Gmail send mail など) | 外に頼む |
通知には宛先を書きます。宛先は me か、項目の名前(notify borrower "...")です。通知の文に入れる {item} は、this の項目か when の {…} です。その項目が別のレコードを指す場合は、指しているレコードの名前が入ります。
値の書き方
create の「項目 値」と set の値には、次のものを書けます。
| 値 | 意味 |
|---|---|
this | 押された1件 |
me | 今使っている人 |
"文字" | 書いた文字そのもの |
7 days from now | 今からの期間(minutes / hours / days / weeks)。年まで入れて保存し、推測はしない |
{名前} | when で取り出した値 |
項目 of this | this の項目の値 |
result | 直前の action の答え(set でだけ使える。std の例は 9.5) |
そのほか
- ルール同士の関係は relate に書きます。
- flow の状態ごとにルールを書いていて抜けがあると、「passed のときは?」という警告が出ます。
relate(ルール同士の関係)
relate ReadMail then FileMail ManualAdd then no FileMail CheckSpam before FileMail NotifyFailed > Remind LineNotify else MailNotify
どの行も「左が先、右が後」です。
| 書き方 | 意味 |
|---|---|
A then B | A が終わったら B が動く |
A then no B | A をやったら、この後 B は動かない。B がすでに済んでいても取り消さない |
A before B | B が動くとき、A は済んでいる。A が終わっても B は勝手に動かない |
A > B | 同時に当てはまったら A が勝つ |
A else B | A が失敗したら B をやる |
A then Bの途中で処理が落ちても、言語が裏で「このレコードで A は済んだ」ことを記録しているので、続きから再開できます。- action に else があり、relate でも同じ action に else を書いた場合はエラーになります。逃げ道は1つだけです。
action(中身が空の部品。契約だけを書く)
action ExtractDeadline in mail text out found monthday | missing example "10/15(木)12:00まで" -> found 10/15 12:00 example "【締切9/24 23:59】" -> found 9/24 23:59 example "来週中にご提出ください" -> missing example "9/24 23:59 または 9/30 23:59" -> missing never guess the year else ask user by ai how limit 5 seconds
- 旧 input / output は in / out になりました。
- example は最低2つ必要です。中身は、すべての例を通らないと採用されません。
- else も必須です。自信がないときの逃げ道(
ask user/use default .../skip)を書きます。 - 契約の矛盾はエラーになります。たとえば、example の答えが out の型に合わない場合や、never と out の型がぶつかる場合です。
never guess the yearなのに out が年の必要な date になっているのが後者の例です。 - 次の表の never は、中身ができたときに機械が大量の入力で確かめます。それ以外の never は、今は機械では確かめられません。ただし AI への指示にはなります。
| never | 確かめ方 |
|---|---|
guess the year | 例の入力と、年のない入力をいくつか流して、答えに年(4桁の数)が出ないか |
depend on width | 例の入力を全角にして流し、半角のときと同じ答えになるか |
return empty | 例の入力とおかしな入力を流して、値が空の答えを返さないか |
fail | おかしな入力(空、長すぎる、絵文字、ありえない日付など)でも止まらないか |
- 失敗や「見つからない」も、out の状態で表します(
found ... | missing)。
by(誰が中身を埋めるか)
| 書き方 | いつ | 中身 |
|---|---|---|
| (書かない) | なし | action の中にその場で書いた do。AI も別ファイルも使わない |
by ai | ビルドのときに1回 | AI が do を書いて固定する。人も読めて直せる |
ask ai | 実行のたびに毎回 | AI に聞く。do はない。how に時間かお金の上限が必須 |
by code "extract.ponte" | なし | 自分で書いた do |
by python "extract.py" | なし | 下の層の言語(Python)で書いた中身。約束と confirm で確かめる(5章 with と confirm) |
by Gmail | 実行のたびに | connect 先が行う |
誰が埋めても、同じ example、never、else で検証されます。
do(action の中身)
do
text = normalize mail
hits = find all Deadline in text
kind[one | none | many] = match count of hits
1 -> one
0 -> none
else -> many
found = match kind
one -> found monthday of first of hits
none -> missing
many -> missing
- 書けるのは
名前 = 式と、名前を付けた match だけです。 - 答えになるのは、ほかのどの行からも使われていない行です。そのような行がちょうど1つでなければエラーになります。答えの行に
[...]は必要ありません(形は out に書いてあるためです)。書く場合はanswer[found monthday | missing]のように、out の形と同じにします。 - 一時的な状態は
名前[a | b] = match ...で宣言して使います。 - 書き換え、ループ、再帰、true/false はありません。そのため、必ず止まります。
- 実行の順番は名前の依存関係で決まり、上から順に実行されるわけではありません。
- 使える道具は 10章にまとめています。
shape(文字の形。正規表現の代わり)
shape Deadline month digits 1..2 "/" day digits 1..2 maybe "(" any 1 ")" maybe space hour digits 1..2 ":" minute digits 2
with と confirm(宣言した値が、下の層で本当に効いたか)
上の層で値を宣言しても、下の層で黙って捨てられることがあります。タイムアウトを渡したのにライブラリが無視していた、学習率を渡したのに既定値のまま学習していた、などです。 confirm は、下の層に「実際に使った値」を報告させ、宣言と照合します。一致しなければ止まります。
action Summarize in text text out found text | missing example "長い文" -> found "短い文" else skip by python "summarize.py" with max_words 20, timeout 5 seconds confirm max_words, timeout
| 部品 | 意味 |
|---|---|
with 名前 値, 名前 値 | 下の層に渡す値の宣言。値は数、5 seconds のような期間、yes / no、"文字" のどれか |
confirm 名前, 名前 | 下の層が実際に使った値を報告させ、with と照合する名前 |
confirm 名前 値 | 下の層には渡さないが、こうなっているはずの設定(読み込んだ重みの合計など)。報告された値を、書いた値と照合します |
決まり
withとconfirmは、何行に分けて書いてもかまいません。confirmの名前だけのものは、withにある名前に限ります。confirm 名前 値は、その値と照合します。confirmは「宣言した設定が実際に効いたか」、require(job)は「走らせた結果が条件を満たすか」です。いつ照合するかではなく、何を照合するかで使い分けます。- 下の層は、1回動くたびに、使った値を報告します。Python では
from ponte.report import reportのreport(名前=値)です。報告は、渡された値ではなく、実際に使っている物から読みます(学習率なら、引数ではなく optimizer が持っている値)。 - 照合は1回動くたびに行います。次のどれかなら、その回は失敗です。
confirmの名前が報告されていない(確かめられないものは、効いたとみなさない)- 報告された値が宣言と違う
- 数は、差が大きい方の値の 1e-9 倍以下なら同じとみなします。期間は秒にそろえて比べます(
5 secondsと5000 msは同じ)。 - 揺れてよい値には、許す幅を書きます。
confirm pretrained_checksum 1234.5 within 0.01%は、相対 0.01% までの差を同じとみなします(GPU の計算で下の桁が揺れる値など)。幅は、書いた値にだけ効きます。 - ズレたときは、宣言した値と、実際に使われた値を必ず両方示します。正しい更新なら、書き換えるだけで済みます。
- 失敗した回は、
ponte testでは失敗になり、動いているアプリでは中身が答えを出せなかったものとしてelseに従います。理由は「どの名前が、宣言ではいくつで、実際はいくつだったか」で示します。 withとconfirmは、下の層に中身を任せる部品(by pythonの action、connect、job)に書けます。
job(下の層のプログラムを、約束付きで走らせる)
job は、下の層のプログラム(学習、変換、集計など)を走らせ、そのプログラムが報告した事実を約束と照合します。プログラムが何をしているかを、Ponte は知りません。見るのは、報告された事実だけです。
job Train run uv run python train.py at "~/research/project" with learning_rate 1.25e-4, batch_size 32, start_from_pretrained yes, j 24 confirm learning_rate, batch_size, start_from_pretrained confirm pretrained_checksum 1234.5 require classes is 3 require clips_mismatch is 0 require test_accuracy at least 52 suspect test_accuracy above 75
| 部品 | 必須 | 意味 |
|---|---|---|
run コマンド | 必須 | 走らせるコマンド |
at "フォルダ" | 任意 | 走らせる場所。書かなければ仕様のファイルがある場所。~ はホームフォルダ |
with 名前 値, … | 任意 | プログラムに渡す値。それぞれコマンドの引数になります。yes は --名前 だけ、no は渡さない、1文字の名前は -j 24 の形です。"~/…" の ~ はホームフォルダに広げます |
confirm 名前, … / confirm 名前 値 | 任意 | 設定が実際に効いたか。報告させて照合します(5章 with と confirm)。名前 値 は引数にしません |
require 事実 条件 | 任意 | 報告された事実が満たすべき条件 |
suspect 事実 条件 | 任意 | 報告された事実がこうなったら、おかしいとみなして止める条件(良すぎる数字など) |
条件は is 値、at least 数、at most 数、above 数、below 数 のどれかです。
決まり
- 走らせるのは
ponte job 仕様.ponte 名前です。プログラムはponte.report.report(名前=値)で事実を報告します。報告は、環境変数PONTE_REPORTのファイルに届きます。 - 同じ名前を何度報告しても、最後の値を使います。
confirmとsuspectは、走っている間に照合します。ズレや、おかしい事実を見つけたら、その場でプログラムを止めます。requireは、終わったあとに照合します。報告されなかった事実は、requireを満たしません。途中で満たさなくても、最後に満たせばかまいません。suspectには、学習の途中で自然に超える値(train の精度など)ではなく、超えたら何かが壊れている値(論文を大きく上回る test の精度など)を書きます。- 次のどれかなら、その job は約束を守れなかったことになります(
ponte jobは失敗で終わります)。 confirmがズレたrequireを満たさないsuspectに当てはまる- プログラムが失敗した
- 何を事実として報告するかは、プログラムの側で決めます。クラスの数や、データとラベルのズレの数のように、複雑な計算は下の層で行い、Ponte には結果だけを報告します。
model(レコードから学んで当てる部品)
model は、thing のレコードから学んで、状態の項目を当てる部品です。書くのは「何を学ぶか」「何を見てよいか」「どこまでできれば合格か」「使えないときにどうするか」で、学び方は書きません。
model Churn learn will_leave from Customer using visits, spend, months require accuracy at least 80% else skip example visits 0, spend 0, months 1 -> yes
| 部品 | 必須 | 意味 |
|---|---|---|
learn 項目 from Thing | 必須 | 当てる項目と、学ぶレコードの thing。項目は状態の項目([yes | no] など)に限ります |
using 項目, 項目 | 必須 | モデルが見てよい項目。数の項目(number / count / money / percent)か状態の項目に限ります。当てる項目そのものは書けません |
require accuracy at least N% | 必須 | 合格の条件。取り置いたレコードでの正解率が N% 以上であること |
else | 必須 | モデルを使えないときの動き。skip(当てたことにしない)か use default 状態(その状態として扱う) |
how layers 16 8, epochs 200 | 任意 | 学び方の細かい指定。書かなければこの値です |
example 項目 値, 項目 値 -> 状態 | 任意 | 必ず当てなければならない例 |
学ぶ(ponte train)
- 学ぶのは、
learnの thing のレコードのうち、当てる項目に状態が入っているものです。作られた順に並べます。 - 並べた順で5件に1件(5件目、10件目、…)は学びに使わずに取り置き、正解率を測るのに使います。同じレコードは、いつも同じ側に入ります。
- レコードが20件に満たないときは、学びません(エラーになります)。
- モデルに渡すのは
usingに書いた項目だけです。それ以外の項目は、学ぶときも当てるときも見せません。 - 学んだ結果は
仕様.ponte.models/名前.jsonに置きます。どの定義で学んだかの印(learn、using、howと、使う項目の型から作ります)も一緒に置きます。
使えるモデル
次のすべてを満たすモデルだけを使えます。1つでも欠ければ、そのモデルは使えないものとして扱います。
- 学んだ結果がある。
- 学んだときの定義の印が、今の定義と同じ。
- 取り置いたレコードでの正解率が
require以上。 exampleをすべて当てる。
ponte test は、学んだ結果があるモデルについて 2〜4 を確かめ、1つでも欠ければ失敗にします。学んだ結果がないモデルは、中身のない action と同じく、確かめていない部分として一覧に出します。
当てた答えを使う
list AtRisk of Customer where predict Churn for it is yes
predict 名前 for it is 状態(list の where)とpredict 名前 for this is 状態(rule の where)で、モデルが当てた状態で絞ります。- モデルが使えないときは
elseに従います。skipなら条件は成り立ちません。use default 状態なら、当てた答えをその状態として扱います。
how(どうやるか。任意)
- how は rule と action の中にだけ書けます。
- 書かなければ AI が決めます。書いたら、AI はその通りにしか作れません。
- 例:
check every 10 minutes/limit 5 seconds/limit 1 yen/on failure retry 3 times/repeat ... until 〇〇 or 1 hour passed - until には回数か時間の上限が必須です。ないとエラーになります(無限ループを防ぐためです)。
- action の
limit N secondsとon failure retry N timesは、動かすときに守られます。時間を過ぎたら失敗とし、失敗したら決めた回数だけやり直します。
group(まとまり)
group Mail rule ReadMail when Gmail gives new message do ExtractDeadline rule FileMail do create Application relate ReadMail then FileMail
- group は名前でくくるだけのもので、継承はありません。外からは
Mail.ReadMailで呼びます。 - group の中の字下げは入れ子と数えません。group の中に group は書けません。
- 別のファイルは
use "mail.ponte"で取り込みます。エラーは、取り込んだ元のファイルと行で示されます。
tbd(まだ決めていないこと。旧 unknown)
tbd timezone of deadline who can delete Application
- tbd が残っているとビルドできません。AI は埋めずに、質問を返します。
##との違いは、答えの案があるかどうかです。tbd には答えがなく、##には答えの案がすでに書いてあります。
never(やってはいけないこと)
- never は action の中にも、ファイル全体にも書けます。
- never は、生成されたコードのガードとテストになります。証明できる違反は、ビルド前にエラーになります。
- action の never は、自動で作った大量の入力で検証します。たとえば年のない入力を何百個も作り、すべてが missing か else になるかを確かめます。
6. 画面
「何を見せるか」は scene、look、part、input に書き、「どう見せるか」は style に書きます。書かなかった見た目は AI が決めます。
scene(場面)
scene Home menu[open | closed] = closed top Header main match count of DueSoon 0 -> EmptyNote else -> DueSoon as cards side Application as list bottom button add over match menu open -> Menu closed -> nothing
- 置き場所は
top/main/side/bottom/over(上に重ねる)です。細かく並べるときはrow/column/grid 3を使います。 - 出し分けには match を使います。
nothingは何も出さないことを表します。 - 画面だけの状態は
名前[a | b] = 最初の値と書きます。
画面の移動
flow scene Home -> Detail -> Edit Home -> AddApplication rule OpenDetail when user taps card on DueSoon do go Detail with this
- 画面は flow scene の矢印の通りにしか移動できません。矢印にない移動はエラーになります。
look(見せ方)
look DueSoon as cards title company sub DeadlineBadge of deadline mark color of status button submitted-button named 提出した look Header button menu-button named メニュー toggle menu button close-button named 閉じる set menu closed
- 見せ方の種類は cards / list / table / detail / input / calendar / board / chart / tabs / dialog / sheet / toast / map / media です。
- board では、flow から状態ごとの列が自動で作られます。カードを動かすと move の出来事が起きます。
- chart は、状態ごとの件数を棒で表します。
group by 項目で分け方を、sum 項目で棒の高さを合計に変えられます。sumに使えるのは数の項目だけです(例: 家計メモの「費目ごとの合計」)。 ``look ByKind as chart group by kind sum yen - 画像を扱うには、thing の項目を
photo imageにして input に書きます。これで画像を選べるようになります(png / jpg / gif / webp、5MB まで)。種類は中身の先頭で確かめます。一覧では、look にimage photo about nameと書くと写真が出ます。aboutは読み上げ用の説明で、公開するときは必須です。画像は、そのレコードを who で見られる人にだけ表示されます。 - input に状態の項目を書くと、選ぶ形になります。ただし flow のある状態は選べません(ボタンの rule で move します)。
- **画面だけの状態は、look の中で
toggle 状態/set 状態 値と書けます。** この場合 rule は必要ありません。データ(thing の項目)は rule の move でしか変えられません。
part(自分で作る部品)
part DeadlineBadge in deadline monthday do left = days until deadline urgency[today | soon | later] = match left 0 -> today 1..3 -> soon else -> later show text "あと{left}日" mark urgency
- 名前を付けて、どこでも使い回せます。
- part の中で part を使えますが、part の中で part を定義することはできません。
- 言語の見せ方で描けない絵は
part 名前 by aiで作ります。example で「このデータのときにこうなっているか」を検証します。見た目の良し悪しまでは機械で検証できません。
input(入力)
input AddApplication company required deadline required, from now memo resume file, pdf only, max 5 MB
- 送信すると
Application is createdの出来事が起きます。 - 入力のチェックは項目の隣に書きます。満たさないときの表示は言語が出します。
required(必須)とfrom now(今より後)は、画面とサーバーの両方で守られます。
style(見た目)
style theme color main #2F6FEB space s 8 style DueSoon card round 12, shadow soft, pad 16 title size 18, bold mark dot left gap 16 enter fade 200ms reorder slide 150ms style Home on phone main column style Home on wide main grid 3
- 色、大きさ、余白、角丸、影、フォント、動き、並べ方まで書けます。
- 画面の大きさは
on phone | tablet | wideで指定します。 - 書かなかったところは AI が決めます。
words(画面の文字と多言語)
words ja add 追加 words en add Add
- 片方の言語だけ訳がないとエラーになります。
- 1つの言語だけのアプリなら、words は必要ありません。
named "借りる"/empty "まだありません"のように、画面の文字を"文字"で直接書けます。 - words がある spec では、画面の文字を words の名前で書きます。 対象は、ボタンの名前、見出し、空のときの文、確認の文、部品の文、部品が計算する文です。words にない名前はエラー(E25)になります。日本語は words ja に1回だけ書きます。
look DueSoon as cards heading due-heading button submitted-button named submit icon send words ja due-heading 3日以内に締切 submit 提出した words en due-heading Due within 3 days submit Mark submitted
- 言語が出す文字(
searchsavecancelnone)も、words で訳せます。 - words がない spec では、画面の文字を直接書けます。
読み上げ対応
- 名前のないボタン(
namedがない)と、説明のない画像(aboutがない)は、試作の間は注意になり、公開するときはエラーになります。
画面の小さな部品
画面を作り込むために足した小さな部品です。どれも1つの仕事だけを持ちます。
| 書き方 | 意味 |
|---|---|
main tabs tab | 画面の状態 tab[...] を切り替えるタブを出す |
main this as detail | 前の画面で押された1件を詳しく見せる |
look Application as detail | thing の名前の look は、詳しく見せるときの見せ方になる |
empty "..."(look の中) | 1件もないときに出す文 |
part の中の do | 部品の中で値を計算する。action の中身と同じく、do の下に 名前 = 式 と 名前[a | b] = match ... を書く |
days until X | 今日から X までの日数(今日なら 0、過ぎていればマイナス) |
match の左の 1..3 / ..-1 / 4.. | 数の範囲(両端を含む) |
match 部品名.状態 to color | 部品の状態ごとの色 |
ボタンの行の tone main | quiet | good | danger | ボタンの強さと色(button failed-button named 不合格 tone danger)。書かなければ、一覧の最初のボタンと画面の下のボタンだけが強くなる |
#4F46E5 | # のすぐ後ろに16進の色が続くときは、コメントではなく色の値 |
user taps X on thing の名前 | list の名前でなく thing の名前で書けば、どの一覧、ボード、詳細画面から押しても動く |
button 名前 named 文字 icon 名前 | ボタンにアイコンを付ける。アイコンは組み込みの24個だけ(ない名前はエラー) |
button 名前 named 文字 confirm "文" | 押す前に確かめる。やめれば何も起きない |
named "空白を含む 名前" | 名前は1語。空白を含むなら引用符で囲む。ボタンの行に知らない語があればエラー |
match Application.status to icon / match tab to icon | 状態ごと、タブごとのアイコン(色の match とは別に持てる) |
lead company(look の中) | 頭文字の丸 |
heading "..."(look の中) | 見出しと件数 |
search company, memo(look の中) | 一覧の検索 |
group by status(look の中) | 状態ごとにまとめる |
take 20(look の中) | 最初に見せる件数。残りは「もっと見る」で出す |
empty "..." button add named 追加(look の中) | 1件もないときの文と、次にやることのボタン |
top notices | お知らせのベル(未読の数と一覧) |
go EditApplication with this | input を with this で開くと、その1件の編集になる。状態の項目は書き換えられない(move だけ) |
words の "引用符の鍵" 訳 | spec に直接書いた日本語も訳せる |
言語が画面で守ることは次のとおりです。
- flow で動けないボタンは、自動で押せなくなります。 rule が
move this to Xで、今の状態から X へ動けなければ、そのボタンは薄くなって押せません。 - board でカードを動かすと move が起きます。flow にない流れは「『下書き』から『通過』へは動かせません」と表示され、受け付けられません。
- 目立つ色になるのは画面の下(bottom)のボタンだけです。上や一覧のボタンは控えめな色になります(最初のボタンだけは強くなります)。
- look の title / lead / search / group by に書いた項目名が存在しない場合はエラー(E28)になります。存在しないアイコン名や、読めないボタンの行も同じです。
件数と合計
main stats Mine, sum yen of Mine と書くと、一覧の件数と項目の合計を並べて表示します。数えるのは見えるものだけです。見出しは words の名前で書きます(合計は「金額の合計」)。数は3桁ごとに区切って表示します。sum に使えるのは数の項目だけです(E32)。
リアルタイム
- 何も書かなくても、画面は常に最新になります。レコードが変わると、それを表示している画面も自動で変わります。
7. データと人
7.1 who(誰が何をできるか)
who user can see Application where owner is me user can change Application where owner is me admin can do everything nobody can remove Application
- 書いていないことは誰もできません。
- who が1行もない thing はエラーになります。
- rule も who に従います。user says や user taps で動く rule は、その人ができることしかできません。
- ログインの方法は connect に任せます。
- 役割:
user以外の役割(admin など)は、thing Userのrole [member | admin]に書きます。その人の role の値が役割になります。書いていない役割を who に使うとエラー(E28)になります。 - 役割の変更も、普通の状態と同じく flow User.role、rule、who で守ります。
- 最初の1人は仕様から決められないため、
ponte role spec.ponte taro adminで決めます。2人目からは画面で決めます。 where it is not meで「自分には使えない」ことを書けます。これにより、自分を管理者から外せなくなり、管理者が0人になることを防げます。- 動詞は
see/create/move(状態を動かすだけ)/change(作る、動かす、書き換える)/removeです。 - 入力を開くボタンは、その thing を作れる人にだけ表示されます。
7.2 保存
- 保存は言語が受け持ちます。thing を書けばデータは残ります。どのデータベースを使うかは書きません。
7.3 消したときの扱い
- ほかのレコードを指す項目には
gone[...]を必ず書きます。ないとエラーになります。 - 消すには rule の
do remove thisを使います。who のcan removeが必要です。消すと〇〇 is removedの出来事が起きます。
| 書き方 | 意味 |
|---|---|
gone[remove too] | 一緒に消す |
gone[leave empty] | 空にする |
gone[block] | 指されている間は消せない |
7.4 thing を変えたとき
change Application to v2 add memo text = "" rename company to corp remove owner remove state passed -> failed
- thing の形が前回のビルドと違うのに change がなければ、エラーになります。
- 動かすときに、保存してある古いデータは change の通りに今の形へ移されます。足した項目の初期値、名前の変更、消した項目、消した状態の移し先が使われます。
- 足した項目に初期値がないとエラーになります。
- 状態を消すときは、その状態だったレコードの移し先が必須です。
8. 外とつながる(connect)
connect Gmail gives new message Message does send mail to text, body text -> sent | failed needs key GMAIL_TOKEN limit 100 per hour
givesは、向こうから届く出来事です(when Gmail gives new message)。doesは、こちらから頼めることです。結果は必ず状態で返ります。needsは秘密の値です。値そのものは仕様に書かず、実行するときに渡します。limitは回数の上限です。by python "pay.py"と書くと、does の中身を Python で書けます。does charge amountなら、pay.py のcharge_amount(値, settings)を呼びます。withとconfirmを書けます(5章 with と confirm)。たとえばwith timeout 5 secondsとconfirm timeoutを書くと、クライアントが実際に使ったタイムアウトを報告させて照合します。一致しなければ、その does は失敗として扱い、失敗の逃げ道に進みます。理由は必ず知らせます。- does が失敗したときの逃げ道(relate の else か、結果を match して書くもの)がないとエラーになります。
- 言語の中は依存ゼロです。外との境界は、connect に宣言した口だけです。
9. テスト(example)
rule MarkSubmitted when user says "submitted {company}" do move Application where company is {company} to submitted example given Application company "Osaka Gas" status draft given Application company "Other" status draft says "submitted Osaka Gas" expect Application is submitted company "Osaka Gas" expect Application is draft company "Other"
- example は3段で書きます。
given(前の状態)、出来事、expect(結果)の順です。 - レコードの中身は字下げして1行に1つずつ書きます。
given Applicationの下にcompany "Osaka Gas"のように並べます。かっこと,は使いません。 - given で別の thing を指す項目は、そのレコードの名前で書けます(
item "カメラ")。 - 前の状態:
given thing の名前(下に中身を書く) - 出来事:
at "..."/says "..."/taps X on thing の名前(下に中身を書く)/taps X on 画面の名前/gets Gmail new message "..."/adds thing の名前(下に中身を書く。人が作ったことにし、〇〇 is createdの出来事も起きる) - 結果:
expect notify "..."/expect X is 状態/expect 箱(下に中身を書き、その中身のレコードがあるかを確かめる)/expect no Loan/expect 2 Loan(件数)/expect scene Detail/expect Home shows 2 cards(存在しない scene に shows を書いたら失敗)/expect nothing
ponte test は穴さがしもします。example がすべて通ったうえで、どの example も確かめていないところを示します(--strict を付けると失敗として扱います)。対象は次のとおりです。
- when がある rule なのに example がなく、どの example の中でも動いていない
- flow の矢印(
a -> b)を、どの example も通っていない - action の out の答えの形(found / missing など)を出す example がない
9.5 標準ライブラリ
use std/名前 で、言語に付属する .ponte を読み込みます。中身もこの言語で書かれており、すべてに example と never が付いています(ponte test で一緒に流れます)。
| 読み方 | action | 答え |
|---|---|---|
use std/date | FindMonthDay | found monthday(年は推測しない)/ missing |
use std/date | FindDate | found date(年が書いてある日付だけ。13月などありえない日付は missing)/ missing |
use std/money | FindYen | found number(¥ が前でも 円 が後ろでも、全角でも読む)/ missing |
use std/contact | FindEmail / FindPhone / FindPostal | found text / missing(郵便番号は 150-0001 の形。電話番号の途中には当たらない) |
- どれも、候補が2つ以上あったら決めずに missing を返します。else は skip です。
- rule からは次のように使います。
do FindYen with memo(入力は押された1件の memo)→relate ReadYen then SaveYen→do set yen to result。 - 答えが出なかったとき(missing / skip)は、result を使う rule は静かに起きません。
10. do で使える道具
現在使える道具の一覧です。この表は実装から生成しており、すべての例をテストで実行しています。
| 種類 | 書き方 | 意味 | 例 |
|---|---|---|---|
| 文字 | 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') |
| 形 | 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') |
| 数 | 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) |
| 文字 | X contains "a" | 文字を含むかどうか(答えは yes / no で、match で分岐) | t contains "締切"(t が "締切は明日" なら 'yes') |
| 文字 | X starts with "a" | 指定の文字で始まるかどうか(答えは yes / no) | t starts with "Re:"(t が "Fw: 件名" なら 'no') |
| 集まり | ["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']) |
| 数 | 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 の部品は次のとおりです。
"文字"… 書いたとおりの文字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 で付けた名前も取り出せる)
まだない道具(予定)もあります。次のものは、書くとエラーになります。
- 日時の start of day / end of day(weekday of、add N days、date of は年の入った日付だけに使えます)
- 集まりの each / group by
- 読み書き(json、csv、pdf、画像)
道具についての補足です。
- each と sort は、数に上限がある集まりにだけ使えます。
名前 of Xは shape で名前を付けた部分(amount of first of hits)を、text of Xは当たった文字そのものを取り出します。+と-は一番弱くつなぎます。count of a + count of bは (count of a) + (count of b) と読みます。- 状態の名前と行の名前を同じにするとエラーになります。どちらを指すのか区別できないためです。
- shape の
word with "._-" 1..64が当たるのは、英数字(ASCII)と書いた記号だけです。日本語の文字は入りません。メールアドレスの前後にある日本語を拾わないようにするためです。 - 道具で足りない計算は、action の by ai / by code に任せます。
- 通貨の違う money を足すとエラーになります。
11. 実行モデル
- thing の1件(レコード)が1つのアクターです。レコードは互いに独立しています。この考え方は、Erlang や Go(goroutine と channel)と同じです。
- ルールはすべて独立しています。並列を書かなくても並列に動きます。
- 同じレコードへの書き換えは、届いた順に1つずつ処理します。矛盾は flow の
>で決めます。 - ルール同士の順番と強さは relate で決めます。
- 画面はレコードの変化を受けて自動で変わります。
- 実行には自前の実行エンジンを使い、spec を直接動かします。その後、WebAssembly に直接変換します。Go などほかの言語やライブラリには依存しません。
11.5 確定した細かいルール
| 何を | ルール |
|---|---|
within N days | 暦日。N日後の日付の終わり(23:59)まで。過ぎたものは入らない |
days until X | 日付だけで数える。今日なら0、過ぎていればマイナス |
| monthday | 年は推測しない。比べるときだけ今の年で読む |
| do の答え | どこからも使われていない行がちょうど1つ |
| action が値のない状態(missing など)を返した | 決められなかったとして else へ |
| 逃げ道 | action の else か relate の else のどちらか1つ。両方はエラー |
> が必要なとき | flow に分かれ道があれば必須(flow scene は除く) |
| 入れ子 | where の and / or / かっこ、match の中の match、子を持てない節の下の行、group の中の group |
| until の上限 | N times か N 時間 passed |
| why | 任意 |
| 人がきっかけでない rule | who に縛られず仕組みとして動く。人がきっかけの rule はその人の who に従う |
| input で作ったレコードの User の項目 | 作った人 |
| thing の形 | check --save-shape で残し、次から比べる |
| 編集 | input を with this で開くと編集。状態は書き換えられない(move だけ) |
| タップ | user taps X on thing の名前 ならどの一覧、ボード、詳細画面から押しても動く |
| ボタンの名前 | 1語。空白を含むなら引用符 |
| 画面の状態 | ブラウザ側で、見ている人ごとに持つ |
| 読み上げ対応の漏れ | 試作は注意、公開はエラー |
| AI の中身の置き場所 | x.ponte.ai/<action名>.ponte。人の spec に混ぜない |
## の承認 | 外せば承認、行ごと消せば却下 |
| AI の呼び方 | 依存ゼロのため、標準の urllib で API を直接呼ぶ |
12. ビルド手順
- 読む: spec を解析します。
- チェック: 13章のエラーをすべて確かめます。通らないと先に進めません。
- 組み立て: thing、flow、list、match、rule、relate、scene、look、style は、AI を使わない決まった変換で作ります。毎回同じ結果になります。
- 穴埋め: action の中身(by ai)と、style に書かなかった見た目だけを AI が決めます。
- 検証: すべての example と never を流します。通ったら完成です。通らなければ AI に書き直させます。
12.5 道具
| 使い方 | すること |
|---|---|
python -m ponte check x.ponte | 13章のエラーをすべて確かめる。--publish で公開するときの検査、--save-shape で thing の形を残す |
python -m ponte test x.ponte | rule と action の example、機械が確かめる never をすべて流す |
python -m ponte fill x.ponte | by ai の action の中身を AI に書かせる。通るまで問題を返して書き直させ、x.ponte.ai/ に残す |
python -m ponte fmt x.ponte | 誰が書いても同じ見た目に整える。意味が変わる場合は書き換えない |
python -m ponte run x.ponte | 動かす。ブラウザで画面が出る |
python -m ponte build x.ponte -o app.pyz | spec と中身と実行エンジンを1つのファイルにまとめる。python app.pyz で動く |
editor/vscode/ | エディタ(VS Code)で 14章の色分けを出す |
エラーは x.ponte:行 コード 中身 の形で出ます。エディタで押すと、その行へ移動できます。
13. エラー一覧(決めていないことはエラー)
| コード | 何が起きたか | なぜ止めるか | どう直すか |
|---|---|---|---|
| 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 名前 を、画像には説明を付けます。 |
E32 の中身は下に書きます。1つずつの説明は ponte explain E32 でも見られます。
警告
- W09(flow の状態の rule の抜け)と W26(試作中の読み上げ対応の漏れ)は警告です。
ponte testの穴さがし(9章)も警告です。--strictを付けると失敗になります。
E32 で確かめること
E32 では、まず rule ごとに this が何の thing かを決めます。when の on 〇〇 や 〇〇 is created から決め、relate の then の先の rule では前の rule から引き継ぎます。create の後は、作ったレコードが this になります。そのうえで、次のことを確かめます。
- 存在しない状態への move、存在しない項目への set、where、with、通知の {…}、状態を set で書き換えること(move を使います)
- 値の型:
set yen to me(number に User)/item me(Item に User)/ result の型(action の out から決まります) - this が決まらないのに this を使うこと、list の where の項目、stats の sum に数でない項目を使うこと
14. 色分け
| 種類 | 色 | 対象 |
|---|---|---|
| 見出し | 紫・太字 | thing flow list match rule relate action group tbd scene look part style input words who change connect |
| 節 | グレー | of where sort when do why in out example by how given expect |
| 守り | 赤 | never else > ## tbd who gone limit |
| 型 | 緑 | text number date monthday money [a | b] |
| 名前 | 青 | Application DueSoon Remind |
| 値 | 黄 | draft "…" 21:00 3 days |
| コメント | 薄グレー斜体 | # … |
| 止めるコメント | 赤の背景 | ## … |
| how / style | 背景グレー | どうやるかのまとまり |
赤は、安全装置が付いていることを示す色です。赤のないまとまりを見れば、守りが足りない可能性に気づけます。
15. 未決(次に決めること)
- 名前(候補は NAMES.md。Sadame / Tsumori / Hitoai)
- how と style に書ける語の完全な一覧
- パッケージ(この言語で書かれた group の共有)の形
- タイムゾーンの扱い(最初は tbd で宣言させる)
16. 変更の記録
16.1 v0.2 → v0.3 で入ったもの(v0.2 の追補をまとめたもの)
| 何 | 中身 | 場所 |
|---|---|---|
| rule の where | this が合わないとき、rule は静かに起きない。ボタンも押せない | 5章 rule |
| create の中身 | do create X の下に「項目 値」 | 5章 rule |
| 値の書き方 | this / me / "文字" / N days from now / {名前} / 項目 of this / result | 5章 rule |
項目 of this | move item of this to lent。指しているレコードを動かす | 5章 rule |
| set | do set yen to result。状態は move だけ | 5章 rule |
| with | do FindYen with memo。action の入力を項目から | 5章 rule |
| result | 直前の action の答え。答えがないときは静かに起きない | 5章 rule、9.5 |
| do の形の表と E31 | do の書き方を check で確かめる | 5章 rule、13章 |
| E32 型の確かめ | this の決め方、状態・項目・値の型 | 13章 |
| stats | 件数と合計 | 6章 |
| 画面の小さな部品 | tabs、detail、empty、tone、icon、confirm、lead、heading、search、group by、take、notices など | 6章 |
| 役割(role) | thing User の role、ponte role、where it is not me | 7.1 |
| 標準ライブラリ | std/date・std/money・std/contact | 9.5 |
| 穴さがし | example が確かめていないところを出す。--strict | 9章 |
| example の書き方 | adds / expect で thing の名前と中身を書く、expect no、expect 2、given で名前で指す、ない scene の shows は失敗 | 9章 |
名前 of X / text of X | shape の部分と当たった文字 | 10章 |
+ の強さ | + - は一番弱い | 10章 |
| 状態名と行名 | 同じならエラー | 10章 |
word with | shape の英数字と記号 | 10章 |
16.2 v0.1 → v0.2 の主な変更
| v0.1 | v0.2 |
|---|---|
| entity | thing |
| unknown | tbd |
one of [a, b] | [a | b] |
ref User / many User | User / list of User |
owner: ref User | owner User(: なし) |
on conflict A wins over B | A > B |
| otherwise | else |
| because | why |
| input / output | in / out |
| from / sort by | of / sort |
# proposed by ai | ## |
| derive / use(△) | 削除。action を do の中で呼ぶ |
| (なし) | relate、group、do、shape、ask ai、画面、who、change、gone、connect の設計、テストの3段 |
| 変換先は Go | 自前の実行エンジン → WebAssembly。依存ゼロ |
付録: 就活Hub(メール→締切→通知)を v0.3 で書いたもの
thing Application company text deadline monthday owner User gone[remove too] status [draft | submitted | passed | failed] thing User name text flow Application.status draft -> submitted -> passed | failed failed > passed who user can see Application where owner is me user can change Application where owner is me user can see User where it is me list DueSoon of Application where status is draft where deadline within 3 days sort deadline match Application.status to color draft -> red submitted -> gray passed -> blue failed -> gray connect Gmail gives new message Message needs key GMAIL_TOKEN action ExtractDeadline in mail text out found monthday | missing example "10/15(木)12:00まで" -> found 10/15 12:00 example "【締切9/24 23:59】" -> found 9/24 23:59 example "来週中にご提出ください" -> missing example "9/24 23:59 または 9/30 23:59" -> missing never guess the year else ask user by ai rule ReadMail why メールの締切を自動で拾うため when Gmail gives new message do ExtractDeadline rule Remind why 締切を落とさないため when every day at 21:00 do notify owner each of DueSoon example given Application company "Osaka Gas" deadline "9/24 23:59" status draft at "9/21 21:00" expect notify "Osaka Gas" rule MarkSubmitted when user taps submitted-button on DueSoon do move this to submitted example given Application company "Osaka Gas" status draft taps submitted-button on Application company "Osaka Gas" expect Application is submitted company "Osaka Gas" relate MarkSubmitted > Remind scene Home top Header main match count of DueSoon 0 -> EmptyNote else -> DueSoon as cards bottom button add named 追加 flow scene Home -> AddApplication part Header show text "就活Hub" part EmptyNote show text "3日以内に締切の下書きはありません" look DueSoon as cards title company sub deadline mark color of status button submitted-button named 提出した input AddApplication company required deadline required style DueSoon card round 12, shadow soft, pad 16 title size 18, bold tbd timezone of deadline
※ 付録には tbd が残っているので、このままでは「止まります」になります。これは意図したとおりです。
v0.3 整理メモ
動かしたところ
- rule の追補(where、create の中身、項目 of this、set、with、E31)に合わせて、rule の節を when / where / do / 値 に分けました。do の形と値は、それぞれ1つの表にまとめました。
- 「画面のための追補」は、6章「画面の小さな部品」に移しました。
- 「件数と合計」は 6章に置いたまま、見出しから「追補」を外しました。
- 役割は、7.1 の who の中に並べました。
- 穴さがしと example の書き方は、9章の本文に入れました。出来事と結果の一覧には adds / expect(thing の名前)/ expect no / expect 2 を加えました。
- 標準ライブラリは 9.5 に置き、追補の見出しを外しました。
- 10章の追補(名前 of X、+ の強さ、状態名と行名、word with)は、10章の箇条書きにしました。
- 13章は、v0.1 / v0.2 の区切りを外して 1〜32 の番号順に並べました。32 の中身は下の箇条書きに移し、警告は別に書きました。
- 16章は、16.1「v0.2 → v0.3 で入ったもの」と 16.2「v0.1 → v0.2 の主な変更」に分けました。
- 「(v0.2)」の印はすべて外しました。
ぶつかっていたところとコードに合わせたところ
- 通知の宛先: v0.2 の本文には
notify meとnotify owner each of 一覧の2つしかありませんでした。コード(DO_FORMS)はnotify 項目 "..."(例notify borrower "...")も通すため、コードに合わせました。 - go: 本文には
go Detail with thisしかありませんでしたが、コードはgo 画面も通します(kakeibo のgo AddExpense)。両方を書きました。 - 期間の値: 追補には
7 days from nowしかありませんでしたが、コードは minutes / hours / days / weeks を通します。コードに合わせました。 - 値の書き方: コードは、表の値のほかに、ただの語や数(状態の名前、数など)も値として通します。表には書いていません(ルールとしては変えていません)。
- 役割のエラー: who の役割は、
user、nobody、User の role の状態のどれかです。コード(check_roles)どおり E28 としました。 - E28 の対象: コードは、create にない項目、stats の書き方、who の役割も E28 で出します。そのため 13章の 28 に加えました。stats の sum が数でないときは E32 です。
- E25: 本文(6章 words)には「画面の文字が words になければエラー(25)」とあります。13章の 25 は訳がないことだけを扱っていたので、両方を 25 に書きました。
- 13章の 26 は、v0.2 で「公開するときだけエラー、試作中は警告」でした。6章「読み上げ対応」と同じ意味のため、変えていません。
- 9 は v0.2 でも警告でした。番号は残し、警告の欄にも書きました。