./../../src/section.lsp

## bar-holder/section [ Classes ]

[ Top ] [ bar-holder ] [ Classes ]

NAME

     section

     File:             section.lsp

     Class Hierarchy:  named-object -> linked-named-object -> bar-holder
                       -> section

     Version:          1.0.2

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of section class which is simply a bar
                       holder and recursive-assoc-list that contains (possibly
                       subsections which contain) player-sections.

     Author:           Michael Edwards: m@michael-edwards.org

     Creation date:    23rd March 2002

     $$ Last modified: 15:24:14 Fri Apr 19 2013 BST

     SVN ID: $Id: section.lsp 3674 2013-06-10 11:07:52Z medward2 $

## section/get-all-players [ Methods ]

[ Top ] [ section ] [ Methods ]

DESCRIPTION

     Return a list of the IDs from all players in a section object. NB: When
     retrieving from a section within a slippery-chicken object, all players in
     the ensemble will be returned, as the slippery-chicken object will generate
     rest bars for players even when they're not active in a given section.

ARGUMENTS

     - A section object.

RETURN VALUE

     - A list of player IDs (symbols).

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((cl (b-flat-clarinet :midi-channel 1))
                         (hn (french-horn :midi-channel 2))
                         (vc (cello :midi-channel 3))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5))))
            :set-map '((1 (1 1 1 1 1))
                       (2 (1 1 1 1 1))
                       (3 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((4 4) h q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((cl (1 1 1 1 1))
                                (hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((cl (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (3 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))))))
      (print (get-all-players (get-section mini 1)))
      (print (get-all-players (get-section mini 2)))
      (print (get-all-players (get-section mini 3))))

    =>
    (CL HN VC)
    (CL HN VC)
    (CL HN VC)

SYNOPSIS

    (defmethod get-all-players ((s section))

## section/get-bar [ Methods ]

[ Top ] [ section ] [ Methods ]

DESCRIPTION

     Return the rthm-seq-bar object at the specified bar number within the given
     section.

     NB: The bar number is counted from the beginning of the entire piece, not
         the beginning of the section.

ARGUMENTS

     - A section object.
     - An integer that is the bar number for which to return the rthm-seq-bar
       object. This number is 1-based and counts from the beginning of the
       piece, not the beginning of the section.

OPTIONAL ARGUMENTS

     NB: The <player> argument is actually required, but is listed as optional
         for reasons of class inheritance.

     - The ID of the player for whose part the rthm-seq-bar object is to be
       returned.

RETURN VALUE

     A rthm-seq-bar object.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((cl (b-flat-clarinet :midi-channel 1))
                         (hn (french-horn :midi-channel 2))
                         (vc (cello :midi-channel 3))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5)))
                           (2 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5)))
                           (3 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5))))
            :set-map '((1 (1 1 1 1 1))
                       (2 (2 2 2 2 2))
                       (3 (3 3 3 3 3)))
            :rthm-seq-palette '((1 ((((4 4) h q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5))))
                                (2 ((((4 4) q e s s h))
                                    :pitch-seq-palette ((1 2 3 4 5))))
                                (3 ((((4 4) e s s h q))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((cl (1 1 1 1 1))
                                (hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((cl (2 2 2 2 2))
                                (hn (2 2 2 2 2))
                                (vc (2 2 2 2 2))))
                            (3 ((cl (3 3 3 3 3))
                                (hn (3 3 3 3 3))
                                (vc (3 3 3 3 3))))))))
      (get-bar (get-section mini 3) 11 'hn))

    =>
    RTHM-SEQ-BAR: time-sig: 2 (4 4), time-sig-given: T, bar-num: 11,
                  old-bar-nums: NIL, write-bar-num: NIL, start-time: 40.000,
                  start-time-qtrs: 40.0, is-rest-bar: NIL, multi-bar-rest: NIL,
                  show-rest: T, notes-needed: 5,
                  tuplets: NIL, nudge-factor: 0.35, beams: NIL,
                  current-time-sig: 2, write-time-sig: NIL, num-rests: 0,
                  num-rhythms: 5, num-score-notes: 5, parent-start-end: NIL,
                  missing-duration: NIL, bar-line-type: 0,
                  player-section-ref: (3 HN), nth-seq: 0, nth-bar: 0,
                  rehearsal-letter: NIL, all-time-sigs: (too long to print)
                  sounding-duration: 4.000,
                  rhythms: (
    [...]
    )
    SCLIST: sclist-length: 6, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: "3-bar1", tag: NIL,
    data: ((4 4) E S S H Q)

SYNOPSIS

    (defmethod get-bar ((s section) bar-num &optional player)

## section/get-sequenz [ Methods ]

[ Top ] [ section ] [ Methods ]

DESCRIPTION

     Get the specified sequenz object from a given section object.

ARGUMENTS

     - A section object.
     - The ID of the player from whose part the sequenz object is to be
       returned.
     - An integer that is the number of the sequence object to be returned from
       within the given section object. This number is 1-based.

RETURN VALUE

     A sequenz object.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((cl (b-flat-clarinet :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4))))
            :set-map '((1 (1 1 1 1 1))
                       (2 (1 1 1 1 1))
                       (3 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((4 4) h q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5))))
                                (2 ((((4 4) q e s s h))
                                    :pitch-seq-palette ((1 2 3 4 5))))
                                (3 ((((4 4) e s s h q))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((cl (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((cl (2 2 2 2 2))
                                (vc (2 2 2 2 2))))
                            (3 ((cl (3 3 3 3 3))
                                (vc (3 3 3 3 3))))))))
      (get-sequenz (get-section mini 2) 'vc 2))

    =>
    SEQUENZ: pitch-curve: (1 2 3 4 5)
    RTHM-SEQ: num-bars: 1
              num-rhythms: 5
              num-notes: 5
              num-score-notes: 5
              num-rests: 0
              duration: 4.0
              psp-inversions: NIL
              marks: NIL
              time-sigs-tag: NIL
              handled-first-note-tie: NIL
             (for brevity's sake, slots pitch-seq-palette and bars are not printed)
    SCLIST: sclist-length: 3, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: (1), this: (2), next: (3)
    BAR-HOLDER:
                start-bar: 7
                end-bar: 7
                num-bars: 1
                start-time: 24.0
                end-time: 28.0
                start-time-qtrs: 24.0
                end-time-qtrs: 28.0
                num-notes (attacked notes, not tied): 5
                num-score-notes (tied notes counted separately): 5
                num-rests: 0
                duration-qtrs: 4.0
                duration: 4.0 (4.000)

SYNOPSIS

    (defmethod get-sequenz ((s section) player seq-num) ; 1-based

## section/has-subsections [ Methods ]

[ Top ] [ section ] [ Methods ]

DESCRIPTION

     Boolean test to determine whether a specified section of a slippery-chicken
     object has subsections.

ARGUMENTS

     - A section object.

RETURN VALUE

     T if the specified section has subsections, otherwise NIL.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((vn (violin :midi-channel 1))))
            :set-palette '((1 ((c4 d4 e4 f4 g4 a4 b4 c5))))
            :set-map '((1
                        ((a (1 1 1))
                         (b (1 1 1))))
                       (2 (1 1 1 1))
                       (3
                        ((a (1 1 1))
                         (b
                          ((x (1 1 1))
                           (y (1 1 1))))))
                       (4
                        ((a (1 1 1))
                         (b (1 1 1))
                         (c (1 1 1 1)))))
            :rthm-seq-palette '((1 ((((2 4) (q) e (s) s))
                                    :pitch-seq-palette ((1 2)))))
            :rthm-seq-map '((1
                             ((a ((vn (1 1 1))))
                              (b ((vn (1 1 1))))))
                            (2 ((vn (1 1 1 1))))
                            (3
                             ((a ((vn (1 1 1))))
                              (b
                               ((x ((vn (1 1 1))))
                                (y ((vn (1 1 1))))))))
                            (4
                             ((a ((vn (1 1 1))))
                              (b ((vn (1 1 1))))
                              (c ((vn (1 1 1 1))))))))))
      (print (has-subsections (get-section mini 1)))
      (print (has-subsections (get-section mini 2))))

    =>
    T
    NIL

SYNOPSIS

    (defmethod has-subsections ((s section))

## section/num-sequenzes [ Methods ]

[ Top ] [ section ] [ Methods ]

DESCRIPTION

     Get the number of sequenz objects in a given section object.

ARGUMENTS

     - A section object.

RETURN VALUE

     An integer that is the number of sequenz objects in the specified section
     object.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((vc (cello :midi-channel 1))))
            :set-palette '((1 ((f3 g3 a3 b3 c4))))
            :set-map '((1 (1 1 1 1 1))
                       (2 (1 1 1 1 1))
                       (3 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((4 4) h q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((vc (1 1 1 1 1))))
                            (2 ((vc (1 1 1 1 1))))
                            (3 ((vc (1 1 1 1 1))))))))
      (num-sequenzes (get-section mini 2)))

    => 5

SYNOPSIS

    (defmethod num-sequenzes ((s section))

## section/re-bar [ Methods ]

[ Top ] [ section ] [ Methods ]

DESCRIPTION

     Regroup the consecutive note and rest events of a given section object into
     new bars of the specified time signature.

     This method will only combine short bars into longer ones; it will not
     split up longer bars and recombine them.

     The method will also use the specified (or default) time signature as a
     target, and may be forced to create a number of bars that are not of the
     specified time signature if the number of beats in the given section object
     do not correspond.

     NB: The user must call the update-slots method after using this method as a
         post-generation editing method.

ARGUMENTS

     - A section object.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :start-bar. An integer that is the first bar within the specified section
       that is to be re-barred. Default = First bar of the given section.
     - :end-bar. An integer that is the last bar within the specified section
       that is to be re-barred. Default = Last bar of the given section.
     - :min-time-sig. The target time signature for all new bars. NB: Depending
       on the number of beats in the given section, the method may have to
       deviate from this target time signature. Default = '(2 4).
     - :verbose. T or NIL to indicate whether to print feedback on the
       re-barring process to the Lisp listener. Default = NIL.
     - :auto-beam.  T, NIL, or an integer. If T, the method will automatically
       attach beam indications to the corresponding events according to the beat
       unit of the time signature. If an integer, the method will beam in
       accordance with a beat unit that is equal to that integer. If NIL, the
       method will not automatically place beams. Default = T.

RETURN VALUE

     T.

EXAMPLE

SYNOPSIS

    (defmethod re-bar ((s section)
                       &key start-bar
                       end-bar
                       (min-time-sig '(2 4))
                       verbose
                       ;; could also be a beat rhythmic unit
                       (auto-beam t))