================================================================ dna2abc Commands ================================================================ dna2abc creates commands for manipulating two types of objects: scanners, which read DNA sequences, and voices, which output ABC music. You can create voices and scanners with the graphical user interface, but the scripts that you attach to a scanner's rules will most likely be commands to manipulate voices, so you need to know at least the voice commands before using this program. You create and manipulate objects with the "voice" and "scanner" commands. Objects store their private attributes in named slots, accessed with the slot method. ====== Voices ====== To create a new voice with the name V: % voice V new V To see the default values for the slots use the "values" method: % voice V values voice V slot channel = 1 voice V slot fileID = voice V slot filename = out.abc voice V slot index = 1 voice V slot instrument = 0 voice V slot key = C voice V slot meter = 4/4 voice V slot note = C voice V slot notecount = 0 voice V slot notelength = 1/8 voice V slot notelist = C, D, E, F, G, A, B, C D E F G A B c d e f g a b c' d' e' f' g' a' b' voice V slot oscdir = 1 voice V slot sustain = 1 voice V slot sustainlist = /16 /8 /4 /2 1 2 4 voice V slot tempo = 1/4 = 120 voice V slot title = dna2abc To get a slot value: % voice V slot note C To set a slot value: % voice V slot note G G Begin by creating one or more voices, and setting their initial slot values. The meanings of the slots: channel The MIDI channel (if a MIDI file is generated) fileID The open file ID, don't set this directly filename The name of the .abc file to generate. Set this before playing any notes. If the option to generate MIDI files is enabled, a file with this name but ending in .midi will be generated. index tune index, don't touch instrument General MIDI number of the instrument (much easier to set from the GUI) key The key, in ABC's key notation meter The time signature note The current note notecount The number of notes played notelength ABC's L: specification, the length of a normal note notelist List of allowed notes oscdir Direction indicator for oscillator, don't touch sustain The current sustain sustainlist List of allowed sustains tempo ABC's Q: specification (song tempo) title ABC's T: specification You can change the key, meter, notelength, and tempo in the middle of a tune and it will be output correctly. You can change the note and sustain directly, or use the incr, cycle, osc and random methods (see below). The notelist and sustainlist can be changed at any time and will take effect the next time incr, cycle, osc, or random is used. To play a note (cause a note to be written to the output file): % voice V play This command: % voice V rest "plays" a rest, it outputs a rest at the current sustain. There are four methods to manipulate the note or sustain using the notelist or sustainlist, respectively. To move to the next highest note: % voice V incr note To move to the next lowest: % voice V incr note -1 The last argument can be any integer value, it's added to the index of the current note in the notelist. If the end or beginning of the list is reached, the note stays pegged at that end. To do the same with the sustain and the sustainlist: % voice V incr sustain The "cycle" method is similar, except that the list is treated as circular. The "osc" method oscillates between the two ends of the list, with the slot oscdir keeping track of which direction we're headed in. The "random" method selects a random item from the list. All of these methods just change the current note or sustain, they don't output any notes. To play 100 notes up and down the scale: voice V new for {set i 0} {$i < 100} {incr i} { voice V osc note voice V play } voice V close The "close" method closes the output file and removes the voice from memory (it may also generate the MIDI file, if that option is enabled). In the GUI, voices are automatically closed after the scanners are run. ======== Scanners ======== To create a scanner: % scanner S new S To see the default values: % scanner S values scanner S slot buffer = NNN scanner S slot bufferA = scanner S slot bufferB = scanner S slot bufferC = scanner S slot bufferD = scanner S slot epilogue = scanner S slot fileID = scanner S slot filename = in.dna scanner S slot frame = 3 scanner S slot index = 0 scanner S slot length = 200 scanner S slot n = 0 scanner S slot prologue = scanner S slot rules = scanner S slot skip = 0 scanner S slot step = 1 Scanners read an input DNA file consisting of DNA bases listed in ASCII (lines beginning with '>' are comments) and step through them "step" bases at a time, matching a buffer of "frame" bases against a set of regular expressions. Those expressions that match the value of the buffer fire rules (see below) that normally would manipulate voices (but can be any Tcl code). The meaning of the slots are: buffer Current sequence being matched, don't touch bufferA..D The four test sequences used by the GUI rule editor. These values have no effect on a scanner's operation. epilogue script executed at end of scanner run, just before closing input file fileID Open file ID, don't touch filename Name of file to read from frame Length of match frame. Buffer is initialized to this many Ns when this is set. index Current index into the four test sequences (don't touch; has no effect when scanner is run) length Number of steps to take n Current step number prologue script executed at start of scanner run, just after opening input file rules List of rules (see below) skip Number of bases to skip at start step Number of bases to comsume each step After a scanner has been created and its rules and other slots set, it can be run from start to finish with: % scanner S run So, a typical non-interactive input file would: 1) create one or more voices and set their slots 2) create one or more scanners and set their slots, especially the rules, 3) Call the run method on each scanner 4) Call the close method on all the scanners and voices Most users will want to use the GUI instead, which has menu items to run all the scanners or just the selected scanner. ===== Rules ===== The heart of this system is the rule specification. Each rule list is an even-length Tcl list consisting of ... etc.. Each is a Tcl regular expression (use more recent versions of Tcl, like 8.3, to get more powerful regular expression syntax). If the expression matches the buffer, the following is executed. Each step, all of the rules are matched in order, so multiple rules may fire in one step. To prevent later rules from firing, end a body with "break". Here's a complete example that reads and writes using the default file names (in.dna and out.abc). It steps through the sequence one base at a time. A causes the note to rise by 1, C by 2, G causes it to fall by 1 and T by 2. voice V new scanner S new scanner S slot frame 1 scanner S slot step 1 scanner S slot length 200 scanner S slot rules { A { voice V osc note 1 voice V play } C { voice V osc note 2 voice V play } G { voice V osc note -1 voice V play } T { voice V osc note -2 voice V play } } scanner S run voice V close