マニフェスト

Curl アプリケーションは、1 つのアプレットまたはスクリプトと、複数の関連パッケージ、グラフィックイメージ、オーディオファイルまたはその他のリソースで構成することができます。これらのリソースは、多くのソースファイルで使用され、複数のアプリケーションで共有される場合があります。

アプリケーションが、開発、テスト、ディプロイメントのプロセスを経過するにつれて、このようなリソースの場所が変更されることがあります。マニフェストは、関連する複数の Curl アプリケーションまたはライブラリのリソースを管理するために使用する特殊な Curl ソースファイルです。マニフェストファイルは .mcurl 拡張子を使用します。プロジェクトの作成時に Curl IDE は、プロジェクトの作成時に、マニフェストファイルを自動的に作成し、ユーザーがプロジェクトにリソースを追加または削除する毎に、マニフェストファイルを管理します。必要に応じて、ユーザーがマニフェストファイルを手動で編集することもできます。

applet 宣言や script 宣言を使用して、マニフェストファイルの名前を manifest 引数に設定することで、マニフェストを指定することが出来ます。IDE は、以下のサンプルコードで示すように、自動的にマニフェストの記述を、プロジェクトで作成される全てのアプレットファイルに追加します。

applet または script 宣言のmanifest キーワードで、マニフェストファイル名を指定します。IDE は、次の例のように、マニフェスト指定をプロジェクト内で作成されたアプレットファイルに自動的に追加します。

{curl 8.0 applet}
{applet 
    manifest = "manifest.mcurl",
    {compiler-directives careful? = true}
}

マニフェストを指定するアプレットやスクリプトは、自動的にマニフェストを使用して、明示的にパッケージの場所が指定されていないパッケージの import ステートメントを処理します。マニフェストに指定された場所を特別にオーバーライドする必要がない限り、ソースコードに直接パッケージの場所を指定しないでください。次に、アプレットとそのマニフェストの例を示します。

{curl 8.0 applet}
{applet 
    manifest = "manifest.mcurl",
    {compiler-directives careful? = true}
}
{import * from DOC.LOGO}

{value
    {show-logo}
}

{curl 8.0 manifest}
{manifest APPLET-PROJECT}

{component file start.curl,
    location = "start.curl"
}

{component package DOC.LOGO,
    location = "load.scurl"
}

{component directory images,
    location = "images"
}

また、マニフェストを使用して、ユーザーコード内に他のリソースファイルの URL を直接指定せず、 manifest-url プロシージャを介してこれらの場所を定めることもできます。

マニフェストファイルの構造

マニフェストファイルは、有効な Curl API バージョンを指定しマニフェストとして識別される curl ヘラルドで開始する必要があります。任意の manifest ステートメントを続けて記述することもできます。manifest ステートメントでは、マニフェスト名および付加的なメタデータを提供することができます。マニフェストでは、パッケージと同様の命名規則を使用することをお勧めします。「パッケージの命名」を参照してください。IDE では、マニフェスト名はプロジェクトのルートノード名となります。既定のマニフェスト名はプロジェクトとなります。

|| File:  manifest.mcurl
{curl 8.0 manifest}
{manifest PROJECT}

上記のマニフェストの残りの部分に以下の情報を含めることもできます。

マニフェストのコンポーネント

component ステートメントの構文は以下のとおりです。

component-type および COMPONENT.NAME は、マニフェストに表記されているコンポーネントを位置付けるための主要なキーになります。パッケージのような Curl コンポーネントは、COMPONENT.NAME が、ソースで宣言されているコンポーネント名と同一である必要があります。他のコンポーネント型には任意の名前を与えることもできます。マニフェストに、リソースの全ての属性を表記する必要はありませんが、マニフェストを使用するコンポーネントの位置付けでは、マニフェスト内でリストされた属性のみが使用されます。

パッケージでは、component 宣言で指定されたメタデータ値はパッケージの実際のメタデータと一致しなければなりません。一致しない場合はパッケージがロードされるときにエラーが発生します。たとえば、次のようにパッケージ MY-PACKAGE がバージョンを 1.2 と宣言した場合、

{curl 8.0 package}
{package MY-PACKAGE, version = "1.2"}

対応する component 宣言では同じバージョン番号を指定するか、または完全にこれを省略します。

以下は正しいエントリです。

{curl 8.0 manifest}
|| These entries are ok:
{component package MY-PACKAGE,
    version = "1.2",
    location = {url "my-package.scurl"}
}
{component package MY-PACKAGE,
    location = {url "my-package.scurl"}
}

以下のエントリは実際のパッケージと一致していません。

{curl 8.0 manifest}
|| This one is inconsistent with the actual package:
{component package MY-PACKAGE,
    version = "1.3",
    location = {url "my-package.scurl"}
}

curl-versions のリストをユーザーが明示的に提供しない限り、component の宣言が含まれているマニフェストファイルの curl ヘラルド中のバージョンと同じバージョンだと推定されます。

マニフェストでは component を二重宣言することができます。通常、一致したものが複数ある場合は新しいバージョンのコンポーネント宣言が古いものより優先されます。それ以外の場合はマニフェストの最初のアイテムが優先されます。

マニフェストのデリゲート（委譲）

マニフェストは delegate-to を使用して他のマニフェストに委譲することができます。

{delegate-to MORE-COMPONENTS, location = "more-components.mcurl"}

delegate-to （委譲先）リソースがプロジェクトに追加された際に、IDE は delegate-to ステートメントをプロジェクトマニフェストに追加します。

Curl RTE は、委譲先マニフェストに、必要とされているリソースが見つからない場合、各委譲先マニフェストを順に検索します。委譲先のマニフェストのヘラルドは、委譲元のマニフェストと、少なくとも一つの APIバージョンが共通している必要があります。例えば、以下のヘラルドを持つマニフェスト A は

{curl 2.0 manifest}
{manifest A}

次にあるマニフェスト B に委譲することができますが、

{curl 2.0, 2.1 manifest}
{manifest B}

A は C に委譲することはできません。

{curl 2.1 manifest}
{manifest C}

さらに、Curl RTE は、現在のアプレットまたはスクリプトを評価するための Curl API バージョンが含まれていないマニフェストヘラルドを、エラーを生成せずに無視します。前記の例では、マニフェスト A は B に委譲でき、B は C に委譲することが可能でした。しかし、2.0 API を使用している場合は、A または B によるルックアップでは、C の内容は一切使用されません。

これらの規則は、現在アクティブな Curl API のバージョンに基いてコンポーネントを選択するのを容易にするために設けられています。

マニフェストのインクルード

マニフェストファイルは、include を使用して、他のファイルの内容をインクルードすることもできます。

{include "more-components.mcurl"}

インクルードされるファイルには、マニフェストファイルで有効な式が含まれている必要があります。付加的な component 宣言または互換性のあるcurl ヘラルドを含む別のマニフェストファイルを含むソースファイルを含めることができます。

デリゲーションに関しては、インクルードされるマニフェストのヘラルドに、それをインクルードするマニフェストと共通する API バージョンを少なくとも 1 つ含める必要があります。たとえば、次のようなヘラルドを持つマニフェスト A の場合、

{curl 2.0 manifest}
{manifest A}

は、次のようなヘラルドを持つマニフェスト B をインクルードできますが、

{curl 2.0, 2.1 manifest}
{manifest B}

次のにあるマニフェスト C をインクルードできません。

{curl 2.1 manifest}
{manifest C}

さらに、Curl RTE は、現在のアプレットまたはスクリプトを評価するための Curl API バージョンが含まれていないマニフェストヘラルドを、エラーを生成せずに無視します。前記の例では、マニフェスト A は B をインクルードでき、B は C をインクルードすることが可能でした。しかし、2.0 API を使用している場合は、C の内容は一切使用されません。

また、component 宣言が明示的に curl-versions を指定していない場合、直接それをインクルードしているマニフェストのヘラルドで宣言されている API バージョンのリストから値を継承します。たとえば、マニフェスト B で宣言されたコンポーネントは、B が直接ロードされたか、あるいは A にインクルードされた結果としてロードされたかにかかわらず curl-versions に 2.0 と 2.1 という値を取得します。

マニフェストを使用したパッケージの位置付け

マニフェストを指定する applet または script は、マニフェストを使って、明示的な場所を使用しないでインポートするパッケージを位置付けます。マニフェストは、パッケージのエントリを一つ含むか、または、インクルードまたはデリゲーションによって参照する必要があります。

ソースコードに明示的に記述されているパッケージの場所が、マニフェストに記述されている場所をオーバーライドします。そのため、import ステートメントでは location キーワードを使用できません。さらに、import-package と使用される ComponentSelector は、location-hints を指定できません。

import で指定された version 番号や他のメタデータ属性は、マニフェストの component 宣言と一致する必要があります。コンポーネント宣言では、インポートで使用されるメタデータ値のすべてを宣言する必要があります。

RTE は以下のプロシージャを使って、マニフェストのデータからパッケージのインスタンスを検索します。

委譲先マニフェストを示すルートマニフェストの使用

Curl 7.0では、delegate-to ステートメントで指定された委譲先マニフェストは、delegate-to ステートメント内で明示されている場所を介してではなく ルートマニフェスト 内のエントリを検索することで間接的にその場所を定めます。これにより、全てのマニフェストの委譲先を書き換えるのではなく、アプレットのメインマニフェストを介して、委譲された全てのパッケージの場所を定義することが出来ます。

root manifest は、通常、applet/script 宣言内で記述されるマニフェストです。しかしながら、import-manifest プロシージャによって、直接または、間接的にロードされたマニフェストにおいて、ルートマニフェストは、そのプロシージャによって返されるマニフェストか、対応するキーワード引数で明示的にルートマニフェストとして指定されたマニフェストのいずれかになります。

マニフェストのロード中にdelegate-to宣言の解決を行っている時、ルートマニフェスト（委譲するマニフェストではなく）は、delegate-to内で記述された情報にマッチする component宣言を探します。delegate-to内で明示的に場所が指定されていない時または、componentエントリに

override? = true

が記述されている時のいずれかで、委譲されたマニフェストをロードする為に、エントリのマッチングからの場所が使われます。

例えば、マニフェストBが宣言を使ってマニフェストCに委譲し、

{delegate-to C, version = "2.3"}

かつルートマニフェストが以下の宣言を含むと

{component C,
    version = "1.0",
    "../C/v1-0/manifest.mcurl"
}

{component
    version = "2.3",
    "../C/v2-3/manifest.mcurl"
}

Cは、パス"../C/v2-3/"からロードされます。

以下を使用してBからCに委譲する時、

{delegate-to C, location = "../C/manifest.mcurl"}

delegate-to宣言に記述された場所が使われます。ただし、以下のように、ルートマニフェストがオーバーライドするエントリを持っていた場合は除きます。

{component C,
    override? = true,
    location = "../C/v1-0/manifest.mcurl"
}

マニフェストを使用したリソースの位置付け

マニフェストは、パッケージ以外のリソース型の検索にも使用できます。これは、必要なリソースのエントリをマニフェストで作成し、場所の情報を取得する manifest-url 関数を使用することによって簡単に達成できます。

たとえば、アプレットが画像を表示する際に、その画像ファイルの場所を書き換え可能にする場合を仮定します。アプレットの作者はイメージに任意の名前を割り当て、一致するエントリをマニフェストに入力します。

{curl 8.0 manifest}
|| Old version of product diagram
{component image PRODUCT-DIAGRAM,
    mime-type = "image/gif",
    content-size = 28000,
    version = "1.0",
    location = "old-product-diagram.gif"
}
|| New versions
{component image PRODUCT-DIAGRAM,
    mime-type = "image/gif",
    content-size = 28000,
    version = "3.0",
    location = "product-diagram.gif"
}
{component image PRODUCT-DIAGRAM,
    mime-type = "image/jpeg",
    content-size = 48000,
    version = "3.0",
    location = "product-diagram.jpeg"
}

アプレットは直接その場所を参照しなくてもイメージを表示することができます。

{image source = {manifest-url "image", "PRODUCT-DIAGRAM"}}

上記のマニフェストでは、3.0 GIF バージョンのダイアグラムが最新バージョン番号であり、3.0 JPEG イメージより前に宣言されているので、これが選択されることになります。manifest-url 呼び出しで古いバージョンのイメージを指定するだけで、アプレットは古いバージョンのイメージも使用できるようになります。

{image
    source =
        {manifest-url "image", "PRODUCT-DIAGRAM",
            version = "1.0"
        }
}

また、MIME 型を指定すれば JPEG バージョンも使用できるようになります。

{image
    source =
        {manifest-url "image", "PRODUCT-DIAGRAM",
            mime-type = "image/jpeg"
        }
}

アプレットは、ユーザー設定や使用可能なネットワーク帯域幅などの実行環境の属性を考慮して選択基準をカスタマイズすることもできます。たとえば、アプレットは帯域幅が広いときは大きなイメージを優先し、狭いときは小さいイメージを優先するようにできます。これは、カスタムセレクション関数を記述し、それを manifest-url に与えれば実現できます。

{let use-big-images?:bool = false}
|| Return true if first component is preferred over the second:
{define-proc {pick-image
                 s1:ComponentSelector, s2:ComponentSelector
             }:bool
    let constant diff:int = s1.content-size - s2.content-size
    {if s1.component-type == "image" then
        {if diff > 0 then
            {return use-big-images?}
         elseif diff < 0 then
            {return not use-big-images?}
        }
    }
    || Use default criterion:
    {return {ComponentSelector.prefer-first? s1, s2}}
}
...
{image
    source =
        {manifest-url "image", "PRODUCT-DIAGRAM",
            comparison-proc = pick-image
        }
}

IDEドキュメンテーションに、IDEでマニフェストを使ってアプリケーションを構成そしてディプロイする詳細情報が含まれています。

マニフェストを使用した翻訳ファイルの位置付け

マニフェストを使用して翻訳ファイルを配置することは、他のリソースを配置することに似ています。パッケージ、ロケールとそれらに対応した翻訳ファイルを記述した項目を追加してください。例えば、COM.EXAMPLE.DOCという名前のパッケージに対する英語と日本語の翻訳ファイルを記述する為には、以下の項目をプロジェクトのマニフェストに追加してください。

{component translations  COM.EXAMPLE.DOC,
    locale="en",
    location="resources/en/messages.xml"
}
{component translations COM.EXAMPLE.DOC,
    locale="ja",
    location="resources/ja/messages.xml"
}

以下の項目は、デフォルトの翻訳ファイルが英語であることを示しています。

{component translations COM.EXAMPLE.DOC,
    locale="default",
    location="resources/en/messages.xml"
}

マニフェスト

概要