Text File Interface
Prev | Chapter 3. Usage | Next

## Text File Interface

You may also create a text file where each line of the file executes one of the commands listed in Interface 2. A simple example file is given below:

Example 3.7. FOMUS Text Input File

    init :output (:lilypond :view t)
    (init
     :filename "outfile"
     :quality 2)

    ;; remark
    part 1 :name "Piano" :instr :piano

    note 1 :off 0 :dur 1 :note 60
    note 1 :off 1 :dur 1 :note 62 \
         :marks (:accent) ; remark
    (note 1
          :off 2
          :dur 1
          :note 64
          :marks (:marcato (:textnote "Text")))

    off +2
    note 1 :off 2 :dur 1/2 :note c4 ; actual offset is 4
    off -1
    note 1 :off 10 :dur 1/2 :note c4 ; actual offset is 9
    off

    note 1 :off 20 :dur 2 :notes (c4 e4 g4 c5)

Each element is read using the Lisp `READ` command (nothing is evaluated), with the exception of expressions that begin with `MAKE-`. These are evaluated to avoid having to specify FOMUS classes and/or structures with `#S` or `#Z` syntax (the Z reader macro is defined by FOMUS). `INIT` lines specify values for FOMUS settings and can contain multiple keyword/arguments on a line. As many `INIT` lines as needed may appear. The `\` character may be used at the end of a line to concatenate it with the following line. Also, as shown in the example above, any "entry" may be surrounded by a set of parenthesis to indicate that all elements inside them are read/parsed together (like an ordinary Lisp expression)--this can also be used to spread entries across several lines.

A few extra things are possible with input files to facilitate editing. Any section of the file may contain an `OFF` tag optionally followed by a number. This tag shifts the offsets of everything that follows by the specified amount. An `OFF` tag with no number resets the offset shift to 0. Also, a `:NOTES` keyword is available for specifying chords. A chord is then specified as a list of notes as shown above. When FOMUS reads this it creates a separate note object for each note in the list.

To process this file, use the `FOMUS` command as follows:

`(FOMUS `filename` &key `value` ...)`

Example 3.8. FOMUS Usage 7

    (fomus "/directory/file.fms")

Example 3.9. FOMUS Usage 8

    (fomus "/directory/file.fms" :output :cmn)

Keyword/argument pairs passed to this function override the settings stored in the input file.

The `FOMUS-FILE` function may be used to parse an input file and return the objects specified in that file without processing them:

`(FOMUS-FILE `filename` &key `value` ...)`

Four return values are returned: a list of `PART` objects, a sorted list of `NOTE`, `REST` and `MARK` objects, a list of `TIMESIG` objects (and `KEYSIG` objects when implemented), and a list of keyword/argument pairs representing the keywords and values found in the `INIT` lines. The following example show how you can edit and resave data using these files:

Example 3.10. FOMUS Usage 9

    (multiple-value-bind (parts events globals args)
        (fomus-file "/directory/myfomusfile.fms")
      ;; user processing...
      (apply #'fomus "/directory/myfomusfile.fms"
    	 :global globals :parts parts :events events
    	 args))

Prev | Up | Next
Interface 2 | Home | Common Music Interface