processObjectTypeParameterOfPugMixin

Pugミックスイン のオブジェクト型の引数の、妥当性を確認し、処理を行う。

此の様な機能は、GUIコンポーネントや其の他のマークアップの断片においては Pugミックスインとして実装されており、但し、設定可能なプロパティが多数有る為、 正しいHTMLコードが生成されるには、一部分又は全てのプロパティが特定の制限を満たさなければならない時に、需要が有る。

問題の考察

Pugと言うHTMLプリプロセッサは、内部JavaScript と同様に静的型付き言語ではない。 引数を持つPugミックスインを利用する場合、渡された引数に不備が有っても( 引数の数、又は型等)、開発者には事前に 知らされない。 PugからHTMLへの変換中にエラーが起きても、具体的に何処にどんな不備が有ったか、 明かにされるとは限らないし、単にエラーが示される事なく期待していたものと違うHTMLコードが生成される事も有り、 気付く迄には長い時間が経つ事も多い。 特に、自分で開発したミックスインではなく、第三者が開発した場合に危険であり、Pugミックスインに依り GUIコンポーネントが実装される場合を含む。

簡単な解決策としては、純粋（第三者ライブラリを使わない）なJavaScriptを利用し、 引数の型や文字数、数の集合等を確認する事である。

mixin Example(foo, bar, baz)

  -

    if (typeof foo !== "string") {
      throw new Error(
        `「Example」ミックスインの１引数目は文字列でなければならないが、実際は「${ typeof foo }」型に成っている。`
      );
    }

    if (foo.length < 2) {
      throw new Error("「Example」ミックスインの１つ目の引数は、少なくとも２文字でなければならない。");
    }

    if (typeof bar !== "number") {
      throw new Error(
        `「Example」ミックスインの２つ目の引数は数値でなければならないが、実際は「${ typeof bar }」型に成っている。`
      );
    }

    if (!Number.isInteger(bar)) {
      throw new Error("「Example」ミックスインの２つ目の引数は、整数でなければならない。");
    }

    if (bar < 10) {
      throw new Error(
        `「Example」ミックスインの２つ目の引数は${ bar }という値だが、最低限10でなければならない。`
      );
    }

    if (typeof baz !== "boolean") {
      throw new Error(
        `「Example」ミックスインの３つ目の引数はブール値でなければならないが、実際は「${ typeof bar }」型に成っている。`
      );
    }

御覧になれば御分かりの様に、たった３件の引数の妥当性確認でも、Pugミックスインのコードは可成り大きな一部分であり、 此処でのエラーメッセージはで、他のミックスインにもほぼ同じ本文を打ち込まざる得ない。 引数の数が３ではなく、１０以上ある場合は、どう成るだろうか？ 似た様なミックスインが数十ある場合は、どう成るだろうか？ 此の様な状態が完全に実践的で、平均的なウェブアプリケーションにとって 20~30個のGUIコンポーネントは普通であり、 然もプロパティに依り高度な設定が常に求められるので、上記の様に「手動で」引数の妥当性を確認するには、時間、精神力がかかりすぎるし、コードの行数も多すぎるのだ。

此処で、引数の妥当性確認に共通する、仕組みの課題が出現する。 此の様な仕組みは、引数及びこれ等のプロパティを検査しなければならず、不備が有る時には１件目の違反だけで なく、全ての違反を詳しく記録しなければならない。 然し、Pugミックスインの利用者の[+Keyphrase--YDID 説明書に必要な参考情報を探す為に、時間をかけずに]、 自力で不備が直せる程度の分かりやすいターミナルの出力でなければいけない。

YDFの解決

YDEEとの結合 、特にRawObjectDataProcessorクラス を利用して、processObjectTypeParameterOfPugMixin関数が開発された。 関数名を直訳すれば分かる通り、当関数はPugミックスインの 単一のオブジェクト型の引数を処理する。

但し、上記のExample(foo, bar, baz)例の様に、何れの型の、何れの 引数の数を処理する関数は開発されなかった。 理由としては、多数の引数のミックスイン（関数も同じ）は、 整備にも利用にも問題が有る為だ。 例えば+Example("top", 2, false)では、2と falseがどういう意味に成っているかは、読むだけでは分からず、結合開発環境がヒントを表示しても GitHubの様なサービスでのコードレビュー中には、此の様なヒントは表示されない（しかも、Pugミックスインの 引数の名前を表示するコーディネーター、結合開発環境やプラグインが存在するとは限らない）。 幸いにもJavaScript系の構文であるPugでは解決が非常に簡単であり、複数の引数を オブジェクト型の１個に結合できる。

mixin Example(compoundParameter)

const { foo, bar, baz } = compoundParameter;

上記の例では分割代入を利用し、単一のオブジェクト型の 引数の全てのプロパティは個別の 定数に抽出され、まるで最初から個別の引数であったかの様に使える様に成った。 processObjectTypeParameterOfPugMixinを使う場合、分割代入の対象は 引数自体ではなく、当関数の返す値である。

mixin Example(compoundParameter)

  const {
    foo,
    bar,
    baz
  } = processObjectTypeParameterOfPugMixin({
    rawParameter: compoundParameter,
    parameterNumber: 1,
    parameterName: "compoundParameter",
    parameterPropertiesSpecification: {
      foo: {
        type: String,
        required: true,
        minimalCharactersCount: 2
      },
      bar: {
        type: Number,
        numbersSet: RawObjectDataProcessor.NumbersSets.nonNegativeIngeter,
        required: true,
        minimalValue: 10
      },
      baz: {
        type: Boolean,
        required: true
      }
    },
    mixinName: "Example"
  });

御覧になれば分かる通り、此の関数も単一のオブジェクト型 の引数を受ける。 単一に成っている理由は、上記で説明されたPugミックスインと同じ。 プロパティの中にrawParameterと言うものが有り、値はPugミックスインの 特定の引数である（上記の例だと、１個しか無い）。 其の他の重要なプロパティはparameterPropertiesSpecificationで、 妥当性確認の規則であり、必要に応じて規定値の代入の様に処理の指示が出来る。

parameterPropertiesSpecificationプロパティはObjectSubtypes.fixedKeyAndValuePairsObject 型である。 実際には、此れは連想配列型のオブジェクトであり、此のキーは Pugミックスインの引数のキーと一致 しなければいけない。

残る３個のプロパティ、即ちparameterNumber、 parameterNameとmixinNameは、記録の為 だけに必要だが、指定しないと、問題が何処に起きたのか分からなく成る恐れが有るため、重要なプロパティとして丁寧に 埋めるべきである。

単一引数のプロパティ

rawParameter：ミックスイン実行時点のミックスイン引数

初期状態のPugミックスインの引数。

• 此処で「raw」（「生の」）は、対象の引数が、規定値の代入の様に、未だ手が付けられていない事を意味する。
• オブジェクト型でなければならず、 さもなくば妥当性確認が直ぐエラーで停止する。 唯一の例外は、 parameterPropertiesSpecificationに全プロパティが 任意のプロパティとして指定されている場合。 此の場合、対象の引数がundefined型に成っていても（つまりミックスイン 呼び出しの際指定されていない）、processObjectTypeParameterOfPugMixinは空の オブジェクトを確保してくれる。

mixin Example(compoundParameter)

const {
  foo,
  bar
} = processObjectTypeParameterOfPugMixin({
  rawParameter: compoundParameter,
  parameterNumber: 1,
  parameterName: "compoundParameter",
  parameterPropertiesSpecification: {
    foo: {
      type: String,
      required: false,
      minimalCharactersCount: 2
    },
    bar: {
      type: Number,
      numbersSet: RawObjectDataProcessor.NumbersSets.nonNegativeIngeter,
      defaultValue: 10
    }
  },
  mixinName: "Example"
});

parameterPropertiesSpecification：—単一の引数のプロパティの仕様

ObjectSubtypes.fixedKeyAndValuePairsObject 形式の対象のミックスイン引数の妥当性についての規則と、必要であれば、処理の規則の定義。 実際には連想配列型のオブジェクトで、此のキーは対象のミックスイン 引数のキーと一致しなければならない。

ObjectSubtypes.fixedKeyAndValuePairsObject連想配列には多数の様々 なオプションが有るが、各プロパティにとって少なくとも、型 (type)と必須（required）の指定が 必要である。 但し、規定値を確保したい場合は、requiredの代わりに defaultValueを指定する事。 より詳しくは、「RawObjectDataProcessor」の説明を参考にすること。

残念ながら、Pug内で使われているのはTypeScriptではなく、 JavaScriptである為、妥当性の確認規則を指定する際、間違いやすくなる。 其の為、関数が正しく稼働しなくなく成る恐れが有り、間違いの発見に時間がかかる事が有る。 とは言え、parameterPropertiesSpecificationの利用に意味が無い訳ではなく、 妥当性を確認する事は、妥当性を確認しない事よりずっと良い。parameterPropertiesSpecificationであれば、 原型コードの量が可成り減る。 妥当性確認の規則を指定する際、間違いの可能性を減らすには、TypeScriptファイルで ObjectSubtypes.fixedKeyAndValuePairsObject型の変数を定義し、 全てのプロパティを指定した上で、Pugに貼り付けすれば良い。

ロギング変数：parameterNumber、parameterName、mixinName

妥当性違反が有る場合に、これ等の記録の為だけに使われている。 ミックスイン引数の番号（parameterNumber）は 自然数でなければならず、残る２個は文字列 でなければならない。

例えば、{ parameterNumber: 1 }、 { parameterName: "properties" }と { mixinName: "Badge--YDF" }の時、出力は下記の様に成る。

  4| mixin Badge--YDF(properties)
  5|
> 6|   -
  7|
  8|     const {
  9|

Invalid parameter value
Object-type parameter No. 1 (named as "properties") of the Pug mixin "Badge--YDF" has one or more invalid properties:

(...)

「IntelliJ IDEA」ファミリー統合開発環境に於ける高速入力

「IntelliJ IDEA」ファミリー の統合開発環境のLive templates 機能利用の恩恵に依り、関数呼び出し表現等の入力速度が向上する。 YDFのライブテンプレートを取得するには、当ライブラリの正式プラグイン を導入する必要が有る。

Live Templateの利用手順

ライブテンプレートを使った事が無い場合でも、充実した内容の手順書が下記にある為、心配は無用である。 ライブテンプレートに慣れてしまえば、（キーボードのショートカット利用と同じ様な習慣）僅か数秒程度で下記の操作を行える。

当ライブテンプレートを使用する前に、引数の指定を含めてPugミックスインを宣言しなければいけない。 尚、Pugミックスイン内ではJavaScriptブロック を用意しなければならず、今後の作業は此の中で行われる事に成る。

1. processObjectTypeParameterOfPugMixin関数名の入力を始めて下さい。 現在のPug言語の対応だと、プロジェクトのファイル（node_modulesを含めずに） の中に無ければ、processObjectTypeParameterOfPugMixin関数について 知らない可能性が高いので、オートコンプリートを１つだけ提供してくれるはずです。 とは言え、もし同じ名前のオートコンプリートが２つ出現したら、印鑑のアイコンが含まれているものを選んで下さい。
2. rawParameterプロパティに該当するミックスインの 引数への参照を指定して下さい。 propertiesと言う名前が提案されますが、此方のミックスインならば、 引数の名前は異なるでしょう。 終わり次第、Enterを押して下さい。
3. parameterNumberプロパティに該当するミックスインの 引数の番号を指定して下さい。 1から3迄の番号をドロップダウンで選択する様に提案され、 引数が此の範囲に有る場合は、矢印キーを使って選択し、Enterを押して下さい。 若しくは、対象の引数が4以上の番号なら、正しい番号を入力してから Enterを押して下さい。
4. parameterNameプロパティに該当するミックスインの 引数名を埋めてから、Enterを押して下さい。
5. parameterPropertiesSpecificationを ObjectSubtypes.fixedKeyAndValuePairsObject型の オブジェクトで埋めて下さい。 静的型付けが無い為に、直ぐに発見出来ないと言う誤りを避けるには、TypeScriptファイルで此の 型の変数を先に作ってから、此処に貼り付ける事を御薦めします。 勿論、直接入力しても構いません。
6. mixinNameプロパティに該当するミックスインの名前を埋めて下さい。

外部リンク

• ソースコード
• RawObjectDataProcessor
  此のクラスのAPIはprocessObjectTypeParameterOfPugMixin 関数に使われている
• 実例
  «TextBox» TextBoxと言うGUIコンポーネントのマークアップを 生成する為processObjectTypeParameterOfPugMixin関数を利用する