Cheetah:構文

コメントは、出力に表示されるべきではないメモ、説明、および装飾テキストをマークするために使用されます。 Cheetahは、Cheetahソースコードから生成するPythonモジュールにコメントを保持します。コメントディレクティブには、1行と複数行の2つの形式があります。

次のテンプレートは、１行コメントを記述した例です。

code: python

##============================= コメントのディレクティブ

$var ## ディレクティブ以降行末までがコメント

##=

#* ... *#に囲まれたテキストは、複数行コメントとして扱われます。

code: pyton

これはコメント

複数行のコメント

テンプレートを読みやすくする目的で、メソッド定義またはループを区切るために空白行を配置すると、その空白行はそのまま出力されることに注意してください。これを回避するためには、空白行をコメントで囲んでおきます。通常、次のメソッド定義の前にはコメントがあるので、次のようにそのコメントを拡張して、前のメソッド定義の後に空白行を含めることができます。

code: python

#def method1

... lines ...

#end def

Description of method2.

$arg1, string, a phrase.

#def method2($arg1)

... lines ...

#end def

docstrtingsコメント

Pythonモジュール、クラス、およびメソッドは、インラインのドキュメント文字列(docstrings)でドキュメント化できます。コメントとは異なり、docstringは実行時にアクセスすることができます。したがって、これらはインタラクティブなヘルプユーティリティに役立つフックが提供されます。

Cheetahのコメントは、次の接頭辞のいずれかを追加することでdocstringsに変換できます。

code: python

##doc: このテキストはメソッドdocstringに追加されます

#*doc: テンプレートファイルが　MyTemplate.tmplの場合、

cheetah compile MyTemplate.tmplを実行すると、

クラスMyTemplateを含むMyTemplate.pyが生成されます。

このテキストは.respond()メソッドののdocstringに含まれます。*#

##doc-method: このテキストは.respond()のdocstringに追加されます

#*doc-method: このテキストは.respond()のdocstringに追加されます *#

##doc-class: このテキストは、MyTemplateクラスのdocstingsに追加されます

#*doc-class: このテキストは、MyTemplateクラスのdocstingsに追加されます *#

##doc-module: このテキストは、モジュールMyTemplate.pyのdocstringsに追加されます

#*doc-module: このテキストは、モジュールMyTemplate.pyのdocstringsに追加されます *#

ヘッダーコメント

Cheetahコメントは、次の構文を使用してモジュールヘッダーコメントに変換することもできます。

code: python

##header: このテキストはモジュールヘッダーコメントに追加されます

#*header: このテキストはモジュールヘッダーコメントに追加されます *#

## doc-module:とheader: の違いに注意してください。cheetah compile は、モジュールdocstring内に## doc-module:テキストを配置します。 header: は、テキストをdocstringのより前に、#プレフィックス付きのコメント行(#....)のセットとして配置します。

変数構文規則

変数は、接頭辞として前にドル記号($)が付いている短い形式か、${....}で囲まれた長い形式があります。それ以外はPython変数と同じ構文規則に従います。

code: python

$var

${var}

$var2.abc'def'('gh', $subplaceholder, 2)

${var2.abc'def'('gh', $subplaceholder, 2)}

単純な場合は$placeholderのように使いますが、他の文字が直接続く場合は、変数名の終わりについて混乱することを避けるために${placeholder}を使用することをお勧めします。$()または$[]を使用することもできますが、混乱しやすいので注意してください。

code: python

$(var)

$var

$(var2.abc'def'('gh', $subplaceholder, 2))

$[var2.abc'def'('gh', $subplaceholder, 2)]

注1:{# compiler}ディレクティブを使用して区切り文字を任意に変更できます。

注2: 長い形式は、式ではなく、トップレベルの変数でのみ使用できます。

Pythonのルールを繰り返すために、変数名はピリオドで区切られた1つ以上の識別子で構成されます。各識別子は文字またはアンダースコアで始まる必要があり、後続の文字は文字、数字、またはアンダースコアである必要があります。任意の識別子の後に、括弧(())で囲まれた引数または角括弧([])のキー/添え字を続けることができます。

識別子では大文字と小文字が区別されます。 {$ var}は{$ Var}または{$ vAr}または{$ VAR}と等しくありません。

()または[]内の引数は、Pythonの場合とまったく同じです。文字列は、任意のPython引用スタイルを使用して引用できます。各引数は式であり、Pythonの任意の式演算子を使用できます。引数式で使用される変数は接頭辞($)を付ける必要があります。これは、*argおよび **kwフォームにも当てはまります。ただし、特別なPython定数（None、True、およびFalseなど）には接頭辞($)は必要ありません。

code: python

$hex($myVar)

$func($arg=1234)

$func2($*args, $**kw)

$func3(3.14159, $arg2, None, True)

$myList$mySubscript

末尾のピリオド（.)は無視されます。 Cheetahは、{$ varName.}の変数名が{varName}であることを認識し、テンプレート出力ではピリオドはそのままになります。

${placeholderName, arg1="val1"}の構文は、出力フィルターに引数を渡します。この場合、中括弧とコンマが必要です。この場合、キーワード引数（つまり、{arg1}）の前にはドル記号($)を省略するのが一般的です。

Cheetahは、文字またはアンダースコアが後に続かないすべてのドル記号（$）を無視します。

有効な変数は次のとおりです。

code: python

$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list3

$object.method $object.method() $object.method

$nest($nest($var))

次の例は、どれも変数としてではなく、通常のテキストとして扱われます。

code: python

$@var $^var $15.50 $$

変数が使用できる場所

変数を使用できる場所は、トップレベルの位置、式の位置、LVALUEの位置の3つです。それぞれにわずかに異なる構文規則があります。

トップレベルの位置は、テキストに散在していることを意味します。これは、変数の長い形式を使用できる唯一の場所です。${var}

{式の位置}は、Python式と同じチーター式を意味します。変数は、読み取るsearchListまたはその他の変数に名前を付けます。式の位置は、変数タグ（つまり、変数内の変数）内の()引数と$[]、$引数内、およびいくつかのディレクティブタグ内で発生します。

{LVALUEの位置}は、書き込まれる変数に名前を付けることを意味します。 LVALUEは、「割り当てステートメントの左側」を意味するコンピュータサイエンスの用語です。ディレクティブ{#set}、{#for}、{#def}、{#block}、および{#attr}の最初の引数はLVALUEです。

次の例は、3つの位置を示しているだけのもので、内容には意味がありません。

トップレベルの位置を通常表記、式の位置を緑背景、LVALUEの位置を赤背景示しています。

#for $count in $range($ninetyNine, 0, -1)

#set $after = $count - 1

$count bottles of beer on the wall. $count bottles of beer!

Take one down, pass it around. $after bottles of beer on the wall.

#end for

$hex($myVar, $default=None)

出力は次のとおりです。

code: pytohn

99 bottles of beer on the wall. 99 bottles of beer!

Take one down, pass it around. 98 bottles of beer on the wall.

98 bottles of beer on the wall. 98 bottles of beer!

Take one down, pass it around. 97 bottles of beer on the wall.

...

変数にはドル記号が必要？

ドル記号($)はスマート変数プレフィックスです。 Cheetahは$を検出すると、変数の位置と、それがsearchList値か非searchList値かを判断し、適切なPythonコードを生成します。

トップレベルの位置では、$は必須です。それ以外の場合、変数を通常のテキストと区別するものはなく、変数名は逐語的に出力されます。

式の位置では、値がsearchListまたは #set global変数からのものである場合は$が必須、ローカル/グローバル/組み込み変数の場合は推奨、特殊定数の場合は不要です。これは、CheetahがsearchList変数の関数呼び出しを生成するが、ローカル/グローバル/組み込み変数の裸の変数名を生成するために機能します。

LVALUEの位置では、$は推奨です。 Cheetahは、LVALUEが期待される場所を知っているため、$があるかどうかに関係なく、変数名を処理できます。

例外：Pythonリスト内包表記の中間変数に$を使用しないでください。これはチーターのパーサーの制限です。リスト内包表記のどの変数が中間変数であるかがわからないため、支援する必要があります。

code: pyton

#set $theRange = x ** 2 for x in $range(10)

$theRange は通常の{#set}変数です。 $rangeはPythonの組み込み関数です。ただし、xはリスト内包内のスクラッチ変数です。$xとしてしまうと、Cheetahはそれを誤ってコンパイルします。

NameMapper構文

Cheetahの主要な目的の1つは、プログラマー以外の人が簡単に使用できるようにすることでした。したがって、Cheetahは、Cheetahの変数をPythonの値にマッピングするために簡略化された構文を使用します。これはNameMapper構文として知られており、プログラマー以外の人が（a）インスタンスと辞書の違い、（b）関数とメソッド、および（c）「自己」が何であるかを知らなくてもCheetahを使用できます。副次的な利点は、テンプレートを変更することなく、基になるデータ構造を変更できることです（たとえば、インスタンスを辞書に、またはその逆）。

NameMapper構文は、Cheetah変数およびディレクティブのすべての変数に使用されます。必要に応じて、Templateクラスの‘useNameMapper’コンパイラ設定を介してオフにすることができます。しかし、それをオフにしたいと思うかどうかは疑わしいです。

あなたは顧客情報システムを構築しています。あなたと一緒にいるデザイナーは、クライアントのWebサイトでシステムからの情報を使用したいと考えています。また、表示コードを理解して、自分で保守できるようにしたいと考えています。

すべての顧客オブジェクトのディクショナリを返すcustomers()メソッドを使用してUIクラスを記述します。各顧客オブジェクトには、顧客の住所に関する情報を含む辞書を返すaddress()メソッドがあります。設計者は、その情報にアクセスできることを望んでいます。

PSP Webアプリケーションを使用すると、サーブレットが顧客情報を管理するために作成したクラスをサブクラス化すると仮定すると、Webサイトの表示コードは次のようになります。

code: python

<%= self.customer()ID.address()'city' %> (42 chars)

CheetahのNameMapper構文では、次のいずれかを使用できます。

code: python

self.customers()$ID.address()'city' (39 chars)

--OR--

$customers()$ID.address()'city'

--OR--

$customers()$ID.address().city

--OR--

$customers()$ID.address.city

--OR--

$customers$ID.address.city (27 chars)

プログラミングの経験がないデザイナーに説明したいのはどれですか？最後の形式は、PSPバージョンよりも15文字短く、概念的にははるかにアクセスしやすくなっています。 PHPまたはASPを使用すると、コードはPSPを使用した場合よりもさらに面倒になります。

これはかなり極端な例であり、もちろん、$getCustomer($ID.city}を実装して対応することもできますが、記述量が増えることには違いがありません。

辞書へのアクセス

NameMapper構文を使用すると、Pythonでオブジェクト属性にアクセスするために使用されるのと同じドット表記の辞書アイテムにアクセスできます。 Cheetahでは次のように書くことができます。

code: python

$customers()'kerr'.address() --OR-- $customers().kerr.address()

ここで、2番目の形式はNameMapper構文です。

これは、たまたま有効なPython識別子でもある辞書キーでのみ機能します。

自動呼び出し

Cheetahは、Cheetah 変数内の関数とメソッドを自動的に検出し、括弧が省略されている場合はそれらを呼び出します。前の例は、次のようにさらに簡略化できます。

code: python

$customers.kerr.address

別の例として、aがオブジェクトの場合、bはメソッドです

code: python

$a.b

これは、次のようにも記述できます。

code: python

$a.b()

bが辞書を返す場合、次のようにすることもできます。

code: python

$a.b.c --OR-- $a.b().c --OR-- $a.b()'c'

ここで、cは a.b()が返す辞書のキーです。

自動呼び出しの注意事項

Cheetahが関数/メソッドを自動呼び出すときは、引数なしで呼び出します。したがって、関数/メソッドは、引数なしで宣言されているか（クラスメソッドのselfを除く)、またはすべての引数にデフォルト値を提供する必要があります。関数に引数が必要な場合は、()を省略することはできません。

Cheetahは、関数とメソッドのみを自動呼び出しすることができます。クラスおよびその他の呼び出し可能なオブジェクトは自動呼び出しされません。その理由は、関数/メソッドの主な目的はそれを呼び出すことであるのに対し、インスタンスの主な目的は、インスタンス自体を呼び出すことではなく、そのアトリビュートを検索するか、そのメソッドを呼び出すことであるためです。また、クラスを呼び出すと、クラスによっては、大量のメモリが無駄に割り当てられたり、他の副作用が発生したりする可能性があります。たとえば、$myInstance.fnameについて考えてみます。 myInstanceオブジェクトの名前空間でfnameを検索するか、あるいは myinstance が返す名前空間で検索するか、どちらかの可能性があるため、チーターは最小の原則に従います。 doでインスタンスを呼び出したい場合は、()を付加するか、__ call __()メソッドの名前を__ str__()に変更します。

自動呼び出しは、Cheetahのコンパイラ設定useAutocallingをFalseに設定すると無効にできます。構文 $getVar(‘varName’, ‘デフォルト値’、False) を使用して、1つの変数に対して無効にすることもできます。 getVar()はsearchList値でのみ機能します。

名前空間のカスケードとsearchList

Cheetahは、テンプレート内の変数名をPythonの値にマップするときに、いくつかの名前空間を順番に検索します。

ローカル変数： {# set} や{# for}によって作成されるか、Cheetahによって事前定義されます。

searchListは、次のもので構成されます。

{#setglobal}変数

Templateクラスのコンストラクターに渡したsearchListコンテナー（存在する場合）

Templateインスタンス(self)：。これには、割り当てた属性、{# def}メソッドと{# block}メソッド、{# extends}を介して継承されたアトリビュート/メソッド、およびTemplateに組み込まれた、または継承されたその他のアトリビュート/メソッドが含まれます

Pythonのグローバル変数：{# import}、{# from ... import} によって作成されるか、Cheetahによって事前定義されます。

Pythonの組み込み変数：None、True、Falseなど。

Pythonの組み込み関数：max、lenなど。

これらのうちで、最初に一致した名前が使用されます。

これらの名前空間は、ドル記号($)の後の最初の識別子にのみ適用されることに注意してください。 $a.b のような変数では、aのみがsearchListやその他の名前空間で検索されます。 bはaの名前空間だけを検索します。

searchListコンテナーは、アトリビュートやキー（辞書、インスタンス、クラス、またはモジュール）を持つ任意のPythonオブジェクトにすることができます。インスタンスにアトリビュートとキーの両方が含まれている場合、アトリビュートが最初に検索され、次にキーが検索されます。

TemplateインスタンスはsearchListの一部であるため、selfなしでそのアトリビュート/メソッドにアクセスできます：$myAttr。ただし、より上位の名前空間$self.myAttrで定義されている同じ名前の変数ではなく、Template属性を取得していることを確認する場合は、selfを使用してください。これは、self自体がローカル変数であるために機能します。

すべてのルックアップと関数呼び出しの後（ただし、フィルターが適用される前）の最終的な結果の値は、どの名前空間で見つかったかに関係なく、変数の値と呼ばれます。

注意：オブジェクトmyObjectをsearchListに配置すると、$myObjectを検索することはできません。 myObjectの内部のアトリビュート/キーのみを検索することができます。

テンプレートをWebwareサーブレットとして使用する場合は、Templateインスタンスのメソッドnameとlogをオーバーライドしないでください。オーバーライドすると、Webwareのロギングが妨げられます。ただし、WebwareはCheetah名前空間を認識していないため、これらの変数をより高い名前空間で使用することは可能です。

値を見つけられないとき

NameMapperがCheetah変数名のPythonの値を見つけられない場合、NameMapper.NotFound例外が発生します。 #errorCatcherディレクティブ、テンプレートコンストラクター引数を使用して、代替の動作を指定できます。ただし、#errorCatcherはデバッグのみを目的としていることに注意してください。

変数のデフォルト値を指定するには、$getVar(‘varName’, ‘デフォルト値')のように記述します。デフォルトを指定せず、変数を見つけられない場合、NameMapper.NotFound例外が発生します。