tap.lib

/*
MIT License

Copyright (c) 2022 Haggai Nuchi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

declare name "Tap Library";
declare author "Haggai Nuchi";
declare license "MIT";
declare version "0.1";

//-------------------------------`(tap.)extract`-------------------------------
//
// Tap a complicated expression to pull out specific outputs, without having to
// manually route those outputs, just like how named function parameters remove
// the need to manually route inputs.
//
// #### Usage
//
// ```
// A(k) = *(k);
//
// complicatedExpression = _,_,_,_ : (
//         (A(1) <: _,tap.T1),
//          A(2),
//          A(3),
//         (A(4) <: _,tap.T2),
//          A(5)
//     ) ~ (_,_,_,_,_ :> _ <: _,tap.T3)
//       : si.block(5)
//       ;
// process = tap.extract(complicatedExpression, (tap.T1, tap.T2, tap.T3));
// ```
//
// Each tap.T1, tap.T2, etc functions as a named !, i.e. has one input and zero
// outputs. When an expression is wrapped with tap.extract, the inputs to the T's
// get routed to the outputs of the expression (after any existing outputs).
//
// In the above example, `complicatedExpression` has four inputs and zero outputs.
// Extracting the three taps (tap.T1, tap.T2, tap.T3) means that `process` will
// have four inputs and three outputs (in the same order as the second argument to
// tap.extract).
//
// #### Named taps
//
// There are pre-defined taps `tap.T1`, ..., `tap.T9`. If you need more than that
// in a single `tap.extract` call, you can define your own with `tap.namedTap`,
// though you need to carefully follow the required syntax:
//
// ```
// myTap = tap.namedTap(tgroup("my custom tap", _));
//
// process = tap.extract(
//     (_ <: myTap, _)
// , myTap);
// ```
//
// #### Limitations
//
// Each tap can only take a single wire input, i.e. does not handle a bus of more
// than one signal. You can use `par` to create a parallel bus of taps, though,
// see the example above.
//
// Some kinds of Faust expressions can't be extracted through. Functions with
// parameters are opaque to tap.extract, and likewise hgroup/vgroup/tgroup, so the
// following don't work:
//
// ```
// A(x, y, z) = x + y + z : tap.T1;
// process = tap.extract(A, tap.T1); // Doesn't work
//
// process = tap.extract(
//     hgroup("foo", (hslider("bar", 0, 0, 1, 1) : tap.T1)),
//     tap.T1
// ); // Doesn't work
// ```
//
// But these workarounds do:
//
// ```
// // Move tap.extract inside the function definition:
// A(x, y, z) = tap.extract((x + y + z : tap.T1), tap.T1);
// process = A; // works
//
// // Use the group name in the UI input name
// process = tap.extract(
//     (hslider("h:foo/bar", 0, 0, 1, 1) : tap.T1),
//     tap.T1
// ); // works
// ```
//
// #### Block diagram
//
// The resulting block diagram can potentially be quite visually messy, so when
// developing, consider developing the expression without the final `tap.extract`
// and then include it only once you have the rest working.
//
// -------------------------------`(tap.)persist`-------------------------------
//
// Like tap.extract, except it merely ensures that the taps get computed rather
// than routing them to the output. Useful for persisting hbargraph/vbargraph
// without manually routing to an output and then calling `attach`. The
// implementation is just `extract` followed by `attach`, so it's required that
// the first argument to `persist` have at least one output (so that `attach` has
// something to work with).
//
// #### Usage
//
// ```
// A(k) = *(k);
//
// complicatedExpression = _,_,_,_ : (
//         (A(1) <: _,(hbargraph("first", 0, 1) : tap.T1)),
//          A(2),
//          A(3),
//         (A(4) <: _,(hbargraph("second", 0, 1) : tap.T2)),
//          A(5)
//     ) ~ (_,_,_,_,_ :> _ <: _,tap.T3)
//       : si.block(5)
//       ;
// process = tap.persist(
//     tap.extract(complicatedExpression, tap.T3),
//     (tap.T1, tap.T2)
// );
// ```

si = library("signals.lib");

namedTap(n) = _, (hslider("tap.lib", 0, 0, 1, 1) : n) :> !;

T1 = namedTap(tgroup("tap.T1", _));
T2 = namedTap(tgroup("tap.T2", _));
T3 = namedTap(tgroup("tap.T3", _));
T4 = namedTap(tgroup("tap.T4", _));
T5 = namedTap(tgroup("tap.T5", _));
T6 = namedTap(tgroup("tap.T6", _));
T7 = namedTap(tgroup("tap.T7", _));
T8 = namedTap(tgroup("tap.T8", _));
T9 = namedTap(tgroup("tap.T9", _));

persist(sig, (i, rest)) = persist(persist(sig, i), rest);
persist(sig, i) = extract(sig, i) : si.bus(outputs(sig) - 1), attach;


extract(sig, (i, rest)) = extract(extract(sig, i), rest);
extract(sig, i) = _check(_extract(sig, i))
with {
    _check(extracted) = _error_if_not_found(extracted, outputs(extracted) - outputs(sig), i) with {
        _error_if_not_found(extracted, 1, i) = extracted;
        _error_if_not_found(extracted, 0, i) = _error_not_found(i);
    };

    // Found a tap! Replace with its input. Add a dummy tgroup that shows up in the box diagram.
    _extract((y, (hslider("tap.lib", 0, 0, 1, 1) : n) :> !), (_, (hslider("tap.lib", 0, 0, 1, 1) : n) :> !)) = y : n;

    // Found par/seq/split/merge/rec! Recurse.
    // ,
    _extract((a, b), current_tap) = _choose_par(
        _extract(a, current_tap),
        _extract(b, current_tap),
        outputs(_extract(a, current_tap)) - outputs(a),
        outputs(_extract(b, current_tap)) - outputs(b),
        outputs(a), // pass this in to simplify block diagram if it's 0
        outputs(b) // number of wires to skip if we extract from a
    ) with {
        // don't clutter with si.bus(0) = 0:! if outputs(a) == 0
        _choose_par(aa, bb, 1, 0, 0, _to_skip) =
            aa, b
            // Like ro.cross1n, but without the indirection so we avoid cluttering the box diagram
            : route(_to_skip+1, _to_skip+1, par(i, _to_skip+1, (i+1, (_to_skip+i)%(_to_skip+1)+1)));
        _choose_par(aa, bb, 1, 0, _else, _to_skip) =
            aa, b
            : si.bus(outputs(a))
                // Like ro.cross1n, but without the indirection so we avoid cluttering the box diagram
              , route(_to_skip+1, _to_skip+1, par(i, _to_skip+1, (i+1, (_to_skip+i)%(_to_skip+1)+1)));
        _choose_par(aa, bb, 0, 1, _unused1, _unused2) = a, bb;
        _choose_par(aa, bb, 0, 0, _unused1, _unused2) = a, b;
        _choose_par(aa, bb, m, n, _unused1, _unused2) = _error_reuse(current_tap);
    };

    // :
    _extract((a : b), current_tap) = _choose_seq(
        _extract(a, current_tap),
        _extract(b, current_tap),
        outputs(_extract(a, current_tap)) - outputs(a),
        outputs(_extract(b, current_tap)) - outputs(b)
    ) with {
        _choose_seq(aa, bb, 1, 0) = aa : b, _;
        _choose_seq(aa, bb, 0, 1) = a : bb;
        _choose_seq(aa, bb, 0, 0) = a : b;
        _choose_seq(aa, bb, m, n) = _error_reuse(current_tap);
    };

    // <:
    _extract((a <: b), current_tap) = _choose_spl(
        _extract(a, current_tap),
        _extract(b, current_tap),
        outputs(_extract(a, current_tap)) - outputs(a),
        outputs(_extract(b, current_tap)) - outputs(b)
    ) with {
        _choose_spl(aa, bb, 1, 0) = aa : (si.bus(outputs(a)) <: b), _;
        _choose_spl(aa, bb, 0, 1) = a <: bb;
        _choose_spl(aa, bb, 0, 0) = a <: b;
        _choose_spl(aa, bb, m, n) = _error_reuse(current_tap);
    };

    // :>
    _extract((a :> b), current_tap) = _choose_mrg(
        _extract(a, current_tap),
        _extract(b, current_tap),
        outputs(_extract(a, current_tap)) - outputs(a),
        outputs(_extract(b, current_tap)) - outputs(b)
    ) with {
        _choose_mrg(aa, bb, 1, 0) = aa : (si.bus(outputs(a)) :> b), _;
        _choose_mrg(aa, bb, 0, 1) = a :> bb;
        _choose_mrg(aa, bb, 0, 0) = a :> b;
        _choose_mrg(aa, bb, m, n) = _error_reuse(current_tap);
    };

    // ~
    _extract((a ~ b), current_tap) = _choose_rec(
        _extract(a, current_tap),
        _extract(b, current_tap),
        outputs(_extract(a, current_tap)) - outputs(a),
        outputs(_extract(b, current_tap)) - outputs(b),
        inputs(a) - outputs(b) // number of wires to cross if we extract from b
    ) with {
        _choose_rec(aa, bb, 1, 0, _unused) = aa ~ b;
        _choose_rec(aa, bb, 0, 1, _to_skip) = (
            si.bus(outputs(b)),
            // like ro.cross1n, but we don't do indirection, so that it doesn't show up in the box diagram
            route(_to_skip+1, _to_skip+1, par(i, _to_skip+1, (i+1, (_to_skip+i)%(_to_skip+1)+1)))
            : a, _) ~ bb;
        _choose_rec(aa, bb, 0, 0, _unused) = a ~ b;
        _choose_rec(aa, bb, m, n, _unused) = _error_reuse(current_tap);
    };

    // Found anything else! Pass it through unchanged.
    _extract(y, (_, (hslider("tap.lib", 0, 0, 1, 1) : n) :> !)) = y;

    // Something bad in the second argument! (i.e. not T1, T2, T3, ...). Error.
    _extract(y, anything_else) = _error_bad_arg(anything_else);
    _error_bad_arg(0) = !:tgroup("Error: expected a tap (e.g. tap.T1, tap.T2, etc), found something else.", _);

    _error_reuse(0) = !:tgroup("Error: used the same tap more than once (the following argument list in the error message will show which one.)", _);

    _error_not_found(0) = !:tgroup("Error: could not find the requested tap to extract (the following argument list will show which one.)", _);
};