
\title{呼び出し規約}

これは自分のパッケージを提供したり、自分のコマンドや環境を作成する方向けの説明です。

PHP 上でパッケージのロードに呼ばれる函数がどう呼ばれるのか、コマンドや環境の呼び出しの際にどのような引数が渡り、
どのような返り値を返せば良いのか、について説明します。

\tableofcontents

\chapter{パッケージ}

\section{パッケージ函数一覧}
パッケージを作成する場合に必須の函数です。
函数の詳細についてはこれより下の項目を参照してください。
\begin{itemize}
	\item
		package_<<パッケージ名>>_load() \br
		\hspace{2em}パッケージ読み込み函数
	\item
		package_<<パッケージ名>>_initialize(\$parser) \br
		\hspace{2em}パッケージ初期化函数
	\item
		package_<<パッケージ名>>_css() \br
		\hspace{2em}パッケージ CSS 出力函数
\end{itemize}

\section{登録}
パッケージを登録するには、 mil/config.php の \$packages に追加したいパッケージの名前を追加します。

\section{パッケージのロード}
mil が呼び出されると、まず初めにパッケージのロードを行います。

実際には次の二つの処理を行います。

\subsection{PHP ソースファイルの読み込み}
\begin{quotation}
	mil/packages/<<パッケージ名>>/load.php
\end{quotation}
が require_once されます。

\subsection{パッケージ読み込み函数の呼び出し}
続いて、
\begin{quotation}
	package_<<パッケージ名>>_load()
\end{quotation}
という函数が呼び出されます。

パッケージの内容が複数の PHP ソースコードに分かれる場合には、
ここで各ソースコードを require_once してください\footnote{include_once などでも構いません。各パッケージの製作者様に一任します}。

\section{パッケージの初期化}
各 mil ソースコードの処理開始時にパッケージの初期化函数、
\begin{quotation}
	package_<<パッケージ名>>_initialize(\$parser)
\end{quotation}
が呼ばれます。 \$parser は MilParser クラスのインスタンスであり、変数の初期化などをここで行います。

\section{CSS の出力}
CSS を使用したい場合には、
\begin{quotation}
	package_<<パッケージ名>>_css()
\end{quotation}
の返り値として CSS を出力します。

コマンドの出力結果のデザインを容易に変更できるように、スタイルはできるだけこの函数内で定義することが強く推奨されます。

なお、CSS を使用しない場合にはこの函数は省略しても構いません。

\chapter{コマンド・環境}

\section{命名の規則}
PHP では函数名の大文字・小文字を区別しないので、それに対処するために、 mil コマンド名と PHP の実際の函数名の間で以下のような変換を行っています。
\begin{itemize}
	\item アンダースコア(_)は二つのアンダースコア(__)に置き換えられます
	\item 大文字の前にはアンダースコアを挿入します
\end{itemize}
従って例えば、SampleCommand_test という mil コマンドは、 PHP 上では、
\begin{quotation}
	_Sample_Command__test
\end{quotation}
と表記されることになります\footnote{PHP では大文字・小文字が区別されないため、「_sample_command__test」と表記しても構いませんが、見にくくなるので推奨されません}。

以下では、<<(コマンド|環境)名(PHP)>> と表記された場合には上の方法で変換された後の名称を指すこととし、
<<(コマンド|環境)名(mil)>>とした場合には変換前の名称を指すこととします。

\section{函数定義}
mil コードのパース中にコマンド・環境を発見した場合には以下のような函数名の函数が呼び出されます。

\subsection{コマンド}
\begin{quotation}
	command_<<コマンド名(PHP)>>_call(\$args, \$parser)
\end{quotation}
ここで、
\begin{itemize}
	\item
		\$args \br
		\hspace{2em}引数の文字列配列
	\item
		\$parser \br
		\hspace{2em}現在パースを行っている MilParser クラスのインスタンス
\end{itemize}
です。

\subsection{環境}
\begin{quotation}
	command_<<環境名(PHP)>>_call(\$main_arg, \$args, \$parser)
\end{quotation}
ここで、
\begin{itemize}
	\item
		\$main_arg \br
		\hspace{2em}環境の main_arg 部分の文字列
	\item
		\$args \br
		\hspace{2em}引数の文字列配列
	\item
		\$parser \br
		\hspace{2em}現在パースを行っている MilParser クラスのインスタンス
\end{itemize}
です。

\section{返り値}
返り値として変換後の HTML を出力します。

ただしこの中に他の mil コマンドや環境を含めても構いません。
その場合でもパースは行われます。
循環参照にならないように気をつけてください。

\section{例外}
何らかの原因で変換に失敗した場合、以下の例外を返すことができます。

\subsection{InvalidArgumentCountException}
引数の数が間違っていることを表す例外です。










