仕様書 v0.3 — Ponte

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つのパーツには1つの仕事だけを持たせます。複雑さはパーツを増やして出すのではなく、組み合わせで出します。
  2. 「何を」は必須、「どうやるか」は任意です。どうやるかは how と style にだけ書けます。書かなければ実行エンジンの標準の動きになり、書いたらその通りにしか作れません。
  3. 順序は書きません。並列が標準です。thing の1件は、それぞれ独立した1つのレコードです。レコードをまたぐ処理はすべて並列に、同じレコードの中の処理は1つずつ行います。順序が必要なときは、flow(状態)か relate(ルールの関係)で表します。
  4. 決めていないことはエラーになります。曖昧なまま渡すことはできません。
  5. 入れ子は禁止です。条件の中に条件を書かず、名前を付けて段階的に積み上げます。
  6. 何でも作れますが、危ないことは action の中身に閉じ込めます。外側(仕様と契約)は絞り、内側(action の中身)は契約を守れば何を書いてもかまいません。
  7. 同じ意味の語は1つだけにします。else はどこでも「逃げ道」、do はどこでも「やること」を表します。> はどこでも「ぶつかったらこちらが勝つ」、| はどこでも「どれか1つ」を表します。

2. 型

型意味
text文字
number数
count0以上の整数
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 lentthis の 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 memoaction を呼ぶ。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 thisthis の項目の値
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 BA が終わったら B が動く
A then no BA をやったら、この後 B は動かない。B がすでに済んでいても取り消さない
A before BB が動くとき、A は済んでいる。A が終わっても B は勝手に動かない
A > B同時に当てはまったら A が勝つ
A else BA が失敗したら 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つでも欠ければ、そのモデルは使えないものとして扱います。

  1. 学んだ結果がある。
  2. 学んだときの定義の印が、今の定義と同じ。
  3. 取り置いたレコードでの正解率が require 以上。
  4. 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
  • 言語が出す文字(search save cancel none)も、words で訳せます。
  • words がない spec では、画面の文字を直接書けます。

読み上げ対応

  • 名前のないボタン(named がない)と、説明のない画像(about がない)は、試作の間は注意になり、公開するときはエラーになります。

画面の小さな部品

画面を作り込むために足した小さな部品です。どれも1つの仕事だけを持ちます。

書き方意味
main tabs tab画面の状態 tab[...] を切り替えるタブを出す
main this as detail前の画面で押された1件を詳しく見せる
look Application as detailthing の名前の 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 thisinput を 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/dateFindMonthDayfound monthday(年は推測しない)/ missing
use std/dateFindDatefound date(年が書いてある日付だけ。13月などありえない日付は missing)/ missing
use std/moneyFindYenfound number(¥ が前でも 円 が後ろでも、全角でも読む)/ missing
use std/contactFindEmail / FindPhone / FindPostalfound 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 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')
数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任意
人がきっかけでない rulewho に縛られず仕組みとして動く。人がきっかけの 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. ビルド手順

  1. 読む: spec を解析します。
  2. チェック: 13章のエラーをすべて確かめます。通らないと先に進めません。
  3. 組み立て: thing、flow、list、match、rule、relate、scene、look、style は、AI を使わない決まった変換で作ります。毎回同じ結果になります。
  4. 穴埋め: action の中身(by ai)と、style に書かなかった見た目だけを AI が決めます。
  5. 検証: すべての example と never を流します。通ったら完成です。通らなければ AI に書き直させます。

12.5 道具

使い方すること
python -m ponte check x.ponte13章のエラーをすべて確かめる。--publish で公開するときの検査、--save-shape で thing の形を残す
python -m ponte test x.ponterule と action の example、機械が確かめる never をすべて流す
python -m ponte fill x.ponteby 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.pyzspec と中身と実行エンジンを1つのファイルにまとめる。python app.pyz で動く
editor/vscode/エディタ(VS Code)で 14章の色分けを出す

エラーは x.ponte:行 コード 中身 の形で出ます。エディタで押すと、その行へ移動できます。

13. エラー一覧(決めていないことはエラー)

コード何が起きたかなぜ止めるかどう直すか
E01match に else がない書いていない値が来たときに、何をするかが決まっていないためです。最後に else -> 結果 を書きます。宣言した状態をすべて書いた場合、else は不要です。
E02until に上限がない終わらない可能性のある待ちは、アプリを止めてしまうためです。repeat ... until 〇〇 or 1 hour passed のように、回数か時間の上限を書きます。
E03action の example が2つ未満例が1つだけでは、中身(自分で書いても AI が書いても)が正しいかを確かめられないためです。当たる例と当たらない例(-> missing など)を、少なくとも1つずつ書きます。
E04action に else がないaction の中身が答えを出せなかったときの動きが必要なためです。else skip や else ask user のように、答えが出なかったときの動きを書きます。
E05tbd が残っている決まっていないことを残したまま動かすと、その部分を誰かが推測で決めてしまうためです。内容を決めて tbd を消します。決められない場合は、その部分を使わない形に書き換えます。
E06## が残っている## は、書いた人が確認を保留している箇所を示す印です。内容を確かめてから、## を消すか #(通常のコメント)に変えます。
E07when に状態を書いている「期限が近い」のような状態は、いつ起きるかが決まっていないためです。when には出来事(every day at 8:00 や user taps ...)を書き、状態は where か list で絞り込みます。
E08move の対象が絞り込まれていないどの1件を動かすかが決まらないまま、複数のレコードがまとめて動いてしまうためです。move this to 状態 にするか、list で1件に絞り込みます。
E10競合する move の優先順位が決まっていない同じ1件に異なる move が同時に届いたとき、どちらを優先するかが決まらないためです。flow に failed > passed のように優先順位を書きます。
E11list の参照が循環しているA の元が B で、B の元が A だと、中身が決まらないためです。どちらかを thing から直接絞り込む形に変えます。
E12入れ子入れ子は読み違えやすいため、1段で書く決まりにしています。内側の部分に名前を付けて外に出し、その名前を使います。
E13action の約束が食い違っているexample の答えや never が out の形に合っていないと、確かめることができないためです。out に書いた形(found monthday | missing など)に合わせて、example と never を書き直します。
E14relate の then / before が循環しているA の後に B、B の後に A が動くと、処理が終わらないためです。どこかの then を外すか、条件付きの rule に分けます。
E15relate の優先順位が双方向になっているA > B と B > A が両方あると、どちらも優先されないためです。どちらか一方だけを残します。
E16before の前の rule が起きないA before B と書いても A が起きる経路がなければ、B はいつまでも起きないためです。A のきっかけ(when)を書くか、before を外します。
E17失敗したときの動きが2つあるaction の else と relate の else が両方あると、どちらが動くかが決まらないためです。どちらか1つにします。
E18match に宣言されていない状態がある宣言にない状態の枝は、打ち間違いであることが多いためです。宣言にある状態名に直すか、宣言に状態を追加します。
E19who がない thing がある書いていない操作は誰にもできない決まりのため、このままでは誰も見ることができません。who に user can see Thing where ... などを書きます。
E20他のレコードを指す項目に gone がない指している先が消えたときに、こちらのレコードをどうするかが決まっていないためです。gone[remove too]、gone[leave empty]、gone[block] のいずれかを付けます。
E21thing の形を変えたのに change がない保存済みのデータを新しい形にどう合わせるかが、決まっていないためです。change Thing to v2 に、追加した項目の初期値(add memo text = )や名前の変更を書きます。
E22ask ai に上限がないAI への問い合わせが止まらないと、費用と時間がかかり続けるためです。how に時間か費用の上限(limit 5 seconds や limit 1 yen)を書きます。
E23connect が失敗したときの動きがない外部サービスは失敗することがあり、そのときの動きが決まっていないためです。relate に rule名 else 〇〇 を書きます。
E24flow scene にない画面の移動画面の移動も flow と同じく、書いた経路しか通れないためです。flow scene に矢印を追加するか、移動先を直します。
E25words の訳が足りない一方の言語だけ文字が欠けていると、その言語の利用者に意味が伝わらないためです。words ja と words en の両方に、同じ名前で書きます。1つの言語だけのアプリでは、words を書かずに "文字" と直接書くこともできます。
E26名前のないボタンまたは説明のない画像読み上げ機能の利用者に、ボタンの役割が伝わらないためです。公開するときだけエラーになります。ボタンには named 名前 を、画像には説明を付けます。
E27通貨の異なる money の足し算円とドルをそのまま足すと、意味のない数になるためです。同じ通貨どうしで足すか、通貨ごとに分けて表示します。
E28定義されていない名前、または知らない言葉存在しない部品、list、項目、アイコンを指したり、節や操作の言葉を打ち間違えたりすると、その行は無視されます。書いたつもりの動きが起きないため、エラーにします。エラーに表示された「もしかして」の名前に直すか、定義を追加します。
E29rule に 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 の wherethis が合わないとき、rule は静かに起きない。ボタンも押せない5章 rule
create の中身do create X の下に「項目 値」5章 rule
値の書き方this / me / "文字" / N days from now / {名前} / 項目 of this / result5章 rule
項目 of thismove item of this to lent。指しているレコードを動かす5章 rule
setdo set yen to result。状態は move だけ5章 rule
withdo FindYen with memo。action の入力を項目から5章 rule
result直前の action の答え。答えがないときは静かに起きない5章 rule、9.5
do の形の表と E31do の書き方を 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 me7.1
標準ライブラリstd/date・std/money・std/contact9.5
穴さがしexample が確かめていないところを出す。--strict9章
example の書き方adds / expect で thing の名前と中身を書く、expect no、expect 2、given で名前で指す、ない scene の shows は失敗9章
名前 of X / text of Xshape の部分と当たった文字10章
+ の強さ+ - は一番弱い10章
状態名と行名同じならエラー10章
word withshape の英数字と記号10章

16.2 v0.1 → v0.2 の主な変更

v0.1v0.2
entitything
unknowntbd
one of [a, b][a | b]
ref User / many UserUser / list of User
owner: ref Userowner User(: なし)
on conflict A wins over BA > B
otherwiseelse
becausewhy
input / outputin / out
from / sort byof / 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 でも警告でした。番号は残し、警告の欄にも書きました。