文書化されていないHubL関数を調べる方法

HubL関数には公式サイトに載っていない非公開の関数が数多く存在します。今回はいくつかの例と共にどのようにして調べるのかお伝えします。

非公開関数の例

まずは、公式サイトのHubL関数を見てみましょう。それなりの数が用意されていて、配列や連想配列（ディクショナリー）などの操作を行える関数が準備されています。

例えば、配列の最後に1つだけ項目を追加できるappend関数があります。

{% set numbers = [0,1,2] %}
{% do numbers.append(3) %}
{{ numbers }}

 結果は[0,1,2,3]です。

実はこの関数と同様の処理ができる非公開のadd関数が存在します。

{% set numbers = [0,1,2] %}
{% do numbers.add(3) %}
{{ numbers }}

結果は同じ[0,1,2,3]になります。

この他にadd関数は引数を増やすことで別の使い方もできます。

{% set numbers = [0,1,2] %}
{% do numbers.add(0, 3) %}
{{ numbers }}

処理内容は「0番目に3を追加する」になるので、結果は[3,0,1,2]です。この動作は公式のinsert関数と同じ挙動をしています。

これは憶測ですが、add関数に2つの挙動があって分かりにくいのでappendとinsertを用意したのだろうと思っています。
一応念を押しますが、add関数を使うことを進めているわけではないので、分かりやすいappendとinsertを使いましょう！

次は本題の「どうやって非公開の関数を調べるのか？」です。

非公開関数の調べ方

非公開関数はHubSpotが開発者向けにソースを公開していたり、ドキュメント（javadoc）があるのでこの資料から調べることになりますが、行き当たりばったりだと時間がかかります。
ですが、少しだけプログラムのことを知るとスムーズに調査できます。

HubSpotのテンプレート制作者ならおなじみのHubLですが、そもそも何から作られているかご存じですか？HubLは「Jinjava」というJinjaベースのテンプレートエンジンを拡張した言語で、javaと名前が付くようにJavaベースで作られています。

Javaを触ったことがある方なら察したかもしれませんが、調査の鍵になるのはクラス名(Class)です。クラス名が分かるとドキュメントやソースから容易に調べることが可能になります。もちろんJavaのことを知らなくても大丈夫で、このクラス名 ＝ ファイル名と思ってもらうと分かりやすいです。

というわけで、HubLでクラス名を知るにはフィルターのpprintを使用します。pprintはデータの詳細を画面に表示するフィルターです。例として配列をpprintしてみます。

{{ [0,1,2]|pprint }}

結果は(SizeLimitingPyList: [0, 1, 2]) と表示され、このSizeLimitingPyListがクラス名です。

後はソースからSizeLimitingPyListを探して中身を確認します。

ソース内にadd関数が見つかりましたか？

このようにソースに書かれている関数は使用することができます。もちろん全て使用できるわけではなく、一般的にはpublic 関数名というような関数のみ使用可能です。

このソース内にはaddAllという公開されていない関数もあります。これは配列に別の配列を合体させる関数で使い方は2つあります。

A. addAll(挿入位置, 配列)
B. addAll(配列)

では、Aの方法で [0,1,2] の1の後（2番目）に [3,4,5]を追加してみます。

{% set numbers = [0,1,2] %}
{% do numbers.addAll(2, [3,4,5]) %}
{{ numbers }}

結果は[0, 1, 3, 4, 5, 2]になります。

もちろんaddAll関数を使用せずにforを使用して作成することもできます。

{% set numbers = [0,1,2] %}
{% for n in [3,4,5] %}
  {% do numbers.insert(loop.index + 1, n) %}
{% endfor %}
{{ numbers }}

どうでしょうか？forよりaddAll関数の方が可読性が高いですよね。

この他に便利な関数だと連想配列を操作するput関数があります。

put関数は連想配列のキーを動的に追加することができます。似たような関数のupdateと比較すると違いが分かるかと思います。

{% set newkey = "KEY_NAME" -%}
{% set dict_var = {"authorName": "Douglas Judy", "authorTitle": "Mastermind" } %}

{# 連想配列のキーに変数newkeyを使用したいけれどそのまま文字として入る #}
{% do dict_var.update({newkey: "Jake"}) %}

{# 連想配列のキーに変数newkeyの値が使用される #}
{% do dict_var.put(newkey, "Mike") %}
{{ dict_var }}

{# 結果
{
  authorName=Douglas Judy,
  authorTitle=Mastermind,
  newkey=Jake,
  KEY_NAME=Mike
}
#}

終わりに

先に注意として記載しましたが、公式に文書化されていないので突如変更される可能性があるかもしれません。

どこで役に立つかは分かりませんが非公開関数を調べる方法の紹介でした。