Karya, built on Sun Nov 26 01:04:37 PST 2017 (patch 0a920b2bde70c0cbac8ee09d158064798b61bbe5)

Derive.Deriver.Lib

Description

This has the higher level parts of the deriver library. That is, functions where are considered basic but can be defined outside of Derive.Deriver.Monad.

Synopsis

derive

data Result Source #

Package up the results of a derivation.

Constructors

 Result Fieldsr_events :: !(Stream.Stream Score.Event) r_cache :: !Cache r_track_warps :: ![TrackWarp.TrackWarp] r_track_signals :: !Track.TrackSignals r_track_dynamic :: !TrackDynamic r_integrated :: ![Integrated] r_state :: !StateThe relevant parts of the final state should be extracted into the above fields, but returning the whole state can be useful for testing.

derive :: Constant -> Dynamic -> Deriver a -> RunResult a Source #

Kick off a derivation.

Extract the merged TrackDynamic from the Collect.

EnvKey.scale comes from the inverted Collect because the scale track is often inverted below the note track. However, the others come from the non-inverted Collect because if the note track sets an instrument, I want to use its instrument, instead of any instrument on individual events. E.g. >kendang-pasang has events that are >kendang-wadon or >kendang-lanang.

See Collect and TrackDynamic for why.

Given an environ, bring instrument and scale calls into scope.

Apply the instrument aliases loaded from the ky file. This should only happen when starting a derivation.

errors

require_right :: CallStack.Stack => (err -> Text) -> Either err a -> Deriver a Source #

state access

import

Merge calls from the given module into scope.

Import only the given symbols from the module.

with_scopes :: (Scopes -> Scopes) -> Deriver a -> Deriver a Source #

Run the derivation with a modified scope.

Filter out any calls that aren't in the given modules.

Filter out calls that don't match the predicate. LookupCalls are also filtered out. This might be confusing since you might not even know a call comes from a LookupPattern, but then you can't import it by name.

merge_lookups :: [LookupCall call] -> [LookupCall call] Source #

Merge LookupMaps into one LookupMap, with any LookupPatterns afterwards. If there are collisions, the first one wins.

Check if the call has a tag. This doesn't support LookupMap, but doesn't need to because I only use it for the block lookup call.

scale

Lookup a scale_id or throw.

environment

Like lookup_val, but throw if the value isn't present.

with_val :: Typecheck.ToVal val => EnvKey.Key -> val -> Deriver a -> Deriver a Source #

Set the given val dynamically within the given computation. This is analogous to a dynamic let.

There is intentionally no way to modify the environment via assignment. It would introduce an order of execution dependency that would complicate caching as well as have a confusing non-local effect.

This dispatches to with_scale or with_instrument if it's setting the scale or instrument, so scale or instrument scopes are always set when scale and instrument are.

with_vals :: Typecheck.ToVal val => [(EnvKey.Key, val)] -> Deriver a -> Deriver a Source #

Like with_val, but should be slightly more efficient for setting multiple values at once.

Merge the given environ into the environ in effect. Unlike with_val or with_vals, this won't set scopes for EnvKey.scale and EnvKey.instrument.

with_val_raw :: Typecheck.ToVal val => EnvKey.Key -> val -> Deriver a -> Deriver a Source #

Like with_val, but don't set scopes for instrument and scale.

This is the Env version of with_merged_control. It only works on numeric env vals.

with_scale :: Scale -> Deriver d -> Deriver d Source #

Replace the scale's calls.

Previously this used add_priority instead of replace_priority, which meant you could overlay scales and use both at the same time. Maybe that's actually a useful feature? In any case, I don't need it at the moment, so it seems more likely to be confusing than useful.

Convert a val call to a pitch call. This is used so scales can export their ValCalls to pitch generators.

Run the a deriver with the given instrument in scope. In addition to assigning the instrument to the EnvKey.instrument field where note calls can inherit it, this also brings the Instrument fields into scope, which is the per-instrument calls and per-instrument environ.

Look up the instrument. Also return the instrument name after resolving any alias. This is what goes in Score.event_instrument, since it's what the performer understands.

control

Return an entire signal.

Get the control value at the given time, taking state_control_functions into account.

Get a ControlValMap at the given time, taking state_control_functions into account.

Arguments

 :: RealTime -> Ruler.Marklists Ruler marklists from the same track as the Dynamic. Needed by control functions, via BaseTypes.dyn_ruler. -> Dynamic -> Int state_event_serial -> Score.ControlValMap

control signal

remove_controls :: [Score.Control] -> Deriver a -> Deriver a Source #

Remove both controls and control functions. Use this when a control has already been applied, and you don't want it to affect further derivation.

Replace the controls entirely.

Modify the given control according to the Merger.

If both signals are typed, the existing type wins over the relative signal's type. If one is untyped, the typed one wins.

As documetned in merge, this acts like a Set if there is no existing control.

Like with_controls, but merge them with their respective default Mergers.

Get the default merger for this control, or merge_mul if there is none.

Combine two signals with a Merger. If there was no old signal, use merger-defined identity value.

Since the default merge for control tracks is multiplication, whose identity is 1, this means the first control track will set the value, instead of being multiplied to 0.

ControlMod

Emit a ControlMod.

Arguments

 :: RealTime Trim controls to end at this time. If a ControlMod is local to a slice it should end when the slice ends, and since it bypasses trim_signal, I have to trim it explicitly. -> Deriver a -> Deriver a

Apply the collected control mods to the given deriver and clear them out.

pitch

The pitch at the given time. The transposition controls have not been applied since that is supposed to be done once only when the event is generated.

The scenario is a call that generates a note based on the current pitch. If pitch_at applied the transposition, the new note would have to remove the transposition signals so they don't get applied again at performance conversion.

Like pitch_at, this is a raw pitch.

Resolve the raw pitch returned from pitch_at to the final transposed pitch.

Unlike pitch_at, the transposition has already been applied, because you can't transpose any further once you have a NoteNumber.

Version of BaseTypes.pitch_nn that logs errors.

with signal

Run the deriver in a context with the given pitch signal.

Mode

Get the CallDuration of the given deriver.

postproc

Arguments

 :: Bool If True, incorporate the evaluated state_collect. This is False for eval which is disconnected from track evaluation, and shouldn't be accumulating things like ControlMods. -> Deriver a -> Deriver (Maybe.Maybe a)

If the deriver throws, log the error and return Nothing.

Replace the state_stack with the one from the event. This is useful for transformers, so they can show a stack trace to the event they are processing.

A combination of catch and with_event_stack.

Shift the controls of a deriver. You're supposed to apply the warp before deriving the controls, but I don't have a good solution for how to do this yet, so I can leave these here for the moment.

Embed a LogId into Deriver. This is for computations that need logging but not a full Deriver.

call

Wrap make_val_call with a Typecheck.to_val to automatically convert to a BaseTypes.Val. This is not in Derive.Deriver.Monad to avoid a circular import with Derive.BaseTypes.