clojure.spec - 根拠と概要

Clojureは動的言語です。とりわけ、これはコードを実行するために型アノテーションが必須ではないことを意味します。Clojureには型ヒントのサポートがありますが、それは強制メカニズムではなく、包括的でもなく、効率的なコード生成を支援するためにコンパイラーに情報を伝達することに限定されています。Clojureは、JVM自体によって、より豊富な型のランタイムチェックを行います。

しかし、Clojureの指導原理であり、コミュニティによって広く尊重され、実践されてきたのは、情報を単純にデータとして表現することでした。したがって、Clojureシステムの重要なプロパティは、ランタイム型が区別できない異種マップやベクターであるため、データの形状やその他の述語的プロパティによって表現および伝達されますが、どこでもキャプチャまたはチェックされません。

ドキュメント文字列は、人間の利用者に伝えるために使用できますが、プログラムやテストで活用することはできません。つまり、その力は最小限です。ユーザーは、より強力な仕様を取得するために、SchemaやHerbertなどのさまざまなライブラリに頼ってきました。

構造を仕様化するためのほとんどのシステムは、キーセット（例えば、マップ内のキー、オブジェクト内のフィールド）の仕様を、それらのキーによって指定された値の仕様と混同しています。つまり、そのようなアプローチでは、マップのスキーマは、:a-keyの型はx-typeで、:b-keyの型はy-typeであると言うかもしれません。これは、硬直性と冗長性の主な原因です。

Clojureでは、マップを動的に構成、マージ、構築することで力を得ています。オプションおよび部分的なデータ、信頼性の低い外部ソースによって生成されたデータ、動的なクエリなどを日常的に扱います。これらのマップは、同じキーのさまざまなセット、サブセット、インターセクション、および和集合を表しており、一般的に、使用される場所に関係なく、同じキーには同じセマンティクスが必要です。すべてのサブセット/和集合/インターセクションの仕様を定義し、各キーのセマンティクスを冗長に記述することは、アンチパターンであり、最も動的なケースでは機能しません。

多くのユーザー、特に初心者は、手書きの解析コードとデストラクチャリングコードによって生成されるエラーメッセージ、特にマクロでは実行の2つのコンテキスト（マクロはコンパイル時に実行され、その展開はランタイム時に実行され、どちらもユーザーエラーが原因で失敗する可能性があります）によって、不満を感じ、困難に直面しています。これにより、「マクロ文法」の要求が生じましたが、実際にはマクロは単なるdata→dataの関数であり、データ検証とデストラクチャリングのソリューションは、他の関数と同様にそれらにも機能するはずです。つまり、マクロは上記の問題のインスタンスです。

最後に、動的かどうかにかかわらず、すべての言語で、テストは品質にとって不可欠です。多くの重要なプロパティは、一般的な型システムではキャプチャされません。しかし、手動テストは、効果/労力の比率が非常に低いものです。Clojureでtest.checkに実装されているように、プロパティベースのジェネレーティブテストは、手動で作成されたテストよりもはるかに強力であることが証明されています。

しかし、プロパティベースのテストでは、プロパティの定義が必要であり、プロパティの作成には追加の労力と専門知識が必要であり、関数レベルでは、関数仕様と実質的に重複しています。関数レベルの多くの興味深いプロパティは、構造的+述語的な仕様によってすでにキャプチャされているはずです。理想的には、仕様はジェネレーティブテストと統合し、「無料」で特定のカテゴリのジェネレーティブテストを提供する必要があります。

つまり、Clojureには、仕様とテストのための標準的で表現力があり、強力で統合されたシステムがありません。

clojure.specはそれを提供することを目指しています。

仕様は、何かがどのように「見える」かについてのものですが、最も重要なのは、見られるものであるということです。仕様は、読みやすく、プログラマーがすでに使用している「単語」（述語関数）で構成され、ドキュメントに統合されている必要があります。

データ構造、属性値、および関数の仕様はすべて同じである必要があり、グローバルに名前空間が設定されたディレクトリに存在する必要があります。

仕様を作成すると、自動で以下が可能になるはずです。

人々に関数を別の方法で定義させることを要求しないでください。docとmacroexpandにわずかな変更を加えることで、再定義することなく、独立して書かれた仕様がfn/マクロの動作を飾ることができます。

マップ（キーセット）の仕様を、属性（キー→値）の仕様とは別に保持します。名前空間付きのキーワードから値の仕様への属性粒度の仕様を奨励およびサポートします。キーをセット（マップを指定するため）に結合することは直交になり、チェックは完全に動的なケースでも可能になります。つまり、マップ仕様が存在しない場合でも、属性（キーと値）をチェックできます。

プログラマーは、名前を同じに保ちながら定義し直すと、大きな苦痛を味わいます。しかし、いくつかの変更には互換性があり、いくつかの変更は破壊的であり、ほとんどのツールは区別できません。互換性を判断できる集合メンバーシップや正規表現などの構成を使用し、（一般的な述語の等価性を範囲外に残しながら）互換性チェックのためのツールを提供します。

私たちは間違いを犯すことができない世界に住んでいません（そして住むこともできません）。代わりに、定期的に間違いを犯していないことを確認します。Amazonは、UPS<Trucks<Boxes<TV>>>を使用してテレビを送信することはありません。そのため、時々電子レンジを入手する可能性がありますが、サプライチェーンは正しさの証明で負担をかけられていません。代わりに、エッジで確認し、テストを実行します。

仕様を証明できるものに制限する理由はありませんが、それが主に型システムが行うことです。システムについて伝達し、検証したいことはたくさんあります。これは、構造的/表現的な型やタグ付けを超えて、例えば、ドメインを絞り込んだり、入力間または入力と出力の関係を詳しく述べたりする述語にまで及びます。さらに、私たちが最も気にするプロパティは、多くの場合、静的な概念ではなく、ランタイムの値のプロパティです。したがって、specは型システムではありません。

すべてのプログラムは、型システムがない場合でも名前を使用し、重要なセマンティクスをキャプチャします。Int x Int x Intは十分ではありません（長さ/幅/高さまたは高さ/幅/奥行きですか？）。したがって、specには、ラベルのないシーケンスコンポーネントやタグのない共用体バインディングはありません。このユーティリティは、specがユーザーに仕様について伝える必要がある場合（例えば、エラーレポートの場合）、また、ユーザーが仕様のジェネレーターをオーバーライドしたい場合（逆も同様）に明らかになります。すべてのブランチに名前が付けられている場合、パスを使用して仕様の一部について話すことができます。

Clojureは名前空間付きのキーワードとシンボルをサポートしています。ここで、Clojureの名前空間オブジェクトではなく、名前空間修飾名についてのみ話していることに注意してください。これらは悲劇的に十分に活用されておらず、辞書/データベース/マップ/セットで競合することなく常に共存できるため、重要な利点をもたらします。specでは、名前空間修飾されたキーワードとシンボル（のみ）を使用して仕様に名前を付けることができます。情報マップに名前空間付きのキーを使用している人々（私たちが成長を望む実践）は、それらの名前で直接それらの属性の仕様を登録できます。これにより、特に動的なコンテキストで、マップの自己記述がカテゴリー的に変更され、構成と一貫性が促進されます。

var、メタデータなどには何も添付されません。すべての関数には名前空間付きの名前があり、他の場所に保存されている関連データ（例：仕様）へのキーとして使用できます。

Lisps（そしてClojure）では、コードはデータです。しかし、データは、その周囲に言語を定義するまでコードにはなりません。この分野の多くのDSLは、スキーマのデータ表現を目指しています。しかし、述語的な仕様にはオープンで大きな語彙があり、有用な述語のほとんどはすでに存在し、コアや他の名前空間の関数としてよく知られており、または単純な式として記述できます。これらの述語をすべて「データ化」し、場合によっては名前を変更することは、価値がほとんどなく、正確なセマンティクスを理解する上で明確なコストがかかります。代わりに、specは、元の述語と式がそもそもデータであるという事実を活用し、ドキュメントやエラー報告でユーザーと通信するためにそのデータをキャプチャします。はい、これはclojure.specの表面領域の多くがマクロになることを意味しますが、仕様は圧倒的に人が作成し、構成される場合は手動で行われます。

上記のように、キーの値の詳細を定義するマップは、サポートされない懸念事項の根本的な複雑化です。マップ仕様は、必須/オプションのキー（つまり、集合のメンバーシップに関するもの）を詳細に記述し、キーワード/属性/値のセマンティクスは独立しています。マップのチェックは2段階で行われ、まず必須キーの存在を確認し、次にキー/値の適合性を確認します。後者は、実行時に存在する（名前空間修飾された）キーがマップ仕様にない場合でも実行できます。これは、構成と動的性のために非常に重要です。

必然的に、人々は実装上の決定を詳細に記述するために仕様システムを使用しようとしますが、それは彼らの損失になります。最も良く、最も役立つ仕様（およびインターフェース）は、純粋に情報的な側面に向けられています。情報仕様のみが、ワイヤーを介して、およびシステム全体で機能します。私たちは常に情報アプローチを優先し、矛盾がある場合はそれを優先します。

この分野には非常に少ない基本的な概念があり、それらに固執するように努めます。明確な構造的概念はわずかです。少数のアトミック型、シーケンシャルなもの、集合、マップです。当然のことながら、これらはClojureのデータ型であり、基本的な操作はこれらに対してのみ提供されます。同様に、これらについて説明するための数学的なツールがあります。マップの集合論とシーケンスの正規表現は、価値のある特性を持っています。私たちは、アドホックなソリューションよりもこれらを優先します。

specの生成的なテストの基盤はtest.checkを活用し、それを再発明しません。しかし、specのユーザーは、独自のジェネレータを作成したり、specが生成したテストを独自のプロパティベースのテストで補強したりする場合を除き、test.checkについて何も知る必要はありません。test.checkへの本番環境でのランタイム依存関係は存在しないはずです。

仕様を定義するための主な操作は、s/def、s/and、s/or、s/keys、および正規表現演算子です。述語関数または式、セット、または正規表現演算子を受け取ることができるspec関数があり、述語によって暗示されるジェネレータをオーバーライドするオプションのジェネレータも受け取ることができます。

ただし、def、and、or、keysのspec関数と正規表現演算子はすべて、述語関数とセットを直接使用でき、specでラップする必要はありません。specは、ジェネレータをオーバーライドするか、ネストされた正規表現が同じパターンに含まれるのではなく、新たに開始することを指定する場合にのみ必要になります。

spec API の多くの部分で、「述語」または「preds」が要求されます。これらの引数は以下によって満たすことができます。

正規表現内に独立した正規表現述語をネストしたい場合は、spec の呼び出しでラップする必要があることに注意してください。そうしないと、ネストされたパターンと見なされます。

spec, and, or, および keys の戻り値。

cat, alt, *, +, ?, & の戻り値。ネストすると、これらは単一の式を形成します。

conform はスペックを使用するための基本的な操作であり、検証と適合/デストラクチャリングの両方を行います。適合は「深い」ものであり、スペックと正規表現操作、マップスペックなどをすべて通過することに注意してください。nil と false は正当な適合値であるため、値を適合させることができない場合、conform は区別された :clojure.spec.alpha/invalid を返します。valid? は完全なブール値述語として代わりに使用できます。

値がスペックに適合しない場合、同じスペック+値で explain または explain-data を呼び出して理由を確認できます。これらの説明は、追加の作業を実行する可能性があり、失敗しない入力やレポートが不要な場合にそのコストを負担する理由がないため、conform 中には生成されません。説明の重要な要素は _パス_ です。explain は、例えばネストされたマップや正規表現パターンをナビゲートする際にパスを拡張するため、全体またはリーフの値だけでなく、より良い情報を取得できます。explain-data は、問題へのパスのマップを返します。

スペックのすべての _分岐_ 点は、マップの keys、or と alt の選択、および (場合によっては省略される) cat の要素など、ラベル付けされているため、スペックのすべての部分式は、パーツの名前を付ける _パス_ (キーのベクター) を介して参照できます。これらのパスは、explain、gen のオーバーライド、およびさまざまなエラーレポートで使用されます。