パッケージ com.lmt.lib.bms

クラス BmsStandardLoader

  • public class BmsStandardLoader
extends BmsLoader
    標準フォーマットのBMSからBMSコンテンツを生成するBMSローダクラスです。

    標準フォーマットの記述形式について
    標準フォーマットは、一般に知られるBMSの仕様に基づいて記述されたテキストです。一般的には「BMSファイル」のことを指します。 BMSライブラリで読み取り可能な記述形式は一般的なBMSの仕様を取り込んでいますが、一部独自の機能を盛り込んでいます。 詳細については以下を参照してください。

    BMS宣言
    BMSの1行目において、";?bms"で始まるコメントを検出した場合、1行目をBMS宣言として解析しようとします。 BMS宣言の構文に誤りがある場合、BMS宣言は通常のコメントとして認識されるようになり、BMS宣言のないBMSコンテンツとして 読み込まれます。BMS宣言の記述例は以下の通りです。

     ;?bms rule="BM"

    メタ情報
    BMSの中で「ヘッダ」と呼ばれる宣言をメタ情報として解析します。メタ情報は"#"または"%"で始まる行が該当します。 メタ情報はBMSのどこで宣言されていても問題なく読み込むことができます(チャンネルを記述した後でもOK)。 ただし、一般的にはメタ情報を全て宣言した後でチャンネルを記述することがほとんどのようです。
    メタ情報の記述例は以下の通りです。

     #GENRE J-POP
 #TITLE My Love Song
 #BPM 120
 %URL http://www.lm-t.com/
 %MYMETA 00AA00GG00ZZ

    タイムライン要素
    "#"＋数字3文字＋36進数2文字＋":"で始まる行は「タイムライン要素」として解析します。 最初の数字は小節番号、続く36進数はチャンネル番号を表し、":"の後の記述は当該小節・チャンネルのデータを表します。 タイムライン要素の記述形式はBMS仕様によって定められているため、仕様に違反する記述をした場合、 当該チャンネルは構文エラーとして報告されます。一般的にチャンネルは小節番号の若い順で記述されますが、 小節番号は前後しても構いません。ただし、BMSの可読性が著しく低下するので小節番号順に記述することが推奨されます。
    タイムライン要素の記述例は以下の通りです。

     #01002:1.5
 #0880A:00AB00CD00EF00GH
 #123ZZ:String data channel

    • コンストラクタの詳細

      • BmsStandardLoader

        public BmsStandardLoader()
        新しい標準フォーマット用ローダオブジェクトを構築します。

    • メソッドの詳細

      • beginParse

        protected BmsErrorParsed beginParse​(BmsLoaderSettings settings,
                                    BmsSource source)
        BMSの解析処理開始を通知します。

        ※当メソッドはBMSライブラリの一般利用者が参照する必要はありません。

        当メソッドが呼ばれた時点でBMSローダが持つパーサ部を初期化することを求めます。 入力引数でローダの設定と解析対象の入力データが通知されるので、パーサ部の動作に必要な初期化処理を行ってください。

        パーサ部の初期化完了後にBmsLoader.nextElement()が呼び出され、BMSコンテンツの各構成要素を返すモードに遷移します。 しかし、当メソッドの実行で以下の条件のいずれかを満たすと、パーサ部の初期化エラーと見なしBMS読み込みは中止され BmsExceptionがスローされます。

        • 戻り値でnullを返した
        • 戻り値でエラー(BmsErrorParsed.isFail()がtrueになるオブジェクト)を返した(BmsLoadException)
        • 当メソッドから実行時例外がスローされた
        • 当メソッドから意図的にBmsExceptionをスローした

        当メソッドが呼ばれると、上記の実行結果に関わらずBmsLoader.endParse()が必ず呼び出されます。

        定義:
        beginParse クラス内 BmsLoader
        パラメータ:
        settings - ローダの設定
        source - 解析対象の入力データ
        戻り値:
        初期化結果を表すエラー情報要素

      • endParse

        protected BmsErrorParsed endParse()
        BMSの解析処理終了を通知します。

        ※当メソッドはBMSライブラリの一般利用者が参照する必要はありません。

        当メソッドはBmsLoader.beginParse(BmsLoaderSettings, BmsSource)が呼ばれると、その実行の成否に関わらず必ず呼ばれます。 BMSローダのパーサ部が使用したリソースを確実に解放する契機を確保するためです。

        パーサ部の初期化途中で実行時例外がスローされ、初期化が中途半端な状態で当メソッドが実行される可能性がありますので、 それを踏まえたうえで当メソッドの処理を実装するようにしてください。

        当メソッドの実行で以下の条件のいずれかを満たすと読み込まれたBMSコンテンツは破棄されBmsException がスローされます。

        • 戻り値でnullを返した
        • 戻り値でエラー(BmsErrorParsed.isFail()がtrueになるオブジェクト)を返した(BmsLoadException)
        • 当メソッドから実行時例外がスローされた

        パーサ部の初期化エラー後に当メソッドが呼ばれ実行時例外がスローされた場合、BMSローダは未定義の動作となります。 当メソッドは極力、実行時例外がスローされる契機がないよう実装してください。

        定義:
        endParse クラス内 BmsLoader
        戻り値:
        終了処理結果を表すエラー情報要素

      • nextElement

        protected BmsParsed nextElement()
        BMSの解析によって得られたBMSコンテンツの要素を1件返します。

        ※当メソッドはBMSライブラリの一般利用者が参照する必要はありません。

        標準フォーマットにおけるBMS解析の動作仕様は概ね以下の通りです。

        • 行頭の半角スペースおよびタブは無視されます。
        • 半角スペースおよびタブのみの行は空行として読み飛ばします。
        • 改行コードは<CR>, <LF>, <CR><LF>を自動認識します。
        • 先頭行において、";bms? "で始まる場合はBMS宣言として認識されます。
        • BMS宣言は左から順に解析し、その順番で返します。
        • ";"、"*"、または"//"で始まる行はコメント行として認識されます。(単一行コメント)
        • "/*"で始まる行は複数行コメントの開始行として認識されます。以降、行末に"* /"が出現するまでの 行は全てコメントとして認識されます。
        • 複数行コメントが閉じられずにBMS解析が終了した場合、エラーハンドラにてBmsErrorType.COMMENT_NOT_CLOSED が通知されます。
        • "#"または"%"で始まり、1文字目がアルファベットで始まる行をメタ情報の定義と見なします。
        • "#"に続き3文字の半角数字で始まり、次に2文字の半角英数字、更にその次が":"で始まる行をタイムライン要素の定義と見なします。
        • 以上のパターンに該当しない行は構文エラーとしてエラー要素を返します。
        定義:
        nextElement クラス内 BmsLoader
        戻り値:
        BMSコンテンツの要素、またはエラー要素。これ以上要素がない場合はnull。
        関連項目:
        BmsDeclarationParsed, BmsMetaParsed, BmsTimelineParsed, BmsErrorParsed