scramble -r [-s regexp] [inputfile]
scramble -t [-m] [-s regexp] [inputfile]
Two modes of operation are supported according to whether the -r (record) or -t (token) option is invoked. When the -r mode is selected, the order of data records is randomized. In this mode, each output record is identical to some input record; only the order of the output records is changed. When the -t mode is selected, the order of data tokens within each record is randomized. In this mode, the order of the input records is preserved -- however, data tokens between concurrent spines are randomly swapped. The -t mode will also cause sub-tokens within multiple stops to be rearranged within the data token. However, if the -m option is concurrently invoked, then sub-tokens within multiple-stops will be randomly redistributed across all tokens in the record. The -r and -t options cannot be invoked concurrently.
In both modes of operation, Humdrum comments and interpretations remain unaffected. Comments and interpretations are output intact, and in precisely the same location (line number) as in the input. Only data records are affected by scramble.
Each time scramble is invoked, a different random ordering is generated.
Note that when using the -r mode, the scrambling process may produce an output that is no longer syntactically correct Humdrum. With the -r mode, scramble is guaranteed to produce Humdrum output only if (1) the input file is bona fide Humdrum, and (2) the number of spines in the input does not vary.
With the -t mode, scramble will always produce output conforming to the Humdrum syntax, however it can produce uninterpretable output if concurrent spines do not contain the same type of data (that is, they have different exclusive interpretations).
Notice also that reordering data records may destroy data-token links
such as
**kern
ties.
A skip option (-s) permits users to anchor certain data records so that they are not either repositioned, or their data tokens re-ordered.
Options are specified in the command line. One of either the record mode (-r) or token mode (-t) must be invoked.
-h displays a help screen summarizing the command syntax -m redistribute subtokens in multiple stops across all tokens in the record; used in conjunction with -t only -r scramble the order of data records; don't scramble data tokens -s regexp skip; don't scramble records matching regexp; leave matching records intact, and in the same position -t scramble data tokens within each record; don't scramble record order
!! A global comment
!! Another comment
**inter **inter
*abcd *efgh
=1 =1
1a 1b a
!local !local
2 b1 b2 b3
3 c
=2 =2
!! A later comment.
4a 4b d
=3 =3
5 e
*- *-
When processed using the
record mode,
the command:
scramble -r -s = inputfile
might produce the following output:
In this example, notice that the Humdrum comments and interpretations
remain in their original location; only the data records have
been reordered.
In addition, data records containing an equals-sign have been
frozen in their original locations.
!! A global comment !! Another comment **inter **inter *abcd *efgh =1 =1 3 c !local !local 5 e 1a 1b a =2 =2 !! A later comment. 4a 4b d =3 =3 2 b1 b2 b3 *- *-
When processed using the token mode, the command:
scramble -t -m -s = inputfile
might produce the following output:
Notice that a complete scrambling of data tokens within a Humdrum file
cannot be achieved merely by invoking one
scramble
mode followed by the other mode.
In order to completely scramble a Humdrum file the user must
extract and scramble the record order for each spine independently,
and then reassemble the scrambled spines into a new file using the
assemble
command.
!! A global comment !! Another comment **inter **inter *abcd *efgh =1 =1 1b a 1a !local !local b2 b3 2 b1 c 3 =2 =2 !! A later comment. 4a 4b d =3 =3 5 e *- *-
Note also that where the number of spines changes over the course of the input file, valid Humdrum output is unlikely. Outputs consistent with the Humdrum syntax can be ensured by using the fields -i command to chronicle changing numbers of spines in a file, followed by the yank command to segregate data blocks containing the same number of spines. Each such bock can be scrambled independently and then the blocks reconnected using the UNIX cat command. Unnecessary (duplicate) interpretations can be eliminated using rid -u.
assemble (4),
extract (4),
fields (4),
humdrum (4)
Note that the
scramble
command cannot be used in pipes.
**kern
"ties."
Use of the -t mode,
can produce uninterpretable output when concurrent spines do not
contain the same interpretations.