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

クラス BmsLoader

  • 直系の既知のサブクラス:
    BeMusicBmsonLoader, BmsStandardLoader
    public abstract class BmsLoader
extends Object
    外部データからBMSコンテンツを生成するローダの基底クラスです。

    BMSライブラリは、「外部データ」からBMSコンテンツを読み込む機能を提供します。ここで言う「外部データ」とは、 BMSで記述されたテキストデータのことを指します。外部データはファイル等の何らかの形式で記録されていることを 想定しており、Java言語のInputStreamで読み取ることができるもの全てを指します。

    BMSローダの基本的な動作について
    BMS読み込み処理は「BMSコンテンツ生成処理部」と「パーサ部」に分かれており、このうちパーサ部は抽象化されています。 パーサ部は当クラスを継承したクラスで実装され、そのクラスがそのまま対応するフォーマットになります。 BMSライブラリではBmsStandardLoaderで標準フォーマットのBMSに対応しています。 また、当クラスを継承し独自のパーサ部を実装することで別のフォーマットに対応したBMSローダを作成できます。

    エラーハンドリングについて
    通常、BMSの読み込みにおいてエラー行を検出した場合はその行を無視し、読み込みを続行することがほとんどです。 アプリケーションによっては、特定のエラーを検出した場合例外的に読み込みを中止し、読み込みエラーとして扱いたい ケースがあります。そのような場合はsetHandler(BmsLoadHandler)でハンドラを登録し、発生したエラーに応じて 読み込みの続行・中止を選択することができます。発生したエラーを蓄積し、エラーをユーザーに報告するようなケースも エラーハンドリングを行うことで解決できます。詳細はBmsLoadHandlerを参照してください。

    拡張したBMSコンテンツオブジェクトを読み込みたい場合
    アプリケーションによっては拡張したBMSコンテンツオブジェクト(BmsContent)を読み込みたいケースが存在します。 BmsLoaderでは読み込み時に、生成するBMSコンテンツオブジェクトを決定することができるようになっています。 setHandler(BmsLoadHandler)で設定したハンドラのBmsLoadHandler.createContent(BmsSpec)を オーバーライドすることによりアプリケーションで独自拡張したBMSコンテンツオブジェクトを返すことができます。

    基数選択について
    BMSローダは以下の要素の数値表現を行うための基数を外部データ側から指定できます。

    これらの要素はデフォルトではBmsSpec.BASE_DEFAULTで規定される基数で解析を行います。 この基数を変更する場合、BmsSpec.getBaseChangerMeta()で示されるメタ情報に基数を設定します。 ただし、この設定を有効にするにはBMS仕様で基数選択メタ情報を規定する必要があります。 基数選択メタ情報の規定方法についてはBmsSpecBuilder.setBaseChangerMeta(String)を参照してください。

    導入されたバージョン:
    0.0.1
    関連項目:
    BmsLoadHandler, BmsScriptError

    • フィールドの詳細

      • DEFAULT_HANDLER

        public static final BmsLoadHandler DEFAULT_HANDLER
        BMSローダのデフォルトハンドラです。具体的な振る舞いはBmsLoadHandlerを参照してください。

    • コンストラクタの詳細

      • BmsLoader

        protected BmsLoader()
        BmsLoaderオブジェクトを構築します。

      • BmsLoader

        protected BmsLoader​(boolean isStandard,
                    boolean isBinaryFormat)
        BmsLoaderオブジェクトを構築します。
        パラメータ:
        isStandard - 標準フォーマット用ローダかどうか
        isBinaryFormat - ローダへの入力データがバイナリフォーマットかどうか

    • メソッドの詳細

      • isStandard

        public boolean isStandard()
        このローダが標準フォーマット用のローダかどうかを返します。

        標準フォーマット用ローダとはBmsStandardLoaderを指します。それ以外のローダは常にfalseを返します。

        戻り値:
        ローダが標準フォーマット用の場合に限りtrue
        導入されたバージョン:
        0.8.0
        関連項目:
        BmsStandardLoader

      • isBinaryFormat

        public boolean isBinaryFormat()
        このローダへの入力データがバイナリフォーマットかどうかを返します。
        戻り値:
        入力データがバイナリフォーマットの場合true
        導入されたバージョン:
        0.8.0

      • getLastProcessedCharset

        public Charset getLastProcessedCharset()
        このローダで最後に読み込んだBMSコンテンツで使用した文字セットを取得します。

        当メソッドは以下のメソッドによりBMSコンテンツの読み込みを行った場合に使用された文字セットを取得します。

        上記以外のメソッドで読み込みを行った場合、ローダがバイナリフォーマットの場合、 または一度も読み込みを行っていない場合当メソッドはnullを返します。

        読み込み処理の途中で例外がスローされると文字セットの更新は行われません。

        戻り値:
        最後に読み込んだBMSコンテンツで使用した文字セット、またはnull
        導入されたバージョン:
        0.8.0
        関連項目:
        setCharsets(Charset...), BmsLibrary.setDefaultCharsets(Charset...)

      • getLastProcessedHasBom

        public boolean getLastProcessedHasBom()
        このローダで最後に読み込んだBMSコンテンツにBOM(Byte Order Mark)が含まれていたかどうかを取得します。

        当メソッドは以下のメソッドによりBMSコンテンツの読み込みを行った場合に、入力ソースにBOMが含まれていたかどうかを返します。

        当ローダがどの文字セットのBOM検出に対応するかについてはload(byte[])のドキュメントを参照してください。 上記以外のメソッドで読み込みを行った場合、またはBOM検出に対応していない文字セットが使用された場合当メソッドは false を返します。

        読み込み処理の途中で例外がスローされるとBOMの有無の更新は行われません。

        戻り値:
        最後に読み込んだBMSコンテンツにBOMが含まれていた場合true
        導入されたバージョン:
        0.8.0

      • setSpec

        public BmsLoader setSpec​(BmsSpec spec)
        読み込み対象BMSのBMS仕様を設定します。

        ローダーは設定されたBMS仕様に従ってBMSの構文を解析します。

        パラメータ:
        spec - BMS仕様
        戻り値:
        このオブジェクトのインスタンス

      • setHandler

        public BmsLoader setHandler​(BmsLoadHandler handler)
        BMS読み込みハンドラを設定します。

        デフォルトではDEFAULT_HANDLERが設定されています。BMS読み込み時の振る舞いを変えたい場合は 実装をカスタマイズしたBmsLoadHandlerオブジェクトを設定してください。

        nullを設定することはできません。nullにした状態でload(java.io.File)メソッドを呼び出すと例外がスローされます。

        パラメータ:
        handler - BMS読み込みハンドラ
        戻り値:
        このオブジェクトのインスタンス

      • setStrictly

        public BmsLoader setStrictly​(boolean strictly)
        厳格なフォーマットチェックの有無を設定します。

        この設定を有効にすると、BMSの記述内容のチェックが厳格になりエラーが出力されやすくなります。 記述内容の不備に関する要因で読み込み処理が中止されやすくなりますが、 それによる意図しないBMSコンテンツの構築を防止できるというメリットがあります。

        具体的には、この設定を有効にすると下記の設定になり、無効にすると下記とは逆の設定になります。

        • 構文エラーを無視せずエラーとして報告します。
        • BMSライブラリの仕様に違反する範囲の値を設定した時、値を仕様範囲内に収めずエラーとして報告します。
        • メタ情報・値型の重複可能チャンネルの再定義を検出した時、上書きをせずにエラーとして報告します。
        • BMS仕様にないメタ情報を検出した時、無視をせずエラーとして報告します。
        • BMS仕様にないチャンネルを検出した時、無視をせずエラーとして報告します。
        • BMS仕様・チャンネルの値が規定されたデータ型に適合しない時、無視をせずエラーとして報告します。

        当メソッドで設定を行うと、複数の設定が一度に書き換えられることに留意してください。

        パラメータ:
        strictly - 厳格なフォーマットチェックの有無
        戻り値:
        このオブジェクトのインスタンス
        導入されたバージョン:
        0.7.0
        関連項目:
        setSyntaxErrorEnable(boolean), setFixSpecViolation(boolean), setAllowRedefine(boolean), setIgnoreUnknownMeta(boolean), setIgnoreUnknownChannel(boolean), setIgnoreWrongData(boolean)

      • setSyntaxErrorEnable

        public BmsLoader setSyntaxErrorEnable​(boolean isEnable)
        構文エラーの有効状態を設定します。

        BMSでは、メタ情報・チャンネル定義以外の記述は全て無視される仕様になっています。BMS内での不要・不正な記述を 防ぐために、メタ情報・チャンネル定義と認識されない全ての記述を構文エラーとしたい場合に当メソッドを使用します。

        構文エラーを有効にした状態でメタ情報・チャンネル定義以外の記述を検出すると、BMS読み込みハンドラにて解析エラーを 通知するようになります。通知メソッドから解析中止が返されるとBMS解析はエラーとなります。

        この設定は、複数行コメントが終了しない状態でBMSの読み込みが終了した場合(BmsErrorType.COMMENT_NOT_CLOSED)、 およびsetHandler(BmsLoadHandler)で設定したハンドラのBmsLoadHandler.testContent(BmsContent) が検査失敗を返した場合(BmsErrorType.TEST_CONTENT)にも適用されます。

        デフォルトでは構文エラーは「無効」になっています。

        パラメータ:
        isEnable - 構文エラーの有効状態
        戻り値:
        このオブジェクトのインスタンス

      • setFixSpecViolation

        public BmsLoader setFixSpecViolation​(boolean isFix)
        BMSライブラリの定める仕様に違反した値を自動的に仕様範囲内に丸め込むかどうかを設定します。

        この設定を有効にすることで訂正される値とは、「初期BPM」「小節長」「BPM変更用のBPM」「譜面停止時間」を指します。 それぞれの値の許容範囲はBmsSpecを参照してください。

        この設定のデフォルト値は false です。BMSライブラリ仕様の違反を検出するとローダーに設定されたBmsLoadHandler に対してエラー通知を行います。その際のエラー種別はBmsErrorType.SPEC_VIOLATIONとなります。

        通常、BMSライブラリの仕様違反となる値は非常に極端な値となっており、値を訂正したとしても当該楽曲の再生には 大きな影響がない場合がほとんどですが、値の使い方次第では楽曲の構成を大きく崩してしまう可能性があります。そのような ケースが許容されない場合には仕様違反の訂正は行わず、当該楽曲の読み込みはエラーとして扱うべきです。

        この設定を有効にして読み込まれたBMSは定義上とは異なるデータとして読み込まれますので、BmsContent.generateHash(boolean, boolean, boolean) が生成する値にも影響を及ぼします。

        デフォルトではこの設定は「有効」になっています。

        パラメータ:
        isFix - 仕様違反訂正の有効状態
        戻り値:
        このオブジェクトのインスタンス

      • setAllowRedefine

        public BmsLoader setAllowRedefine​(boolean isAllow)
        メタ情報・値型の重複不可チャンネルの再定義を検出した場合のデータ上書きを許可するかどうかを設定します。

        データ上書きを許可すると、先に定義されたメタ情報、または同じ小節の小節データを上書きするようになります。 メタ情報は単体メタ情報(BmsUnit.SINGLE)と定義済みの索引付きメタ情報(BmsUnit.INDEXED)が対象です。

        再定義が不許可の状態でメタ情報・値型重複不可チャンネルの再定義が検出された場合、再定義された行はエラーとして処理され、 BMSコンテンツ読み込みハンドラのBmsLoadHandler.parseError(BmsScriptError)が呼び出されます。 エラーはBmsErrorType.REDEFINEとして通知されます。

        この設定は配列型の重複不可チャンネルには適用されません。配列型の重複不可チャンネルで重複定義があった場合、 重複した配列の定義内容を合成します。これはBMSの一般的な仕様です。

        デフォルトではこの設定は「許可」になっています。

        パラメータ:
        isAllow - 再定義の許可有無
        戻り値:
        このオブジェクトのインスタンス
        導入されたバージョン:
        0.2.0

      • setIgnoreUnknownMeta

        public BmsLoader setIgnoreUnknownMeta​(boolean isIgnore)
        不明なメタ情報を無視するかどうかを設定します。

        無視すると、BMS解析はエラーにならず不明メタ情報を読み飛ばして解析を続行するようになります。

        具体的には、setHandler(BmsLoadHandler)で設定したハンドラのBmsLoadHandler.parseError(BmsScriptError) にBmsErrorType.UNKNOWN_METAのエラーが一切通知されなくなります。

        デフォルトではこの設定は「有効」になっています。

        パラメータ:
        isIgnore - 不明メタ情報を無視するかどうか
        戻り値:
        このオブジェクトのインスタンス

      • setIgnoreUnknownChannel

        public BmsLoader setIgnoreUnknownChannel​(boolean isIgnore)
        不明なチャンネルを無視するかどうかを設定します。

        無視すると、BMS解析はエラーにならず不明チャンネルを読み飛ばして解析を続行するようになります。

        具体的には、setHandler(BmsLoadHandler)で設定したハンドラのBmsLoadHandler.parseError(BmsScriptError) にBmsErrorType.UNKNOWN_CHANNELのエラーが一切通知されなくなります。

        デフォルトではこの設定は「有効」になっています。

        パラメータ:
        isIgnore - 不明チャンネルを無視するかどうか
        戻り値:
        このオブジェクトのインスタンス

      • setIgnoreWrongData

        public BmsLoader setIgnoreWrongData​(boolean isIgnore)
        不正なデータを無視するかどうかを設定します。

        無視すると、BMS解析はエラーにならず不正データ定義のあったメタ情報・チャンネルを読み飛ばして解析を 続行するようになります。

        具体的には、setHandler(BmsLoadHandler)で設定したハンドラのBmsLoadHandler.parseError(BmsScriptError) にBmsErrorType.WRONG_DATAのエラーが一切通知されなくなります。

        デフォルトではこの設定は「有効」になっています。

        パラメータ:
        isIgnore - 不正データを無視するかどうか
        戻り値:
        このオブジェクトのインスタンス

      • setSkipReadTimeline

        public BmsLoader setSkipReadTimeline​(boolean isSkip)
        タイムラインの読み込みをスキップするかどうかを設定します。

        この設定を有効にするとタイムラインの定義を読み飛ばすようになり、BMSコンテンツに小節データとノートが 含まれなくなります。つまり、BMSコンテンツに取り込まれるのはBMS宣言とメタ情報のみなることを意味します。

        読み込み対象のBMSに含まれるメタ情報のみを参照したい場合は、この設定を有効にすることで 読み込み処理のパフォーマンス向上が期待できます。

        タイムラインの読み込みをスキップする場合、タイムライン(チャンネル定義)の行の小節番号とチャンネル番号定義の 書式が正しければ、誤った値(BmsErrorType.WRONG_DATAになる状態)を定義していたとしてもスキップされます。 ただし、小節番号、チャンネル番号のいずれかが誤った書式で定義されていた場合、その行はスキップされず 構文エラー(BmsErrorType.SYNTAX)として扱われます。

        デフォルトではこの設定は「無効」になっています。

        パラメータ:
        isSkip - タイムラインの読み込みをスキップするかどうか
        戻り値:
        このオブジェクトのインスタンス
        導入されたバージョン:
        0.4.0

      • setCharsets

        public BmsLoader setCharsets​(Charset... charsets)
        BMS読み込み時、入力のテキストデータのデコードに使用する文字セットを設定します。

        BMS読み込みにload(Reader)以外を使用する場合、テキストのデコード処理が必要になります。 当メソッドを使用し、優先順位の高い文字セットから順に文字セットを登録してください。

        同じ文字セットを複数追加しても意味はありません。後方で指定したほうの同一の文字セットが無視されます。

        文字セットの登録は省略可能です。省略した場合BmsLibrary.getDefaultCharsets()を呼び出し、 BMSライブラリのデフォルト文字セットリストを使用してデコード処理が行われます。 これは、当メソッドで文字セットを1個も指定しなかった場合も同様です。

        入力データがバイナリフォーマットのローダでは、当メソッドで設定した文字セットは使用されません。

        パラメータ:
        charsets - テキストのデコード処理時に使用する文字セットリスト
        戻り値:
        このオブジェクトのインスタンス
        例外:
        NullPointerException - charsetsにnullが含まれている
        導入されたバージョン:
        0.7.0
        関連項目:
        BmsLibrary.setDefaultCharsets(Charset...)

      • load

        public BmsContent load​(File bms)
                throws IOException
        BMSコンテンツを読み込みます。

        当メソッドは指定されたファイル全体を読み込み load(byte[]) を呼び出す下記コードと等価です。

        loader.load(Files.readAllBytes(bms.toPath()));

        ファイル読み込み時に異常が発生すると IOException がスローされますが、 より具体的にスローされる例外についてはJDKの java.nio.file のドキュメントを参照してください。 指定したパスのファイルが存在しない場合は NoSuchFileException がスローされます。

        パラメータ:
        bms - BMSファイル
        戻り値:
        BMSコンテンツ
        例外:
        NullPointerException - bmsがnull
        IllegalStateException - BMS仕様が設定されていない
        IllegalStateException - BMS読み込みハンドラが設定されていない
        NoSuchFileException - 指定されたパスのファイルが存在しない
        IOException - 何らかの理由によりデータ読み取り異常が発生した
        BmsHandleException - ユーザープログラムの処理異常を検出した
        BmsLoadException - ユーザープログラムの判断によりBMSコンテンツの読み込みが中止された
        BmsPanicException - 内部処理異常による処理の強制停止が発生した
        関連項目:
        load(byte[])

      • load

        public BmsContent load​(Path bms)
                throws IOException
        BMSコンテンツを読み込みます。

        当メソッドは指定されたファイル全体を読み込み load(byte[]) を呼び出す下記コードと等価です。

        loader.load(Files.readAllBytes(bms));

        ファイル読み込み時に異常が発生すると IOException がスローされますが、 より具体的にスローされる例外についてはJDKの java.nio.file のドキュメントを参照してください。 指定したパスのファイルが存在しない場合は NoSuchFileException がスローされます。

        パラメータ:
        bms - BMSファイルのパス
        戻り値:
        BMSコンテンツ
        例外:
        NullPointerException - bmsがnull
        IllegalStateException - BMS仕様が設定されていない
        IllegalStateException - BMS読み込みハンドラが設定されていない
        NoSuchFileException - 指定されたパスのファイルが存在しない
        IOException - 何らかの理由によりデータ読み取り異常が発生した
        BmsHandleException - ユーザープログラムの処理異常を検出した
        BmsLoadException - ユーザープログラムの判断によりBMSコンテンツの読み込みが中止された
        BmsPanicException - 内部処理異常による処理の強制停止が発生した
        関連項目:
        load(byte[])

      • load

        public BmsContent load​(InputStream bms)
                throws IOException
        BMSコンテンツを読み込みます。

        BMSコンテンツは指定された入力ストリームから読み込みます。

        読み込み処理の詳細はload(String)を参照してください。

        パラメータ:
        bms - BMSの入力ストリーム
        戻り値:
        BMSコンテンツ
        例外:
        NullPointerException - bmsがnull
        IllegalStateException - BMS仕様が設定されていない
        IllegalStateException - BMS読み込みハンドラが設定されていない
        IOException - 入力ストリームからのデータ読み取り中に異常を検出した
        BmsHandleException - ユーザープログラムの処理異常を検出した
        BmsLoadException - ユーザープログラムの判断によりBMSコンテンツの読み込みが中止された
        BmsPanicException - 内部処理異常による処理の強制停止が発生した

      • load

        public BmsContent load​(byte[] bms)
                throws BmsException
        BMSコンテンツを読み込みます。

        BMSコンテンツは指定されたバイト配列から読み込みます。

        ローダへの入力データがテキストの場合、バイト配列は「文字コードが不明なテキスト」として扱います。 より少ない工程で文字コードが特定できるように、最初にテキストにBOM(Byte Order Mark)が付与されているかを調べます。 この工程で判明する文字コードは「UTF-8」「UTF-16LE」「UTF-16BE」のいずれかです。

        BOMによる文字コードの特定ができなかった場合、setCharsets(Charset...)で指定された文字セット (未指定の場合はBmsLibrary.getDefaultCharsets()で取得できる文字セットリスト) で優先順にテキストのデコードを試行し、デコードがエラーなく完了するまで繰り返します。 全ての文字セットでデコードエラーが発生した場合、最優先文字セット(リストの先頭で指定された文字セット) でテキストの最後まで強制的にデコードします。当該文字セットで変換できなかった文字は代替文字で置き換えられますが、 代替文字の内容は未定義の値となります。つまり、文字化けと同義の状態となることに注意してください。

        より高速に読み込むには、読み込む想定のBMSコンテンツがどの文字セットでエンコードされていることが多いかを、 アプリケーションごとに検討のうえ最適な優先順で文字セットリストを指定することが重要になります。

        ※注意
        入力バイト配列に格納されたテキストの実際の文字コードとデコードする文字セットが異なっていれば、 必ずデコードが失敗するというわけではありません。例えばShift-JISのテキストをUTF-16LEでデコードした場合、 デコード失敗が期待動作ですがテキストの内容次第ではデコードが成功することがあります。 そのようなケースでは文字化けした文字列でBMS読み込みが行われてしまい、期待する結果が得られません。 デコードの誤判定が発生しやすい文字セットは優先順位を下げるか、デコード対象に含まないようにしてください。

        テキストのデコード後の読み込み処理詳細はload(String)を参照してください。

        ローダへの入力データがバイナリフォーマットの場合、上記で述べた文字コードの判別は行われません。 入力データのバイト配列が直接BMSパーサ部への入力データとなります。

        パラメータ:
        bms - BMSのバイト配列
        戻り値:
        BMSコンテンツ
        例外:
        NullPointerException - bmsがnull
        IllegalStateException - BMS仕様が設定されていない
        IllegalStateException - BMS読み込みハンドラが設定されていない
        BmsException - BMSローダの解析処理部からBMS例外がスローされた(実際はこの例外を継承した例外)
        BmsHandleException - ユーザープログラムの処理異常を検出した
        BmsLoadException - ユーザープログラムの判断によりBMSコンテンツの読み込みが中止された
        BmsPanicException - 内部処理異常による処理の強制停止が発生した

      • load

        public BmsContent load​(Reader bms)
                throws IOException
        BMSコンテンツを読み込みます。

        当メソッドを使用してBMSを読み込む場合、入力のテキストデータはデコード処理が行われません。 また、入力データがバイナリフォーマットのローダでは当メソッドを使用できません。 呼び出すと例外をスローします。

        パラメータ:
        bms - BMSのReader
        戻り値:
        BMSコンテンツ
        例外:
        UnsupportedOperationException - 入力データがバイナリフォーマットのローダで当メソッドを呼び出した
        NullPointerException - bmsがnull
        IllegalStateException - BMS仕様が設定されていない
        IllegalStateException - BMS読み込みハンドラが設定されていない
        IOException - テキストの読み取り中に異常を検出した
        BmsHandleException - ユーザープログラムの処理異常を検出した
        BmsLoadException - ユーザープログラムの判断によりBMSコンテンツの読み込みが中止された
        BmsPanicException - 内部処理異常による処理の強制停止が発生した

      • load

        public BmsContent load​(String bms)
                throws BmsException
        BMSコンテンツを読み込みます。

        当メソッドには入力元のBMSテキストを直接指定します。

        メタ情報解析について

        • BMS仕様に規定されていない名称を検出した場合、エラーハンドラにてBmsErrorType.UNKNOWN_METAが通知されます。
        • メタ情報の値がBMS仕様に規定されたデータ型の記述書式に適合しない場合、エラーハンドラにてBmsErrorType.WRONG_DATAが通知されます。

        チャンネル解析について

        • チャンネル番号がBMS仕様に未定義の場合、エラーハンドラにてBmsErrorType.UNKNOWN_CHANNELが通知されます。
        • 重複可能チャンネルで空定義("00"のみの定義)の場合、空配列データとして読み込まれます。
        • 重複可能チャンネルの末尾側で空配列データが連続する場合、空でない定義以降から末尾までの連続する空配列データは読み込まれません。
        • 以下のケースを検出した場合、エラーハンドラにてBmsErrorType.WRONG_DATAが通知されます。
          • チャンネルに定義されたデータの記述書式がBMS仕様に違反している場合。
          • データ重複許可チャンネルの同小節番号内にてBmsSpec.CHINDEX_MAX+1個を超えるデータ定義を検出した場合。

        入力データがバイナリフォーマットのローダでは当メソッドを使用できません。呼び出すと例外をスローします。

        パラメータ:
        bms - BMSの文字列
        戻り値:
        BMSコンテンツ
        例外:
        UnsupportedOperationException - 入力データがバイナリフォーマットのローダで当メソッドを呼び出した
        NullPointerException - bmsがnull
        IllegalStateException - BMS仕様が設定されていない
        IllegalStateException - BMS読み込みハンドラが設定されていない
        BmsException - BMSローダの解析処理部からBMS例外がスローされた(実際はこの例外を継承した例外)
        BmsHandleException - ユーザープログラムの処理異常を検出した
        BmsLoadException - ユーザープログラムの判断によりBMSコンテンツの読み込みが中止された
        BmsPanicException - 内部処理異常による処理の強制停止が発生した

      • beginParse

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

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

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

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

        当メソッドから BmsException を継承した例外を意図的にスローすると、呼び出し元へはその例外が そのままスローされます。

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

        パラメータ:
        settings - ローダの設定
        source - 解析対象の入力データ
        戻り値:
        初期化結果を表すエラー情報要素
        例外:
        BmsException - 解析処理開始時に続行不可能なエラーが発生した

      • endParse

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

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

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

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

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

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

        戻り値:
        終了処理結果を表すエラー情報要素

      • nextElement

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

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

        当メソッドはbeginParse(BmsLoaderSettings, BmsSource)によるパーサ部の初期化処理が正常に終了した後、 BMSローダによって連続で呼び出されます。パーサ部は当メソッドが呼び出される度に、 解析によって得られた要素を順次返すように実装してください。 全ての要素を返した後、nullを返すことで要素の抽出処理を終了することができます。

        要素を返す順番は問いません。BMSローダによって適切にBMSコンテンツへの登録が行われます。 また、要素の正当性はBMSローダによってチェックされますのでパーサ部でチェックを行う必要はありません。 要素の内容に問題があれば自動的にBMS読み込みハンドラへ然るべき通知が行われます。 ただし、構文エラーなどのような要素の正当性に関連しないエラーはパーサ部でチェックするようにしてください。

        解析の過程でエラーが検出された場合、BMSコンテンツへ登録する要素ではなくエラー要素(BmsErrorParsed) を返してください。エラー要素はBMSローダによってBMS読み込みハンドラのBmsLoadHandler.parseError(BmsScriptError) へ通知されます。また、1つの要素で複数のエラーが発生した場合、当メソッドの呼び出し毎に発生したエラーの要素を全て返してください。

        当メソッドで意図的にBmsExceptionを継承する例外をスローした場合、 その例外がそのまま呼び出し元へスローされます。

        戻り値:
        BMSコンテンツの要素、またはエラー要素。これ以上要素がない場合はnull。
        例外:
        BmsException - 処理中に続行不可能なエラーが発生した
        BmsHandleException - 想定外の実行時例外がスローされた
        関連項目:
        BmsDeclarationParsed, BmsMetaParsed, BmsTimelineParsed, BmsErrorParsed