argra****@users*****
argra****@users*****
2013年 5月 4日 (土) 05:17:25 JST
Index: docs/modules/MIDI-Perl-0.8/MIDI/Event.pod
diff -u docs/modules/MIDI-Perl-0.8/MIDI/Event.pod:1.6 docs/modules/MIDI-Perl-0.8/MIDI/Event.pod:1.7
--- docs/modules/MIDI-Perl-0.8/MIDI/Event.pod:1.6 Tue Feb 8 01:15:17 2011
+++ docs/modules/MIDI-Perl-0.8/MIDI/Event.pod Sat May 4 05:17:24 2013
@@ -1,10 +1,14 @@
=encoding euc-jp
-=head1 名前
+=head1 NAME
+
+=begin original
MIDI::Event - MIDI events
+=end original
+
MIDI::Event - MIDIイベント
=head1 概要
@@ -21,36 +25,56 @@
=head1 説明
+=begin original
+
Functions and lists to do with with MIDI events and MIDI event structures.
+=end original
+
MIDIイベントを扱う関数とリスト、及びMIDIイベントの構造。
+=begin original
+
An event is a list, like:
+=end original
+
一つのイベントはこのようなリストである：
( 'note_on', 141, 4, 50, 64 )
+=begin original
+
where the first element is the event name, the second is the
delta-time, and the remainder are further parameters, per the
event-format specifications below.
+=end original
+
最初の要素はイベント名。二番目はデルタタイム。そして残りは追加パラメータで、
この後に出てくるイベント形式の仕様別パラメータである。
+=begin original
+
An I<event structure> is a list of references to such events -- a
"LoL". If you don't know how to deal with LoLs, you I<must> read
L<perllol>.
+=end original
+
一つのI<イベント構造体>は、このような諸イベントへのリファレンスのリスト、
すなわちリストのリスト(LoL)である。
もしLoLの扱いがわからないなら、L<perllpl>を読まなければI<ならない>。
=head1 小物
+=begin original
+
For your use in code (as in the code in the Synopsis), this module
provides a few lists:
+=end original
+
（概要に例示しているような）プログラム中で使うために、このモジュールは
ほんの少しであるがリストを提供している。
@@ -58,40 +82,62 @@
=item @MIDI_events
+=begin original
+
a list of all "MIDI events" AKA voice events -- e.g., 'note_on'
+=end original
+
ボイスメッセージ(voice events)と呼ばれる全MIDIイベントのリスト。例：'note_on'
=item @Text_events
+=begin original
+
a list of all text meta-events -- e.g., 'track_name'
+=end original
+
テキスト型のメタイベント。例：'track_name'
=item @Nontext_meta_events
+=begin original
+
all other meta-events (plus 'raw_data' and F-series events like
'tune_request').
+=end original
+
非テキスト型メタイベント（さらに'raw_data'や、'tune_request'のような
F系列のイベントも加わる）
=item @Meta_events
+=begin original
+
the combination of Text_events and Nontext_meta_events.
+=end original
+
テキスト型イベントと非テキスト型メタイベントの組み合わせ。
=item @All_events
+=begin original
+
the combination of all the above lists.
+=end original
+
以上あげた全てのリストの組み合わせ。
=back
=head1 関数
+=begin original
+
This module provides three functions of interest, which all act upon
event structures. As an end user, you probably don't need to use any
of these directly, but note that options you specify for
@@ -100,6 +146,8 @@
first two of the below functions. (The casual user should merely skim
this section.)
+=end original
+
このモジュールはイベント構造体に作用する三つの興味深い関数を提供する。
あなたがエンドユーザーなら、これらの関数を直接利用する必要はないだろう。
だが、from_fileやfrom_handleオプションとともに使うMIDI::Opus->newに指定する
@@ -110,10 +158,14 @@
=item MIDI::Event::decode( \$data, { ...options... } )
+=begin original
+
This takes a I<reference> to binary MIDI data and decodes it into a
new event structure (a LoL), a I<reference> to which is returned.
Options are:
+=end original
+
この関数はバイナリ形式のMIDIデータへのI<リファレンス>を引数に取り、
新しいイベント構造体（LoL）にデコードする。関数の戻り値はこの構造体への
リファレンスである。オプションは次の通り：
@@ -123,6 +175,8 @@
=item 'include' => LISTREF
+=begin original
+
I<If specified>, listref is interpreted as a reference to a list of
event names (e.g., 'cue_point' or 'note_off') such that only these
events will be parsed from the binary data provided. Events whose
@@ -130,6 +184,8 @@
in the event structure, and they won't be each passed to any callbacks
you may have specified.
+=end original
+
このオプションをI<指定すると>、リストリファレンスはイベント名
（例：'cue_point'や'note_off'）リストへのリファレンスとして解釈される。
このリストにあるイベント名だけが、与えられたバイナリデータからパースされる。
@@ -138,6 +194,8 @@
=item 'exclude' => LISTREF
+=begin original
+
I<If specified>, listref is interpreted as a reference to a list of
event names (e.g., 'cue_point' or 'note_off') that will NOT be parsed
from the binary stream; they'll be ignored -- i.e., they won't end up
@@ -149,6 +207,8 @@
efficiently for just a few specific event types, e.g., just text
events, or just sysexes.
+=end original
+
このオプションをI<指定すると>、リストリファレンスはイベント名
（例：'cue_point'や'note_off'）リストへのリファレンスとして解釈される。
このリストにあるイベント名はバイナリストリームから"パースされない"。
@@ -163,12 +223,18 @@
=item 'no_eot_magic' => 0 or 1
+=begin original
+
See the description of C<'end_track'>, in "EVENTS", below.
+=end original
+
後に出てくる"イベント"のC<'end_track'>の説明を参照。
=item 'event_callback' => CODEREF
+=begin original
+
If defined, the code referred to (whether as C<\&wanted> or as
C<sub { BLOCK }>) is called on every event after it's been parsed into
an event list (and any EOT magic performed), but before it's added to
@@ -176,6 +242,8 @@
way to the event structure (which counts as deep voodoo), define
'event_callback' and have it modify its C<@_>.
+=end original
+
サブルーチンへのリファレンス（C<\&wanted>でもC<sub { BLOCK }>でもよい）を定義
すると、データがイベントリストへとパースされた後、イベント毎にそのコードが
呼び出される（そして何らかのEOTマジックが実行される）。
@@ -185,11 +253,15 @@
=item 'exclusive_event_callback' => CODEREF
+=begin original
+
Just like 'event_callback'; but if you specify this, the callback is
called I<instead> of adding the events to the event structure. (So
the event structure returned by decode() at the end will always be
empty.) Good for cases like the text dumper in the Synopsis, above.
+=end original
+
'event_callback'と同じだ。ただしこのオプションを指定すると、イベントを
イベント構造体に付け加える代わりにコールバックが呼び出される（それゆえ、
最後にdecode()で返されるイベント構造体は常に空となる）。
@@ -199,9 +271,13 @@
=item MIDI::Event::encode( \@events, {...options...})
+=begin original
+
This takes a I<reference> to an event structure (a LoL) and encodes it
as binary data, which it returns a I<reference> to. Options:
+=end original
+
この関数はイベント構造体（LoL）へのI<リファレンス>を引数に取り、
バイナリデータとしてエンコードする。関数の戻り値はこのデータへのリファレンス
である。オプションは次の通り：
@@ -211,6 +287,8 @@
=item 'unknown_callback' => CODEREF
+=begin original
+
If this is specified, it's interpreted as a reference to a subroutine
to be called when an unknown event name (say, 'macro_10' or
something), is seen by encode(). The function is fed all of the event
@@ -218,38 +296,52 @@
this function is added to the encoded data stream -- so if you don't
want to add anything, be sure to return ''.
+=end original
+
このオプションに指定したサブルーチンへのリファレンスは、encode()が未知の
イベント名（例えば'macro_10'とか何か）に出くわしたときに呼び出される。
この関数にはイベントの要素全て（イベント名前、デルタタイム、その他の
パラメーター）が与えられ、戻り値はエンコードされたデータストリームに
追加される。だから、何も追加したくないなら必ず''（空文字）を返すようにすること。
+=begin original
+
If no 'unknown_callback' is specified, encode() will C<warn> (well,
C<carp>) of the unknown event. To merely block that, just set
'unknown_callback' to C<sub{return('')}>
+=end original
+
'unknown_callbackを指定しないと、encode()は未知のイベントに対しC<warn>
（あるいはC<carp>）を発生させる。これをさせないためには、'unknown_callback'
オプションにC<sub{return('')}>をセットすればよい。
=item 'no_eot_magic' => 0 or 1
+=begin original
+
Determines whether a track-final 0-length text event is encoded as
a end-track event -- since a track-final 0-length text event probably
started life as an end-track event read in by decode(), above.
+=end original
+
トラック終端の0長サイズのテキストイベントを、エンドオブトラックとしてエンコード
するかどうか決定する。というのも、トラック終端の0長サイズのテキストイベントは、
decode()が読み込むと、エンドオブトラックとして生成されるからだ。
=item 'never_add_eot' => 0 or 1
+=begin original
+
If 1, C<encode()> never ever I<adds> an end-track (EOT) event to the
encoded data generated unless it's I<explicitly> there as an
'end_track' in the given event structure. You probably don't ever
need this unless you're encoding for I<straight> writing to a MIDI
port, instead of to a file.
+=end original
+
1にすると、C<encode()>は自ら生成するエンコードデータにエンドオブトラック(EOT)を
加えなくなる。ただしイベント構造内に明示的に'end_track'がある場合は別だ。
あなたがファイルではなくてMIDIポートにI<直接>書き込もうとしない限り、
@@ -257,19 +349,27 @@
=item 'no_running_status' => 0 or 1
+=begin original
+
If 1, disables MIDI's "running status" compression. Probably never
necessary unless you need to feed your MIDI data to a strange old
sequencer that doesn't understand running status.
+=end original
+
1にするとランニングステータスが利用できなくなる。ランニングステータスを
理解しない古びて珍奇なシーケンサでも使わない限り、たぶんこのオプションは
必要ないだろう。
=back
+=begin original
+
Note: If you're encoding just a single event at a time or less than a
whole trackful in any case, then you probably want something like:
+=end original
+
注意：一度に一つのイベントだけをエンコードする場合、あるいはとにかく一度に
全トラックをエンコードしない場合、このようにするだろう：
@@ -280,17 +380,25 @@
],
{ 'never_add_eot' => 1} );
+=begin original
+
which just encodes that one event I<as> an event structure of one
event -- i.e., an LoL that's just a list of one list.
+=end original
+
これは、一つのイベントからなるイベント構造体I<として>一つのイベントを
エンコードしている。つまり、一つのLoLはまさに一つのリストのリストである。
+=begin original
+
But note that running status will not always apply when you're
encoding less than a whole trackful at a time, since running status
works only within a LoL encoded all at once. This'll result in
non-optimally compressed, but still effective, encoding.
+=end original
+
しかし注意したいのは、一度に全トラックをエンコードしないなら、
ランニングステータスは必ずしも適用されるとは限らないということだ。なぜなら
ランニングステータスは一度に全部エンコードされたLoLの中でのみ機能するからだ。
@@ -298,18 +406,26 @@
=item MIDI::Event::copy_structure()
+=begin original
+
This takes a I<reference> to an event structure, and returns a
I<reference> to a copy of it. If you're thinking about using this, you
probably should want to use the more straightforward
+=end original
+
この関数はイベント構造体へのリファレンスを引数に取り、コピーしたリファレンスを
返す。もしこの関数を使うことについて思案しているなら、もっと素直な使い方を
望むべきだろう。
$track2 = $track->copy
+=begin original
+
instead. But it's here if you happen to need it.
+=end original
+
これが代わりになる。
=back
@@ -318,8 +434,12 @@
=head2 データタイプ
+=begin original
+
Events use these data types:
+=end original
+
イベントはこれらのデータタイプを使用する：
=over
@@ -350,12 +470,16 @@
=back
+=begin original
+
For data types not defined above, (e.g., I<sf> and I<mi> for
C<'key_signature'>), consult L<MIDI::Filespec> and/or the source for
C<MIDI::Event.pm>. And if you don't see it documented, it's probably
because I don't understand it, so you'll have to consult a real MIDI
reference.
+=end original
+
上で定義していないデータタイプ（例：C<'key_signature'>用のI<sf>やI<mi>）
については、 L<MIDI::Filespec>やC<MIDI::Event.pm>のソースで調べて欲しい。
そのドキュメントにも書いていなければ、たぶん私の理解していないタイプなので、
@@ -363,8 +487,12 @@
=head2 イベント
+=begin original
+
And these are the events:
+=end original
+
イベント：
=over
@@ -443,24 +571,38 @@
=back
+=begin original
+
Three of the above events are represented a bit oddly from the point
of view of the file spec:
+=end original
+
上のイベントのうち三つは、標準MIDIファイルの仕様からすると少し変である。
+=begin original
+
The parameter I<pitch_wheel> for C<'pitch_wheel_change'> is a value
-8192 to 8191, although the actual encoding of this is as a value 0 to
16,383, as per the spec.
+=end original
+
C<'pitch_wheel_change'>用のI<pitch_wheel>は-8192から8191の値をとる。
しかし実際には、仕様書通り0から16,383としてエンコードされる。
+=begin original
+
Sysex events are represented as either C<'sysex_f0'> or C<'sysex_f7'>,
depending on the status byte they are encoded with.
+=end original
+
システムエクスクルーシブイベントはC<'sysex_f0'>かC<'sysex_f7'>として表される。
これは一緒にエンコードされたステータスバイトに依存している。
+=begin original
+
C<'end_track'> is a bit stranger, in that it is almost never actually
found, or needed. When the MIDI decoder sees an EOT (i.e., an
end-track status: FF 2F 00) with a delta time of 0, it is I<ignored>!
@@ -471,6 +613,8 @@
given a crack at it.) On the encoding side, an EOT is added to the
end of the track as a normal part of the encapsulation of track data.
+=end original
+
C<'end_track'>は奇妙な代物だ。実際、ほとんど見かけることも、必要とされることも
ない。MIDIデコーダーはEOT（エンドトラックステータス：FF 2F 00）を0のデルタタイム
とセットで見つけると無視してしまう！もしも0のデルタタイムでない珍しいイベント内
@@ -479,36 +623,52 @@
C<'exclusive_event_callback'>が実行される前に発生する）。エンコードする側から
すると、EOTはトラックデータを包む通常パートとしてトラックの最後に追加される。
+=begin original
+
I chose to add this special behavior so that you could add events to
the end of a track without having to work around any track-final
C<'end_track'> event.
+=end original
+
私がこの特殊な振る舞いを付け加えることを選択したのは、トラック終端の
C<'end_track'>を避けなくても、トラックの後ろにイベントを付け加えることが
できるようにするためである。
+=begin original
+
However, if you set C<no_eot_magic> as a decoding parameter, none of
this magic happens on the decoding side -- C<'end_track'> is decoded
just as it is.
+=end original
+
しかし、もしデコードのパラメータにC<no_eot_magic>をセットしたら、デコードする
側ではこの魔法は起きない。C<'end_track'>はそのままデコードされるのだ。
+=begin original
+
And if you set C<no_eot_magic> as an encoding parameter, then a
track-final 0-length C<'text_event'> with non-0 delta-times is left as
is. Normally, such an event would be converted from a C<'text_event'>
to an C<'end_track'> event with thath delta-time.
+=end original
+
そしてエンコードのパラメータにC<no_eot_magic>をセットしたなら、0でない
デルタタイムを伴う0長サイズのC<'text_event'>は、そのまま残される。
通常そのようなイベントは、C<'text_event'>からそのデルタタイムを伴った
C<'end_track'>に変換される。
+=begin original
+
Normally, no user needs to use the C<no_eot_magic> option either in
encoding or decoding. But it is provided in case you need your event
LoL to be an absolutely literal representation of the binary data,
and/or vice versa.
+=end original
+
通常、エンコード・デコードのいずれでも、C<no_eot_magic>オプションを使いたがる
人はいない。だが、あなたがイベントLoLをバイナリデータとして絶対的に文字通りの
表現にしたい場合には、そして・あるいは、その逆の場合には、このオプションを
@@ -517,23 +677,33 @@
=head1 MIDI BNF
+=begin original
+
For your reference (if you can make any sense of it), here is a copy
of the MIDI BNF, as I found it in a text file that's been floating
around the Net since the late 1980s.
+=end original
+
（あなたが理解できるとして）参考のために、MIDI BNFの写しを載せておく。
私はこれを1980年代後半以来ネットに出回っていたテキストファイルの中から
見つけだした。
+=begin original
+
Note that this seems to describe MIDI events as they can occur in
MIDI-on-the-wire. I I<think> that realtime data insertion (i.e., the
ability to have E<lt>realtime byteE<gt>s popping up in the I<middle>
of messages) is something that can't happen in MIDI files.
+=end original
+
これはMIDI通信で使われるものとして記述されていることに注意。リアルタイムデータ
挿入（リアルタイムのデータがメッセージの途中に飛び込んでくる）は、
MIDIファイルで生じうるようなものではないとI<思う>。
+=begin original
+
In fact, this library, as written, I<can't> correctly parse MIDI data
that has such realtime bytes inserted in messages. Nor does it
support representing such insertion in a MIDI event structure that's
@@ -542,6 +712,8 @@
C<raw_data> events; but then, you can always stow anything
at all in a C<raw_data> event.)
+=end original
+
実際、このライブラリは、これまで書いてきたように、データがメッセージに
リアルタイムに挿入されるようなMIDIデータを正しくパースすることはI<できない>。
MIDIイベント構造において、ファイルに書き込みをするためにエンコード可能な
Index: docs/modules/MIDI-Perl-0.8/MIDI/Opus.pod
diff -u docs/modules/MIDI-Perl-0.8/MIDI/Opus.pod:1.4 docs/modules/MIDI-Perl-0.8/MIDI/Opus.pod:1.5
--- docs/modules/MIDI-Perl-0.8/MIDI/Opus.pod:1.4 Thu Jan 27 22:14:57 2011
+++ docs/modules/MIDI-Perl-0.8/MIDI/Opus.pod Sat May 4 05:17:24 2013
@@ -1,10 +1,14 @@
=encoding euc-jp
-=head1 名前
+=head1 NAME
+
+=begin original
MIDI::Opus -- functions and methods for MIDI opuses
+=end original
+
MIDI::Opus -- MIDIオプス（ソング）のための関数とメソッド
=head1 概要
@@ -18,27 +22,39 @@
=head1 説明
+=begin original
+
MIDI::Opus provides a constructor and methods for objects
representing a MIDI opus (AKA "song"). It is part of the MIDI suite.
+=end original
+
MIDI::OpusはMIDIオプス（ソング）オブジェクトに対する
コンストラクタとメソッドを提供する。
このモジュールはMIDIパッケージの一部である。
+=begin original
+
An opus object has three attributes: a format (0 for MIDI Format 0), a
tick parameter (parameter "division" in L<MIDI::Filespec>), and a list
of tracks objects that are the real content of that opus.
+=end original
+
オプスオブジェクトは三つの属性を持つ：フォーマット（MIDI Fromat 0の'0'）、
ティック（L<MIDI::Filespec>における分解能）、そして
オプスの実質的な内容であるトラックオブジェクトのリスト。
+=begin original
+
Be aware that options specified for the encoding or decoding of an
opus may not be documented in I<this> module's documentation, as they
may be (and, in fact, generally are) options just passed down to the
decoder/encoder in MIDI::Event -- so see L<MIDI::Event> for an
explanation of most of them, actually.
+=end original
+
オプスのエンコード・デコードに対するオプション指定については、
I<この>モジュールドキュメント内では説明していないので注意すること。
これらのオプション指定は恐らく（実際に一般的にそうなのだが）MIDI::Eventの
@@ -48,14 +64,20 @@
=head1 コンストラクタとメソッド
+=begin original
+
MIDI::Opus provides...
+=end original
+
MIDI::Opusは以下を提供する。
=over
=item MIDI::Opus->new({ ...options... })
+=begin original
+
This returns a new opus object. The options, which are optional, is
an anonymous hash. By default, you get a new format-0 opus with no
tracks and a tick parameter of 96. There are six recognized options:
@@ -68,6 +90,8 @@
reference (e.g., C<*STDIN{IO}>), after having called binmode() on that
handle, if that's a problem.
+=end original
+
これは新規のオプスオブジェクトを返す。なくても良いオプションとして
無名ハッシュを引数にとる。デフォルトでは、トラック無し・ティック96・
フォーマット0のオプスを得ることになる。モジュールが認識できる六つの
@@ -79,17 +103,23 @@
（例えばC<*STDIN{IO}>）からオプスを読み込む。
問題がある場合はそのファイルハンドルに対しbinmode()を呼び出してから使う。
+=begin original
+
If you specify either C<from_file> or C<from_handle>, you probably
don't want to specify any of the other options -- altho you may well
want to specify options that'll get passed down to the decoder in
MIDI::Events, such as 'include' => ['sysex_f0', 'sysex_f7'], just for
example.
+=end original
+
C<from_file>かC<from_handle>を指定する際、他のオプションを指定したいとは
思わないだろう。にもかかわらずオプションを指定しようという場合は、
MIDI::Eventsのデコーダーに対してオプションを渡すことになる。
例えば 'include' => ['sysex_f0', 'sysex_f7'] 。
+=begin original
+
Finally, the option C<no_parse> can be used in conjuction with either
C<from_file> or C<from_handle>, and, if true, will block MTrk tracks'
data from being parsed into MIDI events, and will leave them as track
@@ -100,6 +130,8 @@
in code in MIDI::Track, but in a routine there that I've left
undocumented, as you should access it only thru here.)
+=end original
+
最後に、C<no_parse>オプションはC<from_file>かC<from_handle>とセットで使う。
このオプションに真値を設定した場合、MTrkトラックはMIDIイベントにパースされず、
トラックデータのままにされる（これは$track->dataで取得できる）。
@@ -111,44 +143,62 @@
=item $new_opus = $opus->copy
+=begin original
+
This duplicates the contents of the given opus, and returns
the duplicate. If you are unclear on why you may need this function,
read the documentation for the C<copy> method in L<MIDI::Track>.
+=end original
+
このメソッドはオプスの内容をコピーし、複製されたオブジェクトを返す。
なぜこの機能が必要なのかよくわからない場合は、L<MIDI::Track>の
C<copy>メソッドのドキュメントを読むこと。
=item $opus->tracks( @tracks )
+=begin original
+
Returns the list of tracks in the opus, possibly after having set it
to @tracks, if specified and not empty. (If you happen to want to set
the list of tracks to an empty list, for whatever reason, you have to
use "$opus->tracks_r([])".)
+=end original
+
オプスのトラックリストを返す。または、@tracksを指定し、それが空でなければ
内容をセットする（もしもトラックリストに空リストをセットしたいと思ったら、
理由は何であれ"$opus->tracks_r([])"を使わなければならない）。
+=begin original
+
In other words: $opus->tracks(@tracks) is how to set the list of
tracks (assuming @tracks is not empty), and @tracks = $opus->tracks is
how to read the list of tracks.
+=end original
+
つまり、（@tracksが空リストでないとして）$opus->tracks(@tracks)はトラック
リストのセット方法で、@tracks = $opus->tracksは取得方法ということだ。
=item $opus->tracks_r( $tracks_r )
+=begin original
+
Returns a reference to the list of tracks in the opus, possibly after
having set it to $tracks_r, if specified. "$tracks_r" can actually be
any listref, whether it comes from a scalar as in C<$some_tracks_r>,
or from something like C<[@tracks]>, or just plain old C<\@tracks>
+=end original
+
オプスのトラックリストのリファレンスを返す。$tracks_rを指定すると、その内容を
セットする。"$tracks_r"はリストリファレンスでありさえすればよいので、それが
C<$some_tracks_r>からなのか、C<[@tracks]>からなのか、あるいは古き簡素な
C<\@tracks>からであるかのかは問わない。
+=begin original
+
Originally $opus->tracks was the only way to deal with tracks, but I
added $opus->tracks_r to make possible 1) setting the list of tracks
to (), for whatever that's worth, 2) parallel structure between
@@ -156,6 +206,8 @@
directly manipulate the opus's tracks, without having to I<copy> the
list of tracks back and forth. This way, you can say:
+=end original
+
もともと$opus->tracksがトラックを扱う唯一の方法だった。だが私が
$opus->tracks_rを付け加えたのは、(1)トラックリストを何らかの有意義な理由で
丸括弧()にセットできるようにするため。(2)MIDI::Opus::tracks[_r]と
@@ -166,28 +218,42 @@
$tracks_r = $opus->tracks_r();
@some_stuff = splice(@$tracks_r, 4, 6);
+=begin original
+
But if you don't know how to deal with listrefs like that, that's OK,
just use $opus->tracks.
+=end original
+
だがこのようなリストリファレンスの扱い方を知らなくても、大丈夫。
$opus->tracksを使えばよい。
=item $opus->ticks( $tick_parameter )
+=begin original
+
Returns the tick parameter from $opus, after having set it to
$tick_parameter, if provided.
+=end original
+
$opusからティックの値を返す。$tick_parameterを与えればそれがセットされる。
=item $opus->format( $format )
+=begin original
+
Returns the MIDI format for $opus, after having set it to
$format, if provided.
+=end original
+
$opusのMIDIフォーマットの値を返す。$formatを与えればそれがセットされる。
=item $opus->dump( { ...options...} )
+=begin original
+
Dumps the opus object as a bunch of text, for your perusal. Options
include: C<flat>, if true, will have each event in the opus as a
tab-delimited line -- or as delimited with whatever you specify with
@@ -195,6 +261,8 @@
run, would/should reproduce the opus. For concision's sake, the track data
isn't dumped, unless you specify the option C<dump_tracks> as true.
+=end original
+
オプスオブジェクトをダンプしてテクストの塊にする。次のオプションを
とることができる：C<flat>に真値を与えると、オプスのイベントは全て
タブ区切りになる。あるいはc<delimiter>オプションで指定した区切りが使われる。
@@ -204,12 +272,16 @@
=item $opus->write_to_file('filespec', { ...options...} )
+=begin original
+
Writes $opus as a MIDI file named by the given filespec.
The options hash is optional, and whatever you specify as options
percolates down to the calls to MIDI::Event::encode -- which see.
Currently this just opens the file, calls $opus->write_to_handle
on the resulting filehandle, and closes the file.
+=end original
+
$opusを、指定した名前のMIDIファイルに書き出す。ハッシュをオプションとして
指定できる。指定したオプションは全てMIDI::Event::encodeを呼び出すときに
渡される（そちらを参照）。現在このメソッドは、ファイルを開き、ファイル
@@ -217,6 +289,8 @@
=item $opus->write_to_handle(IOREF, { ...options...} )
+=begin original
+
Writes $opus as a MIDI file to the IO handle you pass a reference to
(example: C<*STDOUT{IO}>).
The options hash is optional, and whatever you specify as options
@@ -224,6 +298,8 @@
Note that this is probably not what you'd want for sending music
to C</dev/sequencer>, since MIDI files are not MIDI-on-the-wire.
+=end original
+
リファレンスとして渡したIOハンドル（例：C<*STDOUT{IO}>）に対し、$opusを、
MIDIファイルとして書き出す。ハッシュをオプションとして指定できる。指定した
オプションは全てMIDI::Event::encodeを呼び出すときに渡される（そちらを参照）。
@@ -232,6 +308,8 @@
=item $opus->draw({ ...options...})
+=begin original
+
This currently experimental method returns a new GD image object that's
a graphic representation of the notes in the given opus. Options include:
C<width> -- the width of the image in pixels (defaults to 600);
@@ -248,6 +326,8 @@
colors -- they will be plotted with the color for channel
"channel_number % M" (where C<%> = the MOD operator).
+=end original
+
この現状実験的なメソッドは、新規のGDオブジェクトを返す。
このオブジェクトはオプスのノートをグラフィカルに表現するものだ。
オプションとして：C<width>…ピクセル単位の画像の横幅（デフォルトは600）、
@@ -260,30 +340,46 @@
もしチャンネル0からMまでの色を指定しただけなら、M以降のチャンネルのノートの色は
使いまわしになる -- これは"channel_number % M"（C<%>はMOD演算子）の色で表示される。
+=begin original
+
This means that if you specify
+=end original
+
このように指定した場合、次のことを意味する。
channel_colors => ['00ffff','0000ff']
+=begin original
+
then all the channels' notes will be plotted with an aqua pixel followed
by blue ones; and if you specify
+=end original
+
全てのチャンネルノートが、アクアブルーの後に青のピクセルで描画される。
また、次のように指定すると、
channel_colors => ['00ffff','0000ff', 'ff00ff','ff0000']
+=begin original
+
then all the I<even> channels' notes will be plotted with an aqua
pixel followed by blue ones, and all the I<odd> channels' notes will
be plotted with a purple pixel followed by red ones.
+=end original
+
偶数番号のチャンネルは全てアクアブルーの後に青のピクセルで描画され、
奇数番号のチャンネルは紫の後に赤のピクセルで描画される。
+=begin original
+
As to what to do with the object you get back, you probably want
something like:
+=end original
+
メソッドから得られたオブジェクトを扱うには次のようにすることになる。
$im = $chachacha->draw;
@@ -291,10 +387,16 @@
print OUT $im->gif;
close(OUT);
+=begin original
+
Using this method will cause a C<die> if it can't successfully C<use GD>.
+=end original
+
C<use GD>がうまくいかないでこのメソッドを使うと、C<die>が発生する。
+=begin original
+
I emphasise that C<draw> is expermental, and, in any case, is only meant
to be a crude hack. Notably, it does not address well some basic problems:
neither volume nor patch-selection (nor any notable aspects of the
@@ -304,6 +406,8 @@
specially represented, as it probably should be;
notes overlapping are not represented at all well.
+=end original
+
強調しておきたいのは、C<draw>は実験的であるということだ。いずれにせよ
このメソッドは未完成の仕組み(a crude hack)でしかない。特に、基本的な問題に
ちゃんと取り組んではいない。例えば：
@@ -317,10 +421,14 @@
=head1 デストラクタはどこか？
+=begin original
+
Because MIDI objects (whether opuses or tracks) do not contain any
circular data structures, you don't need to explicitly destroy them in
order to deallocate their memory. Consider this code snippet:
+=end original
+
（オプスかトラックかに関わらず）MIDIオブジェクトはいかなる循環構造データも
含まないので、メモリを綺麗にするために明示的にオブジェクトを破壊する必要はない。
この小さなコードを見てみよう：
@@ -331,41 +439,59 @@
print "$one has ", scalar( $opus->tracks ) " tracks\n";
}
+=begin original
+
At the end of each iteration of the foreach loop, the variable $opus
goes away, along with its contents, a reference to the opus object.
Since no other references to it exist (i.e., you didn't do anything like
push(@All_opuses,$opus) where @All_opuses is a global), the object is
automagically destroyed and its memory marked for recovery.
+=end original
+
foreachループの毎回の繰り返しの最後に変数$opusが消え去る。このとき一緒に
オプスオブジェクトのリファレンスも消える。（グローバルな@All_opusesに対して
push(@All_opuses,$opus)みたいなことをしていない場合）他に参照している
リファレンスが存在しないので、そのオブジェクトは自動的に破壊され、
メモリーは解放のための印がつく。
+=begin original
+
If you wanted to explicitly free up the memory used by a given opus
object (and its tracks, if those tracks aren't used anywhere else) without
having to wait for it to pass out of scope, just replace it with a new
empty object:
+=end original
+
オプスオブジェクトがスコープの外に出るまで待つのではなく、明示的に使用された
メモリーを解放したい場合、単に新規の空オブジェクトを代入すればよい。
$opus = MIDI::Opus->new;
+=begin original
+
or replace it with anything at all -- or even just undef it:
+=end original
+
あるいは代入するのは何でもいい -- undefしてもよい。
undef $opus;
+=begin original
+
Of course, in the latter case, you can't then use $opus as an opus
object anymore, since it isn't one.
+=end original
+
もちろん、後者の場合、その後$opusをオプスオブジェクトとして使うことはできない。
=head1 ティックについての注意
+=begin original
+
If you want to use "negative" values for ticks (so says the spec: "If
division is negative, it represents the division of a second
represented by the delta-times in the file,[...]"), then it's up to
@@ -373,6 +499,8 @@
it gets C<pack()>'d as an "n", it comes out right. I think it'll involve
something like:
+=end original
+
もしティックに負の値を使おうとするなら（仕様書には「分解能がマイナスの場合、
ファイルの中のデルタタイムを秒で表す…」とある）、"n"でC<pack()>することに
よって、曲全体を正しく表す方法を理解しなければならない。
@@ -381,20 +509,30 @@
$opus->ticks( (unpack('C', pack('c', -25)) << 8) & 80 );
+=begin original
+
for bit resolution (80) at 25 f/s.
+=end original
+
25 frames/sec のビット分解能(80) に対応する。
+=begin original
+
But I've never tested this. Let me know if you get it working right,
OK? If anyone I<does> get it working right, and tells me how, I'll
try to support it natively.
+=end original
+
ただし、私はこれを試したことはない。正しく動作したら知らせてくれないだろうか？
もし誰かがI<うまくいって>、どのようにやったかを私に教えてくれるなら、
この機能をネイティブにサポートしようと思う。
=head1 WARNとDIEの注意
+=begin original
+
In the case of trying to parse a malformed MIDI file (which is not a
common thing, in my experience), this module (or MIDI::Track or
MIDI::Event) may warn() or die() (Actually, carp() or croak(), but
@@ -407,6 +545,8 @@
(Or just trap the die in an eval { } around your call to anything you
think you could die.)
+=end original
+
不正な形式のMIDIファイル（共通の事象というよりも自分の経験からだが）を
パースしようとすると、このモジュール（あるいはMIDI::TrackやMIDI::Event）は
warn()かdie()するだろう（実際にはcarp()やcroak()かもしれないが、
Index: docs/modules/MIDI-Perl-0.8/MIDI/Score.pod
diff -u docs/modules/MIDI-Perl-0.8/MIDI/Score.pod:1.4 docs/modules/MIDI-Perl-0.8/MIDI/Score.pod:1.5
--- docs/modules/MIDI-Perl-0.8/MIDI/Score.pod:1.4 Thu Jan 27 22:14:57 2011
+++ docs/modules/MIDI-Perl-0.8/MIDI/Score.pod Sat May 4 05:17:24 2013
@@ -3,8 +3,12 @@
=head1 NAME
+=begin original
+
MIDI::Score - MIDI scores
+=end original
+
MIDI::Score - MIDIスコア
=head1 概要
@@ -13,22 +17,30 @@
=head1 説明
+=begin original
+
This module provides functions to do with with MIDI scores.
It is used as the basis for all the functions in MIDI::Simple.
(Incidentally, MIDI::Opus's draw() method also uses some of the
functions in here.)
+=end original
+
このモジュールはMIDIスコアを扱うための機能を提供する。
MIDI::Simpleの全ての機能の基として利用されている。
ちなみに、MIDI::Opusのdraw()メソッドもこのモジュールの機能の
一部を利用している。
+=begin original
+
Whereas the events in a MIDI event structure are items whose timing
is expressed in delta-times, the timing of items in a score is
expressed as an absolute number of ticks from the track's start time.
Moreover, pairs of 'note_on' and 'note_off' events in an event structure
are abstracted into a single 'note' item in a score structure.
+=end original
+
MIDIイベント構造体の中に入っている各イベントは、デルタタイムで表される
時間間隔を持った要素である。これに対してスコアの中の要素が持つ時間間隔は、
そのトラックの開始時間から計ったティックの絶対値として表現される。
@@ -36,25 +48,37 @@
ノートオフ（'note_off'）は、スコアの中では単体のノート（'note'）へと
抽象化される。
+=begin original
+
'note' takes the following form:
+=end original
+
ノート（'note'）は次の形式をとる：
('note', I<start_time>, I<duration>, I<channel>, I<note>, I<velocity>)
+=begin original
+
The problem that score structures are meant to solve is that 1)
people definitely don't think in delta-times -- they think in absolute
times or in structures based on that (like 'time from start of measure');
2) people think in notes, not note_on and note_off events.
+=end original
+
スコア構造体によって次の問題が解決する。
(1)人々は明らかにデルタタイムでは考えない。絶対時間か、上に述べた
ような構造（スタートからの時間）でもって考える。
(2)人々はノート（音符）で考えるのであって、ノートオンやノートオフで
ではない。
+=begin original
+
So, given this event structure:
+=end original
+
そこで、次のようなイベント構造体があるとする：
['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
@@ -94,8 +118,12 @@
['note_on', 0, 1, 25, 96],
['note_off', 192, 0, 1, 0],
+=begin original
+
here is the corresponding score sctructure:
+=end original
+
これに対応するスコア構造体は：
['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
@@ -119,38 +147,56 @@
['note', 1632, 96, 1, 29, 96],
['note', 1728, 192, 1, 25, 96]
+=begin original
+
Note also that scores aren't crucially ordered. So this:
+=end original
+
スコアは厳密に順番に並んでいるわけではない。だから：
['note', 768, 192, 1, 25, 96],
['note', 960, 96, 1, 29, 96],
['note', 1056, 96, 1, 25, 96],
+=begin original
+
means the same thing as:
+=end original
+
これは次のものと同じだ：
['note', 960, 96, 1, 29, 96],
['note', 768, 192, 1, 25, 96],
['note', 1056, 96, 1, 25, 96],
+=begin original
+
The only exception to this is in the case of things like:
+=end original
+
この唯一の例外は、次のようなケースの時だ：
['patch_change', 200, 2, 15],
['note', 200, 96, 2, 25, 96],
+=begin original
+
where two (or more) score items happen I<at the same time> and where one
affects the meaning of the other.
+=end original
+
二つ以上のスコア要素が同時に発生し、かつ、一つが他方の意味に
影響を与える場合。
=head1 スコアの中に何があるのか
+=begin original
+
Besides the new score structure item C<note> (covered above),
the possible contents of a score structure can be summarized thus:
Whatever can appear in an event structure can appear in a score
@@ -158,21 +204,29 @@
delta-time in ticks, but instead denotes the absolute number of ticks
from the start of the track.
+=end original
+
（先に述べた）C<note>以外に、スコア構造体が持ちうる構成要素をもとめると：
イベント構造体に現れるものは何でもスコア構造体に現れうるということだ。
要素が保持する第二パラメータはティックで表現されるデルタタイムではなく、
トラック開始からの絶対的なティックの数を意味している。
+=begin original
+
To avoid the long periphrase "items in a score structure", I will
occasionally refer to items in a score structure as "notes", whether or
not they are actually C<note> commands. This leaves "event" to
unambiguously denote items in an event structure.
+=end original
+
「スコア構造体の要素」などという回りくどい言い方は避けたいので、
私はしばしばこれをノート（"notes"）と呼ぶ。それが本当にC<note>コマンド
なのかどうかとは関係ない。"event"の方は、明確にイベント構造体の要素を
意味するよう、そのままにしておく。
+=begin original
+
These, below, are all the items that can appear in a score.
This is basically just a repetition of the table in
L<MIDI::Event>, with starttime substituting for dtime --
@@ -180,6 +234,8 @@
(like "velocity" or "pitch_wheel").
As far as order, the first items are generally the most important:
+=end original
+
以下はスコアに登場する全項目である。
基本的にL<MIDI::Event>にあった表の繰り返しでしかない。デルタタイムの
代わりにスタート時からのタイムに置き換わってはいるが。だから、
@@ -264,17 +320,25 @@
=head1 関数
+=begin original
+
This module provides these functions:
+=end original
+
このモジュールは以下の関数を提供する：
=over
=item $score2_r = MIDI::Score::copy_structure($score_r)
+=begin original
+
This takes a I<reference> to a score structure, and returns a
I<reference> to a copy of it. Example usage:
+=end original
+
この関数はスコア構造体へのリファレンスを引数にとり、そのコピーへの
リファレンスを返す。例えば：
@@ -284,12 +348,16 @@
=item ($events_r, $ticks) = MIDI::Score::score_r_to_events_r( $score_r )
+=begin original
+
This takes a I<reference> to a score structure, and converts it to an
event structure, which it returns a I<reference> to. In list context,
also returns a second value, a count of the number of ticks that
structure takes to play (i.e., the end-time of the temporally last
item).
+=end original
+
この関数はスコア構造体へのリファレンスを引数にとってイベント構造体に
変換し、そのリファレンスを返す。リストコンテキストでは、二つ目の値も
返す。これはその構造体が演奏に要するティックの総数（時間的に最後の
@@ -297,9 +365,13 @@
=item $score2_r = MIDI::Score::sort_score_r( $score_r)
+=begin original
+
This takes a I<reference> to a score structure, and returns a
I<reference> to a sorted (by time) copy of it. Example usage:
+=end original
+
この関数はスコア構造体へのリファレンスを引数にとり、（時間によって）
ソートされたコピーへのリファレンスを返す。例えば：
@@ -309,12 +381,16 @@
=item ($score_r, $ticks) = MIDI::Score::events_r_to_score_r( $events_r )
+=begin original
+
This takes a I<reference> to an event structure, converts it to a
score structure, which it returns a I<reference> to. If called in
list context, also returns a count of the number of ticks that
structure takes to play (i.e., the end-time of the temporally last
item).
+=end original
+
この関数はイベント構造体へのリファレンスを引数にとってスコア構造体に
変換し、そのリファレンスを返す。リストコンテキストでこの関数を
呼び出すと、その構造体が演奏に要するティックの総数（時間的に最後の項目の
@@ -322,18 +398,26 @@
=item $ticks = MIDI::Score::score_r_time( $score_r )
+=begin original
+
This takes a I<reference> to a score structure, and returns
a count of the number of ticks that structure takes to play
(i.e., the end-time of the temporally last item).
+=end original
+
この関数はスコア構造体へのリファレンスを引数にとり、その構造体が
演奏に要するティックの総数（時間的に最後の項目の終了時間）を返す。
=item MIDI::Score::dump_score( $score_r )
+=begin original
+
This dumps (via C<print>) a text representation of the contents of
the event structure you pass a reference to.
+=end original
+
この関数は（C<print>を通じて）リファレンス先のイベント構造体
[訳補足：スコア構造体の間違い？]の中身をテキスト表記でダンプする。
Index: docs/modules/MIDI-Perl-0.8/MIDI/Simple.pod
diff -u docs/modules/MIDI-Perl-0.8/MIDI/Simple.pod:1.3 docs/modules/MIDI-Perl-0.8/MIDI/Simple.pod:1.4
--- docs/modules/MIDI-Perl-0.8/MIDI/Simple.pod:1.3 Thu Jan 27 22:14:57 2011
+++ docs/modules/MIDI-Perl-0.8/MIDI/Simple.pod Sat May 4 05:17:24 2013
@@ -1,10 +1,14 @@
=encoding euc-jp
-=head1 名前
+=head1 NAME
+
+=begin original
MIDI::Simple - procedural/OOP interface for MIDI composition
+=end original
+
MIDI::Simple - MIDI作曲のための手続き的/オブジェクト指向的なインターフェース
=head1 概要
@@ -28,42 +32,62 @@
=head1 バージョン変更に関する注意
+=begin original
+
I consider this module a late-stage beta. Let me know if you run into
any problems, and feel free to suggest features.
+=end original
+
このモジュールは後半段階のベータ版である。何か問題が発生したら
私に知らせて欲しい。そしてお気軽に機能の提案をしていただきたい。
+=begin original
+
This module is somewhat incompatible with the MIDI::Simple versions
before .700.
+=end original
+
このモジュールはバージョン0.7以前のMIDI::Simpleとは少々互換性がない。
+=begin original
+
I think I've settled on (i.e., basically frozen) the basic interface
for this module, and will now hopefully only add functionality.
+=end original
+
このモジュールの基本的なインターフェースは決定済み（すなわち基本的に固定）
と考えている。そして今や機能の追加だけですむことを願っている。
=head1 説明
+=begin original
+
This module sits on top of all the MIDI modules -- notably MIDI::Score
(so you should skim L<MIDI::Score>) -- and is meant to serve as a
basic interface to them, for composition. By composition, I mean
composing anew; you can use this module to add to or modify existing
MIDI files, but that functionality is to be considered expermental.
+=end original
+
このモジュールは全てのMIDIモジュール -- 特にMIDI::Score（L<MIDI::Score>を
参照のこと） -- の上位に位置し、作曲のためのベーシックインターフェースの
役割を担っている。ここで作曲とは、新規作成のことだ。このモジュールを使って
既存のMIDIファイルに追加や修正が出来る。ただし、この機能は実験的なものだ。
+=begin original
+
This module provides two related but distinct bits of functionality:
1) a mini-language (implemented as procedures that can double as
methods) for composing by adding notes to a score structure; and 2)
simple functions for reading and writing scores, specifically the
scores you make with the composition language.
+=end original
+
このモジュールは二つの相互に関係した、しかし区別された機能を提供する：
(1)スコア構造体にノートを追加することによって作曲を行えるミニ言語
（プロシージャとしてもメソッドとしても実装されている）。
@@ -71,30 +95,42 @@
この作曲用言語で作ったスコアのことだが。
+=begin original
+
The fact that this module's interface is both procedural and
object-oriented makes it a definite two-headed beast. The parts of
the guts of the source code are not for the faint of heart.
+=end original
+
このモジュールのインターフェースがプロシージャかつオブジェクト指向である
という事実は、モジュールを双頭の獣にさせてしまっている。ソースコードの中身は
心臓の弱い方にはお勧めできない。
=head2 オブジェクトの構造
+=begin original
+
A MIDI::Simple object is a data structure with the following
attributes:
+=end original
+
MIDI::Simpleのオブジェクトは、次のような属性を持ったデータ構造である：
=over
=item Score（スコア）
+=begin original
+
This is a list of all the notes (each a listref) that constitute this
one-track musical piece. Scores are explained in L<MIDI::Score>.
You probably don't need to access the Score attribute directly, but be
aware that this is where all the notes you make with C<n> events go.
+=end original
+
これは1トラックの作品データを構成している全ノート（各々はリスト
リファレンス）のリストである。スコアについてはL<MIDI::Score>で説明して
ある。あなたが直接スコアの属性にアクセスする必要はないだろう。
@@ -103,82 +139,118 @@
=item Time（タイム）
+=begin original
+
This is a non-negative integer expressing the start-time, in ticks
from the start-time of the MIDI piece, that the next note pushed to
the Score will have.
+=end original
+
これはMIDIデータの開始からの時間を負でない整数で表したもので、
単位はティックだ。Scoreに追加される次のノートはこの値を持つ。
=item Channel（チャンネル）
+=begin original
+
This is a number in the range [0-15] that specifies the current default
channel for note events.
+=end original
+
これは0-15の範囲の値をとり、ノートイベントのために現在の既定のチャンネルを
指定する。
=item Duration（デュレーション：持続時間）
+=begin original
+
This is a non-negative (presumably nonzero) number expressing, in
ticks, the current default length of note events, or rests.
+=end original
+
これは負でない（たぶん0でない）数で、ノートや休止の現在のデフォルトの
長さを表す。単位はティック。
=item Octave（オクターブ）
+=begin original
+
This is a number in the range [0-10], expressing what the current
default octave number is. This is used for figuring out exactly
what note-pitch is meant by a relative note-pitch specification
like "A".
+=end original
+
これは0-10の範囲の数で現在のデフォルトのオクターブ番号が何であるかを表す。
これを使って、"A"のような音階の相対的指定が何を意味するのかを正確に
把握することができる。
=item Notes（ノート：音符）
+=begin original
+
This is a list (presumably non-empty) of note-pitch specifications,
I<as note numbers> in the range [0-127].
+=end original
+
これは音階指定のリスト（たぶん空ではない）で、0から127の
I<ノートナンバーとして>表される。
=item Volume（ボリューム）
+=begin original
+
This is an integer in the range [0-127] expressing the current default
volume for note events.
+=end original
+
これは0から127までの整数で、ノートに適用される現在のデフォルトの
ボリュームを表す。
=item Tempo（テンポ）
+=begin original
+
This is an integer expressing the number of ticks a quarter note
occupies. It's currently 96, and you shouldn't alter it unless you
I<really> know what you're doing. If you want to control the tempo of
a piece, use the C<set_tempo> routine, instead.
+=end original
+
四分音符に占めるティックの数を表す整数。デフォルトは96だが、自分が何を
やっているのかI<本当に>理解できていない限り、この値を変更すべきではない。
作品のテンポをコントロールしたいなら代わりにC<set_tempo>を使うこと。
=item Cookies
+=begin original
+
This is a hash that can be used by user-defined object-methods for
storing whatever they want.
+=end original
+
ユーザー定義のオブジェクトメソッドが必要なデータを保持するために
利用するハッシュ。
=back
+=begin original
+
Each package that you call the procedure C<new_score> from, has a
default MIDI::Simple object associated with it, and all the above
attributes are accessible as:
+=end original
+
C<new_sore>プロシージャから呼び出す全てのパッケージは、そのパッケージと
結びついたデフォルトのMIDI::Simpleオブジェクトを持っている。先に見た属性は
全て、次のようにしてアクセスできる。
@@ -186,11 +258,15 @@
@Score $Time $Channel $Duration $Octave
@Notes $Volume $Tempo %Cookies
+=begin original
+
(Although I doubt you'll use these from any package other than
"main".) If you don't know what a package is, don't worry about it.
Just consider these attributes synonymous with the above-listed
variables. Just start your programs with
+=end original
+
（あなたが"mian"パッケージ以外のパッケージからこれらを使うかどうか
わからないが、）パッケージが何か理解できなくても、心配いらない。
とにかく属性は上記の変数と同じ名前を持つと考えればいいだけだ。
@@ -199,130 +275,200 @@
use MIDI::Simple;
new_score;
+=begin original
+
and you'll be fine.
+=end original
+
とやれば問題ない。
=head2 ルーチン/メソッド/プロシージャ
+=begin original
+
MIDI::Simple provides some pure functions (i.e., things that take
input, and give a return value, and that's all they do), but what
you're mostly interested in its routines. By "routine" I mean a
subroutine that you call, whether as a procedure or as a method, and
that affects data structures other than the return value.
+=end original
+
MIDI::Simpleはいくつかの純粋な関数（インプットをとり、戻り値を返すだけのもの）を提供する。しかし、そのルーチンは大変興味深いものだ。私は「ルーチン」をあなたが呼び出すサブルーチンの意味で使っている。これはプロシージャかメソッドかは関係ない。そして戻り値ではなくデータ構造に影響を与える。
+=begin original
+
Here I'm using "procedure" to mean a routine you call like this:
+=end original
+
ここで私はプロシージャを次のような呼び出しをするルーチンの意味で使っている：
name(parameters...);
# or, just maybe:
name;
+=begin original
+
(In technical terms, I mean a non-method subroutine that can have side
effects, and which may not even provide a useful return value.) And
I'm using "method" to mean a routine you call like this:
+=end original
+
（技術的なことを言えば、副次効果をもたらす非メソッドなサブルーチンのことで、これは有益な戻り値をもたらさないだろう。）そしてメソッドとは次のような呼び出し方をするルーチンだ：
$object->name(parameters);
+=begin original
+
So bear these terms in mind when you see routines below that act
like one, or the other, or both.
+=end original
+
これから先、一方か他方、あるいはその両方の振る舞いをするルーチンを見たら、
これらの言葉を思い出して欲しい。
=head2 MAIN ROUTINES
+=begin original
+
These are the most important routines:
+=end original
+
最重要のルーチン：
=over
=item new_score() または $obj = MIDI::Simple->new_score()
+=begin original
+
As a procedure, this initializes the package's default object (Score,
etc.). As a method, this is a constructor, returning a new
MIDI::Simple object. Neither form takes any parameters.
+=end original
+
プロシージャとしてこのルーチンはパッケージのデフォルトオブジェクト
（Score等）を初期化する。メソッドとしてはこのルーチンはコンストラクタ
として機能し、新規のMIDI::Simpleオブジェクトを返す。どちらも引数をとらない。
=item n(...parameters...) または $obj->n(...parameters...)
+=begin original
+
This uses the parameters given (and/or the state variables like
Volume, Channel, Notes, etc) to add a new note to the Score -- or
several notes to the Score, if Notes has more than one element in it
-- or no notes at all, if Notes is empty list.
+=end original
+
このルーチンは与えられたパラメータ（Volume、Channel、Notes等々）を利用してScoreに新規のノートを追加する。あるいは、ノートが複数の要素をもっているならScoreにいくつかのノートを付け加える。もしNotesが空リストなら、ノートは付け加わらない。
+=begin original
+
Then it moves Time ahead as appropriate. See the section "Parameters
For n/r/noop", below.
+=end original
+
それからTimeを適切に進める。下の"n/r/nopのパラメータ"の所を見て欲しい。
=item r(...parameters...) or $obj->r(...parameters...)
+=begin original
+
This is exactly like C<n>, except it never pushes anything to Score,
but moves ahead Time. (In other words, there is no such thing as a
rest-event; it's just a item during which there are no note-events
playing.)
+=end original
+
このルーチンはC<n>とそっくりだ。例外はといえば、Timeを進める以外何もScoreに付け加えないということだけだ。（つまり、休止イベントのようなものは存在せず、ただノートイベントのない項目ということ。）
=item noop(...parameters...) or $obj->noop(...parameters...)
+=begin original
+
This is exactly like C<n> and C<r>, except it never alters Score,
I<and> never changes Time. It is meant to be used for setting the
other state variables, i.e.: Channel, Duration, Octave, Volume, Notes.
+=end original
+
このルーチンはC<n>とそっくりだ。例外はScoreI<と>Timeに変更を加えないということだ。他のステータス変数、つまりChannel、Duration、Octave、Volume、Notesをセットするために使われる。
=back
=head2 n/r/noopのパラメータ
+=begin original
+
A parameter in an C<n>, C<r>, or C<noop> call is meant to change an
attribute (AKA state variable), namely Channel, Duration, Octave,
Volume, or Notes.
+=end original
+
C<n>、C<r>、やC<noop>を呼び出す際のパラメータは、属性（ステータス変数）、すなわちChannel、Duration、Octave、Volume、Notesを変更する。
+=begin original
+
Here are the kinds of parameters you can use in calls to n/r/noop:
+=end original
+
n/r/noopの呼び出しに利用できるパラメータは：
+=begin original
+
* A numeric B<volume> parameter. This has the form "V" followed by a
positive integer in the range 0 (completely inaudible?) to 127 (AS
LOUD AS POSSIBLE). Example: "V90" sets Volume to 90.
+=end original
+
※数値によるB<volume>パラメータ。これは"V"の後に0（完全に聞こえない？）から127（可能な限り 大 き く）までの正の整数が続く形式を持つ。例："V90"はボリュームを90にセットする。
+=begin original
+
* An alphanumeric B<volume> parameter. This is a key from the hash
%MIDI::Simple::Volume. Current legal values are "ppp", "pp", "p",
"mp", "mezzo" (or "m"), "mf", "f", "ff", and "fff". Example: "ff"
sets Volume to 112. (Note that "m" isn't a good bareword, so use
"mezzo" instead, or just always remember to use quotes around "m".)
+=end original
+
※アルファベットによるB<volume>パラメータ。これは%MIDI::Simple::Volumeのキーである。現在適正な値は、"ppp"、"pp"、"p"、"mp"、"mezzo"（"m"）、"mf"、"f"、"ff"、"fff"。例："ff"はボリュームに112をセットする（"m"は裸のワードとしては具合がよろしくないので、代わりに"mezzo"を使うこと。あるいは常に"m"をクォートで囲んでおくことを忘れないようにする）。
+=begin original
+
* A numeric B<channel> parameter. This has the form "c" followed by a
positive integer 0 to 15. Example: "c2", to set Channel to 2.
+=end original
+
※数値による B<channel>パラメータ。これは"c"の後に0から15までの正の整数が続く形式を持つ。例："c2"はチャンネルに2をセットする。
+=begin original
+
* A numeric B<duration> parameter. This has the form "d" followed by
a positive (presumably nonzero) integer. Example: "d48", to set
Duration to 48.
+=end original
+
※数値によるB<duration>パラメータ。これは"d"の後に正の（たぶん0は入らない）整数が続く形式を持つ。例："d48"はデュレーションに48をセットする。
+=begin original
+
* An alphabetic (or in theory, possibly alphanumeric) B<duration>
parameter. This is a key from the hash %MIDI::Simple::Length.
Current legal values start with "wn", "hn", "qn", "en", "sn" for
@@ -337,8 +483,12 @@
whatever abbreviations you want, as long as the parser can't mistake
them for any other kind of n/r/noop parameter.
+=end original
+
※アルファベット（論理的にはアルファベットと数）によるB<duration>。これは%MIDI::Simple::Lengthのキーだ。現在適正な値としては、全音符、二分音符、四分音符、八分音符、十六分音符に対応して、"wn"、 "hn"、 "qn"、"en"、"sn"がある。これらの最初に"d"を付け加えることで「付点〜」を得ることができる（例："dqn"は付点四分音符）。先頭に"dd"を付けると「複付点〜」を得ることができる（例："ddqn"は複付点四分音符）。先頭に"t"を付けることで「三連〜」を得ることができる（"tsn"は三連十六分音符、つまり八分音符の長さの所に三つ音符が入る）。パーサーが他のn/r/noopのパラメータのものと取り違えない限り、あなたの望む略譜を%MIDI::Simple::Lengthに付け加えることができる。
+=begin original
+
* A numeric, absolute B<octave> specification. This has the form: an
"o" (lowercase oh), and then an integer in the range 0 to 10,
representing an octave 0 to 10. The Octave attribute is used only in
@@ -346,8 +496,12 @@
this section. (All absolute note specifications also set Octave to
whatever octave they occur in.)
+=end original
+
※数値によるB<octave>の絶対指定。これは次の形式："o"（小文字のオー）と、その後ろに0から10の整数（オクターブ0〜10）。このセクションのもう少し後で説明するように、オクターブ属性はノートの相対指定を解決する際にのみ用いられる（ノートの絶対指定は全て、それがどのオクターブにあるのかを設定する）。
+=begin original
+
* A numeric, relative B<octave> specification. This has the form:
"o_d" ("d" for down) or "o_u" ("u" for down), and then an integer.
This increments, or decrements, Octave. E.g., if Octave is 6, "o_d2"
@@ -356,115 +510,189 @@
10. (For more information, see the section "Invalid or Out-of-Range
Parameters to n/r/noop", below.)
+=end original
+
※数値によるB<octave>の絶対指定。これは次の形式："o_d"（"d"は下がるの意味）か"o_u"（uは上がるの意味[訳補足：原文は下がるになっている]）とその後ろに整数。これはオクターブ上げたり、下げたりする。例えば、オクターブが6の時、"o_d2"は二つ下げてオクターブ4にする。もしこれによってオクターブが0より小さい値になっても、強制的に0になる。また、オクターブが10より大きくなったら、強制的に10になる（詳細は後で出てくる"/n/r/noopのパラメータが不正、あるいは範囲を超えた場合"を参照のこと）。
+=begin original
+
* A numeric, absolute B<note> specification. This has the form: an
optional "n", and then an integer in the range 0 to 127, representing
a note ranging from C0 to G10. The source to L<MIDI> has a useful
reference table showing the meanings of given note numbers. Examples:
"n60", or "60", which each add a 60 to the list Notes.
+=end original
+
※数値によるB<note>の絶対指定。これは次の形式：省略可能な"n"とその後にC0からG10を表す0から127までの整数値。L<MIDI>のソースには、ノートナンバーの意味を示す便利なリファレンス表が入っている。例："n60"もしくは"60"とやると、Notesリストに60が追加される。
+=begin original
+
Since this is a kind of absolute note specification, it sets Octave to
whatever octave the given numeric note occurs in. E.g., "n60" is
"C5", and therefore sets Octave to 5.
+=end original
+
これは一種の絶対指定なので、数値で指定されたノートにはオクターブがセットされる。例えば、"n60"は"C5"なので、オクターブには5がセットされる。
+=begin original
+
The setting of the Notes list is a bit special, compared to how
setting the other attributes works. If there are any note
specifications in a given parameter list for n, r, or noop, then all
those specifications together are assigned to Notes.
+=end original
+
ノートリストへのセットは、他の属性へのセットの仕方に比べて少し特殊だ。n/r/noopのパラメーターリストに何らかのノート指定をすると、それらの指定は全て一緒にノートに足される。
+=begin original
+
If there are no note specifications in the parameter list for n, r, or
noop, then Notes isn't changed. (But see the destription of "rest",
at the end of this section.)
+=end original
+
n/r/noopのパラメーターリストにノート指定をしない場合、ノートは変化しない（ただしこのセクションの最後、"休符"の説明を見ること）。
+=begin original
+
So this:
+=end original
+
だから：
n mf, n40, n47, n50;
+=begin original
+
sets Volume to 80, and Notes to (40, 47, 50). And it sets Octave,
first to 3 (since n40 is in octave 3), then to 3 again (since n47 =
B3), and then finally to 4 (since n50 = D4).
+=end original
+
これはボリュームに80、それからノートに40,47,50がセットされる。そしてオクターブは最初のノートに3（n40はオクターブ3だから）、次にもう一度3（n47=B3）、最後に4（n50=D4）がセットされる。
+=begin original
+
Note that this is the same as:
+=end original
+
これは次のものと同じことに注意：
n n40, n47, n50, mf;
+=begin original
+
The relative orders of parameters is B<usually> irrelevant; but see
the section "Order of Parameters in a Call to n/r/noop", below.
+=end original
+
パラメータの相対的な順番はB<通常>どうでもよい。だが後に出てくるn/r/noopの呼び出しにおけるパラメータの順番"を参照のこと。
+=begin original
+
* An alphanumeric, absolute B<note> specification.
+=end original
+
※アルファベットと数値によるB<note>の絶対指定。
+=begin original
+
These have the form: a string denoting a note within the octave (as
determined by %MIDI::Simple::Note -- see below, in the description of
alphanumeric, relative note specifications), and then a number
denoting the octave number (in the range 0-10). Examples: "C3",
"As4" or "Asharp4", "Bf9" or "Bflat9".
+=end original
+
次の形式を持つ：オクターブの取りうる範囲内（%MIDI::Simple::Noteに定められている--下のアルファベットと数値、ノートの相対指定の説明を参照）の音符を意味する文字列と、その後ろにオクターブ番号を表す数（0〜10）。例："Cd"、"As4"あるいは"Asharp4"、"Bf9"あるいは"Bflat9"。
+=begin original
+
Since this is a kind of absolute note specification, it sets Octave to
whatever octave the given numeric note occurs in. E.g., "C3" sets
Octave to 3, "As4" sets Octave to 4, and "Bflat9" sets Octave to 9.
+=end original
+
これは一種の絶対指定なので、数値で指定されたノートにはオクターブがセットされる。例えば、"C3"はオクターブに3を、"As4"はオクターブに4を、"Bflat9"はオクターブに9をセットする。
+=begin original
+
This:
+=end original
+
つまり：
n E3, B3, D4, mf;
+=begin original
+
does the same as this example of ours from before:
+=end original
+
これは次の例と同じことだ。
n n40, n47, n50, mf;
+=begin original
+
* An alphanumeric, relative B<note> specification.
+=end original
+
※アルファベットによるB<note>の相対指定。
+=begin original
+
These have the form: a string denoting a note within the octave (as
determined by %MIDI::Simple::Note), and then an optional parameter
"_u[number]" meaning "so many octaves up from the current octave" or
"_d[parameter]" meaning "so many octaves down from the current
octave".
+=end original
+
次の形式を持つ：オクターブの範囲内（%MIDI::Simple::Noteによって定められている）で音符を意味する文字列と、その後ろに省略可能なパラメータ"_u[数値]"（数値分だけ現在のオクターブよりあげる）か"_d[数値]"（数値分だけ現在のオクターブより下げる）。
+=begin original
+
Examples: "C", "As" or "Asharp", "Bflat" or "Bf", "C_d3", "As_d1" or
"Asharp_d1", "Bflat_u3" or "Bf_u3".
+=end original
+
例："C"、"As"か"Asharp"、"Bflat"か"Bf"、"C_d3"、"As_d1"か"Asharp_d1"、"Bflat_u3"か"Bf_u3"。
+=begin original
+
In resolving what actual notes these kinds of specifications denote,
the current value of Octave is used.
+=end original
+
このような指定をされた実際のノートが何を表しているのかを解決するために、現在のオクターブの値が使用される。
+=begin original
+
What's a legal for the first bit (before any optional octave up/down
specification) comes from the keys to the hash %MIDI::Simple::Note.
The current acceptable values are:
+=end original
+
何が先頭文字（オクターブの上げ下げを指定するオプションの前の部分）として適正かは、%MIDI::Simple::Noteのキーで決まる。現在取りうる値は：
C (maps to the value 0)
@@ -480,11 +708,15 @@
As or Bf or Asharp or Bflat (maps to the value 10)
B (maps to the value 11)
+=begin original
+
(Note that these are based on the English names for these notes. If
you prefer to add values to accomodate other strings denoting notes in
the octave, you may do so by adding to the hash %MIDI::Simple::Note
like so:
+=end original
+
これらはその音符に対応する音符英語名に基づいている。そのオクターブ内で音符を意味する他の文字列を利用するために値を付け加えたほうがよいなら、%MIDI::Simple::Noteに次のように付け加えることができる：
use MIDI::Simple;
@@ -495,15 +727,23 @@
# ...等々...
);
+=begin original
+
But the values you add must not contain any characters outside the
range [A-Za-z\x80-\xFF]; and your new values must not look like
anything that could be any other kind of specification. E.g., don't
add "mf" or "o3" to %MIDI::Simple::Note.)
+=end original
+
付け加える値には、[A-Za-z\x80-\xFF]の範囲外のいかなるキャラクタも含んではならない。そしてまた、他の指定に使用されうるものと同じであってはならない。例えば、"mf"や"o3"を%MIDI::Simple::Noteに加えてはならない。
+=begin original
+
Consider that these bits of code all do the same thing:
+=end original
+
同じことをするコードを考えてみると：
n E3, B3, D4, mf; # way 1
@@ -515,14 +755,20 @@
noop o3, mf; # way 4
n E, B, D_u1;
+=begin original
+
or even
+=end original
+
さらに同じ：
n o3, E, B, o4, D, mf; # way 5!
n o6, E_d3, B_d3, D_d2, mf; # way 6!
+=begin original
+
If a "_d[number]" would refer to a note in an octave below 0, it is
forced into octave 0. If a "_u[number]" would refer to a note in an
octave above 10, it is forced into octave 10. E.g., if Octave is 8,
@@ -531,13 +777,19 @@
(For more information, see the section "Invalid or Out-of-Range
Parameters to n/r/noop", below.)
+=end original
+
もし"_d[number]"によってオクターブの値が0より小さいノートを示すことになったら、強制的にオクターブは0にセットされる。"_u[number]"によってオクターブの値が10より大きいノートを示すことになったら、強制的にオクターブは10にセットされる。例えば：オクターブが8のとき、"G_u4"は"G10"と同じことになる（範囲を超えるのでG12にはならない）。オクターブが2なら、"G_d4"は"G0"になる（詳細は後で出てくる"/n/r/noopのパラメータが不正、あるいは範囲を超えた場合"を参照のこと）。
+=begin original
+
* The string "C<rest>" acts as a sort of note specification -- it sets
Notes to empty-list. That way you can make a call to C<n> actually
make a rest:
+=end original
+
※文字列C<rest>はノート指定の一種として振る舞う。--ノートに空リストをセットする。C<n>を呼び出すやり方で実際上休符を作り出す。
n qn, G; # 四分音符のGを生成
@@ -548,57 +800,91 @@
n rest; # 四分休符
n; # もう一回四分休符
+=begin original
+
(If you can follow the above code, then you understand.)
+=end original
+
（上のコードを追えるなら、あなたは理解している）
+=begin original
+
A "C<rest>" that occurs in a parameter list with other note specs
(e.g., "n qn, A, rest, G") has B<no effect>, so don't do that.
+=end original
+
他のノート指定を伴うパラメータリストに現れる"C<rest>"（例："n qn, A, rest, G"）はB<無効>なので、何もしない。
=head2 n/r/noopの呼び出しにおけるパラメータの順番
+=begin original
+
The order of parameters in calls to n/r/noop is not important except
insofar as the parameters change the Octave parameter, which may change
how some relative note specifications are resolved. For example:
+=end original
+
n/r/noopの呼び出しにおけるパラメータの順番は、オクターブを変化させるパラメータを除いて、重要ではない。なぜならオクターブを変化させるパラメータは、ノートの相対指定の解決方法を変化させるかもしれないからだ。例えば：
noop o4, mf;
n G, B, A3, C;
+=begin original
+
is the same as "n mf, G4, B4, A3, C3". But just move that "C" to the
start of the list:
+=end original
+
これは"n mf, G4, B4, A3, C3"と同じだ。だが"C"をリストの最初に持ってくると：
noop o4, mf;
n C, G, B, A3;
+=begin original
+
and you something different, equivalent to "n mf, C4, G4, B4, A3".
+=end original
+
そしてこれは先ほどとは違って、"n mf, C4, G4, B4, A3"になる。
+=begin original
+
But note that you can put the "mf" anywhere without changing anything.
+=end original
+
"mf"は他に影響を与えないので、どこに置いてもよいことに注意。
+=begin original
+
But B<stylistically>, I strongly advise putting note parameters at the
B<end> of the parameter list:
+=end original
+
しかし体裁を考えて、音符パラメータはリストの最後に置くことを強くお勧めする。
n mf, c10, C, B; # 1. 良い
n C, B, mf, c10; # 2. 悪い
n C, mf, c10, B; # 3. 大変悪い！
+=begin original
+
3 is particularly bad because an uninformed/inattentive reader may get
the impression that the C may be at a different volume and on a
different channel than the B.
+=end original
+
3番目は特にまずくて、生真面目/不注意な読み手は、Cが違うボリュームであるとか、Bとは違うチャンネルにあるなどの印象を持ってしまうかもしれない。
+=begin original
+
(Incidentally, "n C5,G5" and "n G5,C5" are the same for most purposes,
since the C and the G are played at the same time, and with the same
parameters (channel and volume); but actually they differ in which
@@ -607,20 +893,32 @@
you're manipulating the note-items in Score or the MIDI events in a
track.)
+=end original
+
（ちなみに、"n C5,G5"と"n G5,C5"はほとんどの場合同じである。というのも、CとGは同時に演奏され、同じパラメータ（チャンネルとボリューム）を持つからだ。だが音符がスコアの最初に置かれ、MIDIファイルの最初にエンコードされる場合には、実際上の違いが生じる。もっとも、スコア内のノート項目か、トラック内のMIDIイベントを操作しない限り、違いは生じない。）
=head2 /n/r/noopのパラメータが不正、あるいは範囲を超えた場合
+=begin original
+
If a parameter in a call to n/r/noop is uninterpretable, Perl dies
with an error message to that effect.
+=end original
+
n/r/noopを呼び出す際のパラメータが解釈不能な場合、Perlはその効果に関するエラーメッセージを伴ってdieする。
+=begin original
+
If a parameter in a call to n/r/noop has an out-of-range value (like
"o12" or "c19"), Perl dies with an error message to that effect.
+=end original
+
n/r/noopを呼び出す際のパラメータが範囲を超えている場合（"o12"とか"c19"のように）、Perlはその効果に関するエラーメッセージを伴ってdieする。
+=begin original
+
As somewhat of a merciful exception to this rule, if a parameter in a
call to n/r/noop is a relative specification (whether like "o_d3" or
"o_u3", or like "G_d3" or "G_u3") which happens to resolve to an
@@ -630,21 +928,31 @@
lower), or down into 9 or 10 (if it would have been an octave higher
than 10, or a note higher than G10), as appropriate.
+=end original
+
このルールには幸運な例外があって、n/r/noopを呼び出す際のパラメータが相対指定("o_d3"や"o_u3"とか、"G_d3"や"G_u3"など) の時、それが範囲外の値を解決しなければならなくなった場合（オクターブの値が2の時に"G_d3"が与えるなどのような場合）、PerlはdieしI<ない>。その代わりに黙ってそのノートを強制的に0にまで上げる（0未満の場合）か、9なしは10にまで下げる（10より高いオクターブになってしまったり、G10よりも高いノートになった場合）ことによって、範囲内に収めようと試みる。
+=begin original
+
(This becomes strange in that, given an Octave of 8, "G_u4" is forced
down to G10, but "A_u4" is forced down to an A9. But that boundary
has to pop up someplace -- it's just unfortunate that it's in the
middle of octave 10.)
+=end original
+
（次のような場合、奇妙なことが起こる。すなわち、オクターブ8が与えられ時"G_u4"は強制的にG10になるが"A_u4"はA9になる。これは不幸なことにAがオクターブ10の真ん中にあるためだ。）
=head2 属性メソッド
+=begin original
+
The object attributes discussed above are readable and writeable with
object methods. For each attribute there is a read/write method, and a
read-only method that returns a reference to the attribute's value:
+=end original
+
以上見てきたオブジェクトの属性はオブジェクトメソッドで読み書きができる。全ての属性について、読み書き用のメソッドと、属性値へのリファレンスを返す読み込み専用メソッドが存在する：
Attribute || R/W-Method || RO-R-Method
@@ -659,33 +967,53 @@
Tempo || Tempo || Tempo_r (returns a scalar ref)
Cookies || Cookies || Cookies_r (returns a hashref)
+=begin original
+
To read any of the above via a R/W-method, call with no parameters,
e.g.:
+=end original
+
読み書きメソッドを通じて上の属性を読み込むには、パラメータ無しでメソッドを呼べばよい。例えば：
$notes = $obj->Notes; # $obj->Notes() と同じ
+=begin original
+
The above is the read-attribute ("get") form.
+=end original
+
上のは読み取り属性("get")形式。
+=begin original
+
To set the value, call with parameters:
+=end original
+
値をセットするには、パラメータなしでメソッドを呼び出す：
$obj->Notes(13,17,22);
+=begin original
+
The above is the write-attribute ("put") form. Incidentally, when
used in write-attribute form, the return value is the same as the
parameters, except for Score or Cookies. (In those two cases, I've
suppressed it for efficiency's sake.)
+=end original
+
上のは書き込む属性("put")形式。
+=begin original
+
Alternately (and much more efficiently), you can use the read-only
reference methods to read or alter the above values;
+=end original
+
上記の値を読みとったり変更したりするための別の方法として（そしてより効率的な方法として）、読み込み専用のリファレンス用メソッドを利用できる。
$notes_r = $obj->Notes_r;
@@ -694,28 +1022,44 @@
# 書き込み:
@$notes_r = (13,17,22);
+=begin original
+
And this is the only way to set Cookies, Notes, or Score to a (),
like so:
+=end original
+
そしてこれはCookies、NotesやScoreに空リスト()をセットする唯一の方法である。
$notes_r = $obj->Notes_r;
@$notes_r = ();
+=begin original
+
Since this:
+=end original
+
このため：
$obj->Notes;
+=begin original
+
is just the read-format call, remember?
+=end original
+
これは単なる読み取り形式の呼び出しだ、覚えた？
+=begin original
+
Like all methods in this class, all the above-named attribute methods
double as procedures that act on the default object -- in other words,
you can say:
+=end original
+
このクラスの全てのメソッド同様、上で名前の挙がった属性メソッドはデフォルトオブジェクトに対し作用するプロシージャとしての機能も持つ。つまり、このように書ける：
Volume 10; # 右と同じこと： $Volume = 10;
@@ -724,27 +1068,39 @@
$score_ref = Score_r; # 右と同じこと： $score_ref = \@Score
Volume(Volume + 10) # 右と同じこと： $Volume += 10
+=begin original
+
But, stylistically, I suggest not using these procedures -- just
directly access the variables instead.
+=end original
+
だが体裁を考えると、こういったプロシージャは使わない方がいい。代わりに直接変数にアクセスするべきだ。
=head2 MIDIイベントルーチン
+=begin original
+
These routines, below, add a MIDI event to the Score, with a
start-time of Time. Example:
+=end original
+
下に挙げるこれらのルーチンは、Timeの開始時間を伴ってScoreにMIDIイベントを追加する。例として：
text_event "And now the bongos!"; # プロシージャとして使う
$obj->text_event "And now the bongos!"; # メソッドとして使う
+=begin original
+
These are named after the MIDI events they add to the score, so see
L<MIDI::Event> for an explanation of what the data types (like
"velocity" or "pitch_wheel") mean. I've reordered this list so that
what I guess are the most important ones are toward the top:
+=end original
+
これらのルーチンには、そのルーチンがスコアに付け加えるMIDIイベントの名前がつけられいる。よって、そのデータタイプ（"velocity"や"pitch_wheel"など）が何を意味しているのかについての説明は、L<MIDI::Event>を参照のこと。
=over
@@ -792,8 +1148,12 @@
=back
+=begin original
+
And here's the ones I'll be surprised if anyone ever uses:
+=end original
+
そして、もしも誰かが使ったなら、私が驚いてしまうであろうルーチンもある。
=over
@@ -832,6 +1192,8 @@
=head2 テンポ(Tempo)について
+=begin original
+
The chart above shows that tempo is set with a method/procedure that
takes the form set_tempo(I<tempo>), and L<MIDI::Event> says that
I<tempo> is "microseconds, a value 0 to 16,777,215 (0x00FFFFFF)".
@@ -839,6 +1201,8 @@
MIDI::Simple object called "Tempo", which I've warned you to leave at
the default value of 96. So you may wonder what the deal is.
+=end original
+
上のチャートが示しているように、テンポはset_tempo(I<tempo>)という形式の
メソッド/プロシージャによってセットされる。そしてL<MIDI::Event>で述べて
いるように、I<tempo>は"マイクロ秒、0〜16,777,215 (0x00FFFFFF)の値"である。
@@ -846,6 +1210,8 @@
これについて私は、デフォルト値の96のままにするよう警告してある。
Tempとは何なのか詳細が知りたい人がいるだろう：
+=begin original
+
The "Tempo" attribute (AKA "Divisions") is an integer that specifies
the number of "ticks" per MIDI quarter note. Ticks is just the
notional timing unit all MIDI events are expressed in terms of.
@@ -855,57 +1221,89 @@
does. Its one parameter is the number of microseconds each quarter
note should get.
+=end original
+
"Tempo"属性（分解能）とは、MIDIにおける四分音符あたりのティックの数を特定する整数のことである。ティックは論理的な時間間隔の単位であり、全てのMIDIイベントはこの値を使って表現されている。ティックを"Tempo"と呼ぶのは本当は間違いなのだ。あなたの曲のスピードを早くしたり遅くしたりする時に変更するのは、Tempoではなくて、ティックと実時間の対応の方である。これはC<set_tempo>によってなされる。C<set_tempo>によって設定されるパラメータは、一つひとつの四分音符が持つべきマイクロ秒の数である。
+=begin original
+
Suppose you wanted a tempo of 120 quarter notes per minute. In terms
of microseconds per quarter note:
+=end original
+
1分あたり四分音符120のテンポにしたいとしてみよう。一個の四分音符あたりの
マイクロ秒だから：
set_tempo 500_000; # 桁区切りのカンマに _ を使える
+=begin original
+
In other words, this says to make each quarter note take up 500,000
microseconds, namely .5 seconds. And there's 120 of those
half-seconds to the minute; so, 120 quarter notes to the minute.
+=end original
+
つまり上の例では、一つひとつの四分音符が500,000マイクロ秒（0.5秒）で
構成される。0.5秒が120個集まると1分になる。だから、120個の四分音符で
1分になるわけだ。
+=begin original
+
If you see a "[quarter note symbol] = 160" in a piece of sheet music,
and you want to figure out what number you need for the C<set_tempo>,
do:
+=end original
+
楽譜に"[四分音符のマーク] = 160"と書かかれてあって、
C<set_tempo>でそれに必要な数を表したいなら：
60_000_000 / 160 ... その結果得るのは： 375_000
+=begin original
+
Therefore, you should call:
+=end original
+
よってこのように呼び出す：
set_tempo 375_000;
+=begin original
+
So in other words, this general formula:
+=end original
+
結局、次のような一般式：
set_tempo int(60_000_000 / $quarter_notes_per_minute);
+=begin original
+
should do you fine.
+=end original
+
を使えばよい。
+=begin original
+
As to the Tempo/Duration parameter, leave it alone and just assume
that 96 ticks-per-quarter-note is a universal constant, and you'll be
happy.
+=end original
+
Tempo/Durationについては、そのままにしておいて、四分音符一個につき
96ティックで常に一定と考えておけば吉。
+=begin original
+
(You may wonder: Why 96? As far as I've worked out, all purmutations
of the normal note lengths (whole, half, quarter, eighth, sixteenth,
and even thirty-second notes) and tripletting, dotting, or
@@ -919,8 +1317,12 @@
mess with the Tempo attribute -- I suggest multiples of 96, e.g., 5 *
96.)
+=end original
+
（あなたは疑問に思うだろう：「なぜ96なの？」。通常の音符の長さ（全音符・二分音符・四分音符・八分音符・十六分音符、さらには三十二分音符さえ）と三連符、付点音符、複付点音符を表現するにあたって、96なら全て生成できる。例えば四分音符がティック96なら複付点三十二分音符21ティックとなる（1.75 * 1/8 * 96）。もし四分音符が48ティックだったらこれは10.5になってしまう。今度は、五連符をつくりたいとする。不運なことに96には因数に5が含まれない。96は因数分解すると3 * (2 ** 5)。つまり3かける2の5乗。本当に五連符が欲しいならTemp属性の変更を許可しなければならない。この場合96の倍数が良いと思う。例えば5 * 96など。）
+=begin original
+
(You may also have read in L<MIDI::Filespec> that C<time_signature>
allows you to define an arbitrary mapping of your concept of quarter
note, to MIDI's concept of quarter note. For your sanity and mine,
@@ -929,6 +1331,8 @@
MIDI quarter note". And this is relevant only if you're calling
C<time_signature> anyway, which is not necessarily a given.)
+=end original
+
[訳注：L<MIDI::Filespec>は事実上存在しないので、上記の段落は訳していない]
=head2 さらなるルーチン
@@ -939,6 +1343,8 @@
=item $opus = $obj->write_score(I<filespec>)
+=begin original
+
Writes the score to the filespec (e.g, "../../samples/funk2.midi", or
a variable containing that value), with the score's Ticks as its tick
parameters (AKA "divisions"). Among other things, this function calls
@@ -947,6 +1353,8 @@
(Also: you can also use a filehandle-reference instead of the
filespec: C<write_score *STDOUT{IO}>.)
+=end original
+
指定したファイル（"../../samples/funk2.midi"や、そういった値の入っている
変数）にスコアを書き出す。この時ティックパラメータ（分解能）としてその
スコアのティックも一緒に書き出される。さらにいうと、この関数は下に挙げた
@@ -958,6 +1366,8 @@
=item $obj = MIDI::Simple->read_score('foo.mid'))
+=begin original
+
In the first case (a procedure call), does C<new_score> to erase and
initialize the object attributes (Score, Octave, etc), then reads from
the file named. The file named has to be a MIDI file with exactly one
@@ -965,37 +1375,63 @@
acts as a constructor method, returning a new object read from the
file.
+=end original
+
一番目のやり方の場合（プロシージャ呼び出し）、オブジェクトの属性（Score、Octave等）を消去・初期化するために、C<score_new>し、それから指定されたファイルから読み込む。指定されたファイルは、確実にイベントで満たされた一つのトラックを持ったMIDIファイルでなければならない。さもなければPerlはdieする。二番目のやり方の場合、C<read_score>はコンストラクタメソッドとして機能し、ファイルから読み込んだ新しいオブジェクトを返す。
+=begin original
+
Score, Ticks, and Time are all affected:
+=end original
+
Score、TicksとTimeは影響を受ける。
+=begin original
+
Score is the event form of all the MIDI events in the MIDI file.
(Note: I<Seriously> deformed MIDI files may confuse the routine that
turns MIDI events into a Score.)
+=end original
+
ScoreはMIDIファイル中にある全MIDIイベントの形をとる（注意：I<著しく>形式の
崩れたMIDIファイルはMIDIイベントをScoreに変換するルーチンを混乱させる）。
+=begin original
+
Ticks is set from the ticks setting (AKA "divisions") of the file.
+=end original
+
Ticksはファイルのティック（分解能）に基づいてセットされる。
+=begin original
+
Time is set to the end time of the latest event in the file.
+=end original
+
Timeはファイルの一番最後のイベントの終了時間がセットされる。
+=begin original
+
(Also: you can also use a filehandle-reference instead of the
filespec: C<read_score *STDIN{IO}>.)
+=end original
+
（また、ファイル指定の代わりにファイルハンドルへの
リファレンスを使うことも出来る。：C<read_score *STDOUT{IO}>。）
+=begin original
+
If ever you have to make a Score out of a single track from a
I<multitrack> file, read the file into an $opus, and then consider
something like:
+=end original
+
I<マルチトラック>ファイルの複数のトラックからScoreをつくらなければならない場合、ファイルを$opusに読み込んでから次のようにする：
new_score;
@@ -1013,36 +1449,56 @@
=item $obj->synch( LIST of coderefs )
+=begin original
+
LIST is a list of coderefs (whether as a series of anonymous subs, or
as a list of items like C<(\&foo, \&bar, \&baz)>, or a mixture of
both) that C<synch> calls in order to add to the given object -- which
in the first form is the package's default object, and which in the
second case is C<$obj>. What C<synch> does is:
+=end original
+
LISTはサブルーチンへのリファレンスのリストだ（無名サブルーチンかC<(\&foo, \&bar, \&baz)>のようなリストか、それらの混合かは問わない）。C<synch>は与えられたオブジェクトに付け加えるためにそれらを呼び出す。与えられるオブジェクトは、一番目のプロシージャ形式の場合はそのパッケージのデフォルトオブジェクトが、そしてメソッドの場合はC<$obj>となる。C<synch>が何をするかというと：
+=begin original
+
* remember the initial value of Time, before calling any of the
routines;
+=end original
+
※ルーチンを呼び出す前に、Timeの最初の値を覚えておく。
+=begin original
+
* for each routine given, reset Time to what it was initially, call
the routine, and then note what the value of Time is, after each call;
+=end original
+
※与えられた全てのルーチン毎に、Timeの値を最初の値へとリセットしておく。
ルーチンを呼び出す。全てのルーチンを呼び出した後に、Tiemの値が何であるかを記録する。
+=begin original
+
* then, after having called all of the routines, set Time to whatever
was the greatest (equals latest) value of Time that resulted from any
of the calls to the routines.
+=end original
+
※そして全てのルーチンを呼び出し終えた後、ルーチンの呼び出して解決されたTimeの最大値（すなわち最後の値）をTimeにセットする。
+=begin original
+
The coderefs are all called with one argument in C<@_> -- the object
they are supposed to affect. All these routines should/must therefore
use method calls instead of procedure calls. Here's an example usage
of synch:
+=end original
+
サブルーチンへのリファレンスは全て、C<@_>の一つの引数（影響を受けるオブジェクト）を伴って呼び出される。それゆえ、これらのルーチンはプロシージャ呼び出しではなく、メソッド呼び出しでなければならない。synchの使用例：
my $measure = 0;
@@ -1070,30 +1526,42 @@
=item $opus = make_opus または $opus = $obj->make_opus
+=begin original
+
Makes an opus (a MIDI::Opus object) out of Score, setting the opus's
tick parameter (AKA "divisions") to $ticks. The opus is,
incidentally, format 0, with one track.
+=end original
+
Scoreからオプス（MIDI::Opusオブジェクト）をつくる。このときオプスの
ティック（分解能）に$ticksをセットする。ちなみにこのオプスは一つの
トラックを持つフォーマット0だ。
=item dump_score または $obj->dump_score
+=begin original
+
Dumps Score's contents, via C<print> (so you can C<select()> an output
handle for it). Currently this is in this somewhat uninspiring format:
+=end original
+
C<print>を通じてScoreの内容をダンプする（C<sekect>を使って出力先の
ハンドルを変更できる）。現在の所、これは次のような退屈な形式になる：
['note', 0, 96, 1, 25, 96],
['note', 96, 96, 1, 29, 96],
+=begin original
+
as it is (currently) just a call to &MIDI::Score::dump_score; but in
the future I may (should?) make it output in C<n>/C<r> notation. In
the meantime I assume you'll use this, if at all, only for debugging
purposes.
+=end original
+
現在のところ、&MIDI::Score::dump_scoreの呼び出しと変わらない。だが将来は
C<n>/C<r>を表すように出力したい（するべきか？）。とりあえずは、
デバッグの目的でのみこれを使うことを想定している。
@@ -1103,10 +1571,14 @@
=head2 関数
+=begin original
+
These are subroutines that aren't methods and don't affect anything
(i.e., don't have "side effects") -- they just take input and/or give
output.
+=end original
+
これらはメソッドでなく、他に影響を与えない（副作用をもたらさない）
サブルーチンだ。つまりインプットを受け取りアウトプットを出すだけだ。
@@ -1114,36 +1586,54 @@
=item interval LISTREF, LIST
+=begin original
+
This takes a reference to a list of integers, and a list of note-pitch
specifications (whether relative or absolute), and returns a list
consisting of the given note specifications transposed by that many
half-steps. E.g.,
+=end original
+
整数のリストへのリファレンスと、音階指定のリストを引数にとる。
そして与えられたノート指定を半音単位でずらしたリストを返す。例えば：
@majors = interval [0,4,7], C, Bflat3;
+=begin original
+
which returns the list C<(C,E,G,Bf3,D4,F4)>.
+=end original
+
これはC<(C,E,G,Bf3,D4,F4)>のリストを返す。
+=begin original
+
Items in LIST which aren't note specifications are passed thru
unaltered.
+=end original
+
ノート指定を含まないLISTの要素は、変更されない。
=item note_map { BLOCK } LIST
+=begin original
+
This is pretty much based on (or at least inspired by) the normal Perl
C<map> function, altho the syntax is a bit more restrictive (i.e.,
C<map> can take the form C<map {BLOCK} LIST> or C<map(EXPR,LIST)> --
the latter won't work with C<note_map>).
+=end original
+
これはPerlのC<map>関数に基づいている（少なくともインスピレーションを
得た）。ただし文法は少しばかり規制が厳しいが（C<map>はC<map {BLOCK} LIST>か
C<map(EXPR,LIST)>の形式をとれるが、C<note_map>は後者のようにはできない）。
+=begin original
+
C<note_map {BLOCK} (LIST)> evaluates the BLOCK for each element of
LIST (locally setting $_ to each element's note-number value) and
returns the list value composed of the results of each such
@@ -1153,61 +1643,92 @@
as an anonymous subroutine) three parameters, which BLOCK can access
in @_ :
+=end original
+
C<note_map {BLOCK} (LIST)>は、LISTの要素に対して（各要素はローカル化された
$_にセットされる）ブロック内を評価して、その結果をまとめたリスト値を返す。
リストコンテキストでブロックを評価すること。LISTの各要素は戻り値において0,1,それ以上の要素を生成するかもしれない。さらに、$_にセットされる以外に、C<note_map>はブロック（無名サブルーチンとしてみる）に三つのパラメータを渡す。これは@_を使ってブロック内からアクセスできる。
+=begin original
+
$_[0] : Same as $_. I.e., The current note-specification,
as a note number.
This is the result of having fed the original note spec
(which you can see in $_[2]) to is_note_spec.
+=end original
+
+ $_[0] : $_と同じ。つまり現在のノート指定。ノートナンバーとして表される。
+ 元のノート指定（$_[2]参照）をis_note_specに与えた結果である。
+
+=begin original
+
$_[1] : The absoluteness flag for this note, from the
above-mentioned call to is_note_spec.
0 = it was relative (like 'C')
1 = it was absolute (whether as 'C4' or 'n41' or '41')
- $_[2] : the actual note specification from LIST, if you want
- to access it for any reason.
-
-
- $_[0] : $_と同じ。つまり現在のノート指定。ノートナンバーとして表される。
- 元のノート指定（$_[2]参照）をis_note_specに与えた結果である。
+=end original
$_[1] : このノートが絶対指定かどうかのフラグ。is_note_specから渡される。
0 = 相対指定（例えば'C'）
1 = 絶対指定（'C4'とか'n41'とか'41')
+=begin original
+
+ $_[2] : the actual note specification from LIST, if you want
+ to access it for any reason.
+
+=end original
+
$_[2] : 何らかの理由でアクセスする場合の、LISTから得る実際のノート指定。
+=begin original
+
Incidentally, any items in LIST that aren't a note specification are
passed thru unchanged -- BLOCK isn't called on it.
+=end original
+
ちなみにLISTの中のノート指定でないどの要素も変更されずに素通りする。
BLOCKは呼ばれない。
+=begin original
+
So, in other words, what C<note_map> does, for each item in LIST, is:
+=end original
+
つまり、C<note_map>がすることは、LISTの各要素に対して：
+=begin original
+
* It calls C<is_note_spec> on it to test whether it's a note
specification at all. If it isn't, just passes it thru. If it is,
then C<note_map> stores the note number and the absoluteness flag that
C<is_note_spec> returned, and...
+=end original
+
※それがノート指定かどうかをテストするためにC<is_note_spec>を呼び出す。
違っていたら、無視する。ノート指定であったら次にC<note_map>は、その
ノートナンバーと、C<is_note_spec>が返す絶対指定フラグを保持する。それから…
+=begin original
+
* It calls BLOCK, providing the note number in $_ and $_[0], the
absoluteness flag in $_[1], and the original note specification in
$_[2]. Stores the return value of calling BLOCK (in a list context of
course) -- this should be a list of note numbers.
+=end original
+
ブロックを呼び出す。このとき$_と$_[0]にはノートナンバーを、$_[1]には絶対指定フラグを、$_[2]には元のノート指定を与える。ブロック呼び出しの戻りを保持する（もちろんリストコンテキストで）。この戻り値はノートナンバーのリストであるべきだ。
+=begin original
+
* For each element of the return value (which is actually free to be
an empty list), converts it from a note number to whatever B<kind> of
specification the original note value was. So, for each element, if
@@ -1216,26 +1737,44 @@
was absolute, C<note_map> will try to restore it to the
correspondingly formatted absolute specification type.
+=end original
+
※戻り値の各要素に対して（空リストでもよい）、ノートナンバーから元のノートの値による何らかの指定へと変換する。だから各要素に対して、元の指定が相対指定の場合、C<note_map>は戻り値を相対ノートナンバーとして解釈し、戻り値に対してC<number_to_relative>を呼び出す。絶対指定ならC<note_map>は対応するようにフフォーマットされた絶対指定型としてそれを保持しようとする。
+=begin original
+
An example is, I hope, helpful:
+=end original
+
この例が役に立つとよいのだが：
+=begin original
+
This:
+=end original
+
これは：
note_map { $_ - 3, $_ + 2 } qw(Cs3 n42 50 Bf)
+=begin original
+
returns this:
+=end original
+
次の値を返す：
('Bf2', 'Ef3', 'n39', 'n44', '47', '52', 'G', 'C_u1')
+=begin original
+
Or, to line things up:
+=end original
+
つまりこういうふうに：
Cs3 n42 50 Bf
@@ -1243,58 +1782,86 @@
/-----\ /-----\ /---\ /----\
Bf2 Ef3 n39 n44 47 52 G C_u1
+=begin original
+
Now, of course, this is the same as what this:
+=end original
+
もちろん、これは次の戻り値と同じだ：
interval [-3, 2], qw(Cs3 n42 50 Bf)
+=begin original
+
returns. This is fitting, as C<interval>, internally, is basically a
simplified version of C<note_map>. But C<interval> only lets you do
unconditional transposition, whereas C<note_map> lets you do anything
at all. For example:
+=end original
+
これが一致するのは、基本的にC<interval>は内部的にはC<note_map>を簡略したものだからだ。だが、C<interval>は無条件に音階を変更する。これに対してC<note_map>は任意のことができる。例えば：
@note_specs = note_map { $funky_lookup_table{$_} }
C, Gf;
+=begin original
+
or
+=end original
+
や、
@note_specs = note_map { $_ + int(rand(2)) }
@stuff;
+=begin original
+
C<note_map>, like C<map>, can seem confusing to beginning programmers
(and many intermediate ones, too), but it is quite powerful.
+=end original
+
C<map>同様、C<note_map>は初心者プログラマを混乱させるかもしれない
（そして中級プログラマもまた）。しかしこの関数は大変強力だ。
=item number_to_absolute NUMBER
+=begin original
+
This returns the absolute note specification (in the form "C5") that
the MIDI note number in NUMBER represents.
+=end original
+
この関数はMIDIノートナンバー（NUMBER）が表す絶対ノート指定を返す
（"C5"のような形式）。
+=begin original
+
This is like looking up the note number in %MIDI::number2note -- not
exactly the same, but effectively the same. See the source for more
details.
+=end original
+
これは%MIDI::number2noteからノートナンバーを探すのに似ている。
全く同じとはいわないが、効果は同じだ。詳細についてはソースを見て欲しい。
=item the function number_to_relative NUMBER
+=begin original
+
This returns the relative note specification that NUMBER represents.
The idea of a numerical representation for C<relative> note
specifications was necessitated by C<interval> and C<note_map> --
since without this, you couldn't meaningfully say, for example,
interval [0,2] 'F'. This should illustrate the concept:
+=end original
+
この関数はNUMBERが表す相対ノート指定を返す。c<相対的な>ノート指定を数値で表現するという考えは、C<interval>とC<note_map>によって必要とされる。もしも相対指定が無かったら例えば、interval [0,2] 'F' という表現は無意味になるだろう。これは次のような概念で表される。
number_to_relative(-10) => "D_d1"
@@ -1307,6 +1874,8 @@
=item is_note_spec STRING
+=begin original
+
If STRING is a note specification, C<is_note_spec(STRING)> returns a
list of two elements: first, a flag of whether the note specification
is absolute (flag value 1) or relative (flag value 0); and second, a
@@ -1314,20 +1883,30 @@
not a note specification, C<is_note_spec(STRING)> returns an empty
list (which in a boolean context is FALSE).
+=end original
+
STRINGがノート指定なら、C<is_note_spec(STRING)>は二つの要素からなる
リストを返す。一番目の要素はそのノート指定が絶対指定（値は1）か相対指定
（値は0）かを表すフラグだ。二番目の要素はそのノート指定に対応する
ノートナンバーだ。もしSTRINGがノート指定でないなら、
C<is_note_spec(STRING)>は空リスト（ブールコンテキストでは偽になる）を返す。
+=begin original
+
Implementationally, C<is_note_spec> just uses C<is_absolute_note_spec>
and C<is_relative_note_spec>.
+=end original
+
実装上は、C<is_note_spec>はC<is_absolute_note_spec>と
C<is_relative_note_spec>を利用しているだけだ。
+=begin original
+
Example usage:
+=end original
+
使用例：
@note_details = is_note_spec($thing);
@@ -1340,30 +1919,46 @@
=item is_relative_note_spec STRING
+=begin original
+
If STRING is an relative note specification, returns the note number
for that specification as a one-element list (which in a boolean
context is TRUE). Returns empty-list (which in a boolean context is
FALSE) if STRING is NOT a relative note specification.
+=end original
+
STRINGが相対ノート指定なら、一つの要素からなるリスト（ブールコンテキスト
では真になる）としてその指定に対応するノートナンバーを返す。もしSTRINGが
相対ノート指定でB<ない>なら、空リストを返す（ブールコンテキストでは
偽になる）。
+=begin original
+
To just get the boolean value:
+=end original
+
ブール値を得るだけなら：
print "Snorf!\n" unless is_relative_note_spec($note);
+=begin original
+
But to actually get the note value:
+=end original
+
だが、ノートの値を実際に得るためには：
($note_number) = is_relative_note_spec($note);
+=begin original
+
Or consider this:
+=end original
+
あるいは次のように：
@is_rel = is_relative_note_spec($note);
@@ -1373,6 +1968,8 @@
print "Snorf!\n";
}
+=begin original
+
(Author's note, two years later: all this business of returning lists
of various sizes, with this and other functions in here, is basically
a workaround for the fact that there's not really any such thing as a
@@ -1382,6 +1979,8 @@
input is a number, and undef/emptylist (C<return;>) if not -- then,
the user could test:
+=end original
+
（二年後の作者からの注意：ここにある関数がもたらす、様々なサイズの戻り値リストは基本的に次の事実を避けるためのものである。すなわち、Perlには本当の意味でブールコンテキストのようなものは存在しないということだ。少なくとも、ユーザー定義の関数が知ることは出来ない。私は今、単一のスカラー値を返すだけでブール判定が出来るようにするべきだとは思っている。もし数値がインプットされたら数字を（0も含む！）、そうでなかったらundefか空リストをC<return>する。それからユーザーがテストすることができる）
# 仮定 --
@@ -1392,11 +1991,15 @@
print "Hey, that's no note!\n";
}
+=begin original
+
However, I don't anticipate users actually using these messy functions
often at all -- I basically wrote these for internal use by
MIDI::Simple, then I documented them on the off chance they I<might>
be of use to anyone else.)
+=end original
+
しかし、私はユーザーがこのような混乱した関数を実際に使うとは思わない。
私はこれらの関数を基本的にMIDI::Simpleが内部的に使うために書いた。
とはいえ、ひょっとしたら誰か他の人にこれらの関数が使われる
@@ -1404,20 +2007,30 @@
=item is_absolute_note_spec STRING
+=begin original
+
Just like C<is_relative_note_spec>, but for absolute note
specifications instead of relative ones.
+=end original
+
相対指定の代わりに絶対ノート指定に対応している以外、
C<is_relative_note_spec>と同じだ。
=item Self() または $obj->Self();
+=begin original
+
Presumably the second syntax is useless -- it just returns $obj. But
the first syntax returns the current package's default object.
+=end original
+
恐らく二番目の方法は無意味だ。なぜなら$objを返すだけだから。だが最初の
方法は現在のパッケージでデフォルト使用されるオブジェクトを返す。
+=begin original
+
Suppose you write a routine, C<funkify>, that does something-or-other
to a given MIDI::Simple object. You could write it so that acts on
the current package's default object, which is fine -- but, among
@@ -1427,13 +2040,19 @@
argument to it is the object to act on. If the MIDI::Simple object
you want it to act on is it C<$sonata>, you just say
+=end original
+
あなたがC<funkify>というルーチンを書いたとしよう。この関数は与えられたMIDI::Simpleのオブジェクトに対し何かを行う。現在のパッケージのデフォルトオブジェクトに対し作用するようだろう。だが注意すべきことに、これはC<synch>からC<funkify>を呼び出すことができないことを意味する。なぜならこのようなルーチンはメソッド呼び出しでのみ使うべきだからだ。だから代わりに、最初の引数が作用されるオブジェクトになるように書くことだ。作用させたいMIDI::SimpleオブジェクトがC<$sonata>なら、このようにする：
funkify($sonata)
+=begin original
+
However, if you want it to act on the current package's default
MIDI::Simple object, what to say? Simply,
+=end original
+
だが、現在のパッケージのデフォルトのMIDI::Simpleオブジェクトに対し作用させたいのなら、どうするか？単純にこうする。
$package_opus = Self;
Index: docs/modules/MIDI-Perl-0.8/MIDI/Track.pod
diff -u docs/modules/MIDI-Perl-0.8/MIDI/Track.pod:1.4 docs/modules/MIDI-Perl-0.8/MIDI/Track.pod:1.5
--- docs/modules/MIDI-Perl-0.8/MIDI/Track.pod:1.4 Thu Jan 27 22:14:57 2011
+++ docs/modules/MIDI-Perl-0.8/MIDI/Track.pod Sat May 4 05:17:24 2013
@@ -1,10 +1,14 @@
=encoding euc-jp
-=head1 名前
+=head1 NAME
+
+=begin original
MIDI::Track -- functions and methods for MIDI tracks
+=end original
+
MIDI::Track -- MIDIトラックのための関数とメソッド
=head1 SYNOPSIS
@@ -23,24 +27,34 @@
=head1 説明
+=begin original
+
MIDI::Track provides a constructor and methods for objects
representing a MIDI track. It is part of the MIDI suite.
+=end original
+
MIDI::Trackは、MIDIトラックを表現するオブジェクトに対する
コンストラクタとメソッドを提供する。
+=begin original
+
MIDI tracks have, currently, three attributes: a type, events, and
data. Almost all tracks you'll ever deal with are of type "MTrk", and
so this is the type by default. Events are what make up an MTrk
track. If a track is not of type MTrk, or is an unparsed MTrk, then
it has (or better have!) data.
+=end original
+
現在MIDIトラックはタイプ、イベント、データという三つの属性を持っている。
あなたが扱うほとんど全てのトラックは"MTrk"タイプのトラックだ。
そしてこれがデフォルトのタイプである。イベントは、MTrkトラックを構成している。
もしあるトラックがMTrkタイプでないか、あるいはMTrkとして解析されない場合、
それはデータということだ。
+=begin original
+
When an MTrk track is encoded, if there is data defined for it, that's
what's encoded (and "encoding data" means just passing it thru
untouched). Note that this happens even if the data defined is ""
@@ -48,6 +62,8 @@
data defined for the MTrk track (as is the general case), then the
track's events are encoded, via a call to C<MIDI::Event::encode>.
+=end original
+
MTrkトラックがエンコードされる時、そこに定義済みのデータがあるなら、それが
エンコードされる（「データをエンコードする」とは、データを未接触のものへと
送るこをと意味する）。データが""で定義されていてもエンコードされることに注意
@@ -55,22 +71,34 @@
MTrkトラックにない場合（これはよくあることだ）、トラックが有するイベントが
エンコードされる。これはC<MIDI::Event::encode>の呼び出しを通じて行われる。
+=begin original
+
(If neither events not data are defined, it acts as a zero-length
track.)
+=end original
+
（もしどのイベントも定義されていないなら、0サイズのトラックとして振舞う。）
+=begin original
+
If a non-MTrk track is encoded, its data is encoded. If there's no
data for it, it acts as a zero-length track.
+=end original
+
非MTrkタイプのトラックがエンコードされるなら、トラックにあるデータはエンコード
される。トラックにデータが無い場合は、0長サイズのトラックとして振舞う。
+=begin original
+
In other words, 1) events are meaningful only in an MTrk track, 2) you
probably don't want both data and events defined, and 3) 99.999% of
the time, just worry about events in MTrk tracks, because that's all
you ever want to deal with anyway.
+=end original
+
つまり、(1)イベントはMTrkタイプのトラック内部でのみ意味を持つ。
(2)定義されたデータとイベントの両方を必要とはしないだろう。
(3)あなたの時間の99.999%はMTrkトラック内のイベントに気をまわすことになる。
@@ -79,14 +107,20 @@
=head1 コンストラクタとメソッド
+=begin original
+
MIDI::Track provides...
+=end original
+
MIDI::Trackは以下のものを提供する。
=over
=item MIDI::Track->new({ ...options... })
+=begin original
+
This returns a new track object. By default, the track is of type
MTrk, which is probably what you want. The options, which are
optional, is an anonymous hash. There are four recognized options:
@@ -97,6 +131,8 @@
L<perllol> for the skinny on LoLs); and C<events_r>, which is an exact
synonym of C<events>.
+=end original
+
新しいトラックオブジェクトを返す。デフォルトでMTrkタイプになる。これはたぶん
あなたが望むものだろう。任意のオプションとして無名ハッシュを渡せる。
モジュールは四つのオプションを認識する：C<data>は新規のトラックデータに
@@ -107,10 +143,14 @@
=item $new_track = $track->copy
+=begin original
+
This duplicates the contents of the given track, and returns
the duplicate. If you are unclear on why you may need this function,
consider:
+=end original
+
このメソッドはトラックの内容を複製し、オブジェクトを返す。
もしこの機能がなぜ必要なのかよくわからない場合は、次の例を考えてみよう。
@@ -131,6 +171,8 @@
$samba->write_to_file('samba2.mid');
exit;
+=begin original
+
So you have your routines funk_it_up and turn_it_out, and they each
modify the track they're applied to in some way. But the problem is that
the above code probably does not do what you want -- because the last
@@ -140,6 +182,8 @@
the above code. That's where you need to do copy the object. Change
the above code to read:
+=end original
+
つまり、あなたはfunk_it_upとturn_it_outというルーチンをつくり、何らかの方法で
それぞれのトラックを修正することになる。しかし問題は、上記のコードではあなたの
望むことをやってくれないだろうということだ。$funkの最後尾の
@@ -150,59 +194,85 @@
push(@{ $samba->tracks_r }, $bass_track->copy );
+=begin original
+
and what you want to happen, will.
+=end original
+
これであなたの望んだとおりになるだろう。
+=begin original
+
Incidentally, this potential need to copy also occurs with opuses (and
in fact any reference-based data structure, altho opuses and tracks
should cover almost all cases with MIDI stuff), which is why there's
$opus->copy, for copying entire opuses.
+=end original
+
ついでにいうと、このようなコピーの必要性が、オプスにおいても生じる（そして
実際、リファレンスに基づくどんなデータ構造でも生じる。オプスとトラックは
MIDI要素のほとんど全てのケースをカバーしなければならないにもかかわらず）。
これがオプスを丸ごとコピーするために$opus->copyが存在する理由である。
+=begin original
+
(If you happen to need to copy a single event, it's just $new = [@$old] ;
and if you happen to need to copy an event structure (LoL) outside of a
track for some reason, use MIDI::Event::copy_structure.)
+=end original
+
（単一のイベントをコピーする必要があるなら、単に$new = [@$old]でよい。
何らかの理由で一つのトラックを越えてイベント構造（リストのリスト）を
コピーする必要が出たらMIDI::Event::copy_structureを使うこと。）
=item $track->events( @events )
+=begin original
+
Returns the list of events in the track, possibly after having set it
to @events, if specified and not empty. (If you happen to want to set
the list of events to an empty list, for whatever reason, you have to use
"$track->events_r([])".)
+=end original
+
トラックのイベントリストを返す。あるいは、@eventsを指定し、それが空でなければ
その値がセットされる（理由は何であれ、リストイベントに空リストをセットしたい
ならば、"$track->events_r([])"を使わなければならない）。
+=begin original
+
In other words: $track->events(@events) is how to set the list of events
(assuming @events is not empty), and @events = $track->events is how to
read the list of events.
+=end original
+
つまり、（@eventsは空でないとして）$track->events(@events)はイベントリストの
セット方法で、@events = $track->eventsはイベントリストの取得方法である。
=item $track->events_r( $event_r )
+=begin original
+
Returns a reference to the list of events in the track, possibly after
having set it to $events_r, if specified. Actually, "$events_r" can be
any listref to a LoL, whether it comes from a scalar as in
C<$some_events_r>, or from something like C<[@events]>, or just plain
old C<\@events>
+=end original
+
トラックのイベントリストへのリファレンスを返す。あるいは、$events_rを指定すると
リファレンスがセットされる。実際のところ、"$events_r"はリストのリスト(LoL)への
リファレンスでありさえすればよいので、C<$some_events_r>からだろうと、
C<[@events]>からだろうと、古き簡素なC<\@events>からだろうと構わない。
+=begin original
+
Originally $track->events was the only way to deal with events, but I
added $track->events_r to make possible 1) setting the list of events
to (), for whatever that's worth, and 2) so you can directly
@@ -210,6 +280,8 @@
events (which might be tens of thousands of elements long) back
and forth. This way, you can say:
+=end original
+
もともと$track->eventsがイベントを扱う唯一の方法だった。だが私が
$track->events_rを付け加えたのは、(1)イベントリストを何らかの有意義な理由で
丸括弧()にセットできるようにするため。(2)（10000要素の長さにもなるような）
@@ -219,18 +291,26 @@
$events_r = $track->events_r();
@some_stuff = splice(@$events_r, 4, 6);
+=begin original
+
But if you don't know how to deal with listrefs outside of LoLs,
that's OK, just use $track->events.
+=end original
+
だが配列の配列を越えてリストリファレンスの扱い方を知らなくても、大丈夫。
$track->eventsを使えばよい。
=item $track->type( 'MFoo' )
+=begin original
+
Returns the type of $track, after having set it to 'MFoo', if provided.
You probably won't ever need to use this method, other than in
a context like:
+=end original
+
$trackのタイプを返す。'MFoo'を与えれば、それがセットされる。たぶん次のような
文脈以外では、このメソッドを使う必要が生じることはないだろう：
@@ -238,18 +318,26 @@
give_up_the_funk($track);
} # それ以外なら処理を続けよう！
+=begin original
+
Track types must be 4 bytes long; see L<MIDI::Filespec> for details.
+=end original
+
トラックタイプは4バイト長でなければならない。
詳細はL<MIDI::Filespec>を参照のこと。
=item $track->data( $kooky_binary_data )
+=begin original
+
Returns the data from $track, after having set it to
$kooky_binary_data, if provided -- even if it's zero-length! You
probably won't ever need to use this method. For your information,
$track->data(undef) is how to undefine the data for a track.
+=end original
+
$trackからデータを返す。$kooky_binary_dataを与えれば、それがセットされる。
これは0サイズのデータでもよい！たぶんこのメソッドを使う必要が生じることは
ないだろう。参考までにいうと、$track->data(undef)は、
@@ -257,23 +345,33 @@
=item $track->new_event('event', ...parameters... )
+=begin original
+
This adds the event ('event', ...parameters...) to the end of the
event list for $track. It's just sugar for:
+=end original
+
$trackのイベントリストの最後にイベント('event', ...parameters...)を
付け加える。これは次のコードの構文糖に他ならない：
push( @{$this_track->events_r}, [ 'event', ...params... ] )
+=begin original
+
If you want anything other than the equivalent of that, like some
kinda splice(), then do it yourself with $track->events_r or
$track->events.
+=end original
+
もしもこれ以上のこと、例えばsplice()のようなことをしたいなら、
$track->events_rや$track->eventsを使って自分自身でやること。
=item $track->dump({ ...options... })
+=begin original
+
This dumps the track's contents for your inspection. The dump format
is code that looks like Perlcode you'd use to recreate that track.
This routine outputs with just C<print>, so you can use C<select> to
@@ -283,6 +381,8 @@
track.
Read the source if you really need to know how this works.
+=end original
+
このメソッドは、あなたが内容を確かめられるようにトラックの内容を
ダンプする。ダンプ形式はPerlのコードようなものだ。このコードを使えば
トラックを復元することができる。