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

クラス BmsSaver

  • public final class BmsSaver
extends Object
    BMSコンテンツを外部データへ出力するセーバーです。

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

    出力されるデータ 外部データとして出力されるデータには、以下のものが存在します。

    • BMS宣言。出力対象のBMSコンテンツにBMS宣言が1件でも存在する場合、外部データの1行目にBMS宣言の一覧を出力します。B
    • メタ情報。BMSコンテンツに設定された全てのメタ情報を出力します。メタ情報の値が初期値と同じ場合でも、明示的に 設定されたメタ情報は外部データに出力されます。メタ情報の出力順はBmsMeta.getOrder()の値に準拠します。
    • チャンネル。BMSコンテンツに記録されたチャンネルのうち、チャンネル番号がBmsSpec.SPEC_CHANNEL_MIN～BmsSpec.SPEC_CHANNEL_MAX のチャンネルを外部データとして出力します。ユーザーチャンネルのデータは出力されません。チャンネルデータの並び順は 小節番号、チャンネル番号で昇順になります。

    また、外部データにはコメントを出力することができます。コメントは以下のメソッドで登録出来ます。
    メタ情報の先頭：setMetasComment(String...)
    チャンネルの先頭：setChannelsComment(String...)
    外部データの行末：setFooterComment(String...)

    文字コードについて
    当クラスで出力する外部データの文字コードは、標準動作ではBmsSpec.getStandardCharset()の返す文字セットに従います。 この動作を変更したい場合はBmsSpec.setStandardCharset(Charset)で標準の文字セットを明示的に指定するか、BMSコンテンツの BMS宣言に、使用する文字セットを記述します。例えば、以下のようにBMS宣言を登録すると外部データはUTF-8で出力されます。

    bmsContent.addDeclaration("encoding", "UTF-8");

    このBMS宣言を追加したBMSコンテンツは、BMSライブラリで外部データとして出力する限りにおいてはUTF-8でエンコーディング されて出力されます。

    UTF-8で出力する場合のBOM(Byte Order Mark)について
    外部データをUTF-8でエンコーディングする場合において、BOMは付与されません。

    • コンストラクタの詳細

      • BmsSaver

        public BmsSaver()
        BMSセーバのインスタンスを構築します。

    • メソッドの詳細

      • setMetasComment

        public BmsSaver setMetasComment​(Collection<String> metasComment)
        メタ情報コメントを設定します。

        コメントの内容は1行につき1文字列、複数行記述する場合は複数の文字列をCollectionに設定して渡してください。

        文字列中の改行コード<CR>、<LF>は消去したうえで出力されます。

        パラメータ:
        metasComment - メタ情報コメント
        戻り値:
        BMSセーバのインスタンス
        例外:
        NullPointerException - metasCommentがnull

      • setMetasComment

        public BmsSaver setMetasComment​(String... metasComment)

      • setChannelsComment

        public BmsSaver setChannelsComment​(Collection<String> channelsComment)
        チャンネルコメントを設定します。

        コメントの内容は1行につき1文字列、複数行記述する場合は複数の文字列をCollectionに設定して渡してください。

        文字列中の改行コード<CR>、<LF>は消去したうえで出力されます。

        パラメータ:
        channelsComment - チャンネルコメント
        戻り値:
        BMSセーバのインスタンス
        例外:
        NullPointerException - channelsCommentがnull

      • setChannelsComment

        public BmsSaver setChannelsComment​(String... channelsComment)

      • setFooterComment

        public BmsSaver setFooterComment​(Collection<String> footerComment)
        フッターコメントを設定します。

        コメントの内容は1行につき1文字列、複数行記述する場合は複数の文字列をCollectionに設定して渡してください。

        文字列中の改行コード<CR>、<LF>は消去したうえで出力されます。

        パラメータ:
        footerComment - フッターコメント
        戻り値:
        BMSセーバのインスタンス
        例外:
        NullPointerException - footerCommentがnull

      • setFooterComment

        public BmsSaver setFooterComment​(String... footerComment)

      • save

        public void save​(BmsContent content,
                 OutputStream dst)
          throws BmsException
        BMSを出力します。

        dstにはクローズされていない出力可能なストリームを指定してください。出力中のエラーに関しては OutputStreamの仕様に準拠します。

        指定BMSコンテンツに1件でもBMS宣言が存在する場合、BMSの先頭行には";?bms"が出力されます。

        BMS宣言の"encoding"要素は、出力するBMSの文字セットを表します。この要素の値には文字セットの正規名が 出力されます。一方、文字セットは別名でも指定可能であることから、必ずしもプログラム上で指定した文字セット名が そのまま出力されるとは限りません。

        BMS宣言にて"encoding"要素が指定されている場合、その要素の値に記述されている 文字セットを用いてBMSを出力しようとします。
        文字セットの名称が未知の場合、BmsExceptionをスローします。
        BMSをUTF-8で出力しようとした場合のBOM(Byte Order Mark)は付加されません。
        文字セットを指定しない場合、BmsSpec.setStandardCharset(java.nio.charset.Charset)で指定した文字セットが使用されます。 通常、BMSの標準文字セットはShift-JISです。

        BMSには、以下の順に各要素が出力されます。
        1.BMS宣言(存在する場合のみ)
        2.メタ情報コメント(指定した場合のみ)
        3.メタ情報
        4.チャンネルコメント(指定した場合のみ)
        5.チャンネルデータ
        6.フッターコメント(指定した場合のみ)

        パラメータ:
        content - 出力対象のBMSコンテンツ
        dst - 出力ストリーム
        例外:
        BmsException - contentがnull: Cause NullPointerException
        BmsException - dstがnull: Cause NullPointerException
        BmsException - BMS宣言で指定の文字セットが未知
        BmsException - BMS出力中にストリームが例外をスローした