Where a type error came from. The arg number starts at 0.

Catch and rethrow an error, presumably to annotate it with more information.

Each kind of deriver looks a different scope for its calls. By making this a class method, I can figure out which scope to look in just from the type.

This is essentially a translation from dynamically typed ScopesT and Scopes to statically typed Generator Note etc. The class itself should be closed, and correspond exactly to the fields of ScopesT * Scopes. Surely there is some more direct way to express this, but I haven't figured it out yet. TODO what would this look like in idris?

What to call this call, for error msgs when lookup fails.

This is for ctx_prev_val. Normally the previous value is available in all its untagged glory based on the type of the call, but ValCalls can occur with all the different types, so they need a tagged ctx_prev_val.

Context for Callable on both Generator and Transformer. It has this name because top-level expression calls have this context.

All the state available during derivation.

State which is threaded linearly. This destroys the ability to parallelize derivation, so it's not so great. However, the only threaded state is state_prev_val, which is only needed within a track, so sibling tracks can still be parallelized.

This is a dynamically scoped environment that applies to generated events inside its scope.

Instrument aliases as (alias, destination) pairs. Map through this before looking in state_lookup_instrument. The alias destination is always the final instrument, not another alias, so you never have to look up multiple times.

When a note call inverts, it stashes its actual note-generating code so it can re-invoke track evaluation on the control tracks below it. It's kind of like saving a continuation.

Previously I did it by copying the text of the inverting call to the generated track. The problem was that I therefore had to keep the evaluated expression around in the call Context, and if I forgot to clear it in the right places things would be very confusing when a later inversion executed unexpected code. under_invert transforms are now also stored as code rather than data, in state_under_invert.

Strip out fields that I don't need to remember in a TrackDynamic.

If I don't do this, I get a memory leak. Presumably the cause is that state_pitch_map has an unevaluated pitch derivation, which in turn somehow retains the previous derivation, and then the previous, and so on. This makes each derivation leak more space.

Initial control environment.

A default dynamic that's not 0 is useful because otherwise you have to add dyn to everything. Since control tracks multiply by default, 1 is the most convenient value.

This is the library of built-in calls, indexed by Module. On import, the imported CallMaps are inserted into Scopes at PrioBuiltin.

The map takes priority over the patterns.

This represents all calls in scope. Different types of calls are in scope depending on the track type, except ValCalls, which are in scope everywhere. This is dynamic scope, not lexical scope.

Perhaps this should be called Namespaces, but Id.Namespace is already taken and Scopes is shorter.

TODO this could probably now do with a more general name maybe CallType for this, and CallKind for Scope? This is arg type, Scope is return type, or maybe TrackType.

Calls are in scope by expression position (generator, transformer, track, val) and then by track type (note, control, pitch). Expression position also determines the the argument type (generator: nothing, transformer: deriver, track: TrackTree.EventsTree), while track type determines the return type (Deriver Note, Deriver Control, Deriver Pitch).

Val calls are special in that they always have the same type (Args -> Val), and are in scope in val call exrpession position for all track types.

names: EScope, TScope for ExpressionScope and TrackScope? ExprScope, TrackScope? I'd want to update the names in CallDoc too.

An instrument or scale may put calls into scope. If that instrument or scale is replaced with another, the old calls must be replaced with the new ones.

Priority is determined by get_scopes, which returns them in the fields' declaration order.

The reason this can't be accomplished just by arranging imports in the right order is that when an instrument or scale comes into scope, it needs to replace existing instrument or scale calls. To do that, I need to keep each category separate. Also, this way I can import the ky file once at the toplevel, and it will still override PrioBuiltin calls.

Add this call at this level of priority. It will shadow existing calls with the same name.

Replace all calls at this level of priority.

This is like Call, but with only documentation. (name, CallDoc)

Values that don't change during one derive run.

Derivation can run in a few distinct modes.

The built-in set of control Mergers.

Unlike the rest, this one is not associative.

Mostly the deriver just deals with instruments as strings, and doesn't understand anything else about them. However, it does need a few other things, which are expressed here to avoid excessive dependencies between the systems.

Some ornaments only apply to a particular instrument, so each instrument can bring a set of note calls and val calls into scope, via the Scope type. This is like Builtins, but without the Module map, since they're all implicitly in PrioInstrument.

How to merge a control into Dynamic.

Combine two signals. The element should be an identity, like mempty. ControlMod uses it to avoid affecting signal outside of the modified range. The merge function is not obliged to be associative, so this isn't actually a monoid. TODO it's all the fault of merge_scale... do I lose something important with associativity?

These are things that collect throughout derivation, and are cached in addition to the derived values. Effectively they are extra return values, which are combined with mappend. So this is the WriterT part of State.

These are fragments of a signal, which will be later collected into collect_track_signals. This is part of a complicated mechanism to evaluate TrackSignals only once. When the sliced fragments of a track are evaluated, they collect signal fragments. When the track is fully evaluated, they are sorted and merged into collect_track_signals. If the track is then evaluated again, the monoid instance will discard the duplicate.

The signal fragments are indexed by the slice position. Since merge makes the earlier signals win in case of overlaps, this ensures a trimmed earlier fragment won't replace a more complete later one.

This is a hack so a call on a control track can modify other controls. The motivating case is pitch ornaments that also want to affect the dynamics. The modifications are a secondary return value from control and pitch calls. The track deriver will extract them and merge them into the dynamic environment. [NOTE control-modification]

Snapshots of the environ at each track. This is used by the Cmd layer to figure out what the scale and instrument are for a given track.

Originally this was a map from Stacks to Environ (and only the changed parts). The idea was that I could walk up the stack to find the Environ value in scope at a given point, and given Stack.Region, could even get e.g. per event instruments. Unfortunately, while it's easy to do that on the Derive side, it seems really complicated and somewhat expensive to try to retrace a complete stack on every cmd. Since this implementation doesn't store the entire stack, a track with a different instrument at different times will wind up with the last one.

This is a much simpler solution which will hopefully work well enough in practice.

NOTE [record-track-dynamics] One complication is that when I get controls from sliced tracks, the controls are also sliced. But I need the environ from the inverted version of the track so the common case of [>i, *scale] gets the correct scale. So I record TrackDynamic for both inverted and non inverted tracks and prefer the inverted tracks, but take controls from the non-inverted versions.

This is the logical duration of a call. This may be different from its actual duration (which is to say, the end time of the last event it emits). Also, while most calls adjust their duration to the duration of the event they are called from, some of them have their own intrinsic duration. For example, a block call may stretch to its calling event's duration, but it also has its own duration that is used to align the block's end, or to sequence blocks.

Since the call duration is sometimes used to place the call in the first place (e.g. to align its end), I want to evaluate the minimum amount necessary to find the duration. The implementation is that each generator call has a gfunc_score_duration field. When Derive.Eval is evaluating a generator call, if it sees that state_mode is ScoreDurationQuery, instead of calling gfunc_f, it will call gfunc_score_duration and return the result via collect_score_duration. You shouldn't stick your fingers into this machinery, but instead use Derive.get_call_duration to do the gefingerpoken for you.

I'm not very happy with this implementation, but I tried several approaches and this is the only one that worked. Historical details are in NOTE [call-duration].

Additional data for a call. This part is invariant for all calls on an event.

The events are not used for transform calls.

TODO make separate types so the irrelevent data need not be passed?