class:: PatternProxy
summary:: stream reference
categories:: Libraries>JITLib>Patterns, Live Coding
related:: Classes/Pdefn

description::
Keeps a reference to a stream that can be replaced while playing. Multiple streams are thus handled without creating dependencies.

ClassMethods::

private::at, hasGlobalDictionary, parallelise, postRepository, removeAll, basicNew, clear, event

method::new
create a new instance with a pattern (the source). the pattern should be a emphasis::value pattern:: (see link::Classes/Pdefn::).

for event pattern proxy, see: link::Classes/EventPatternProxy::. instead of a pattern, a strong::function:: can be passed in, creating a routine.

method::default
a default source, if none is given. the default is 1.0 (it is not 0.0 in order to make it safe for durations)

method::defaultQuant
set the default quantization value for the class. (default: nil)

method::defaultValue
a default return value, if no source is given. the default is 1.0 (it is not 0.0 in order to make it safe for durations). This is used in link::#-endless::.

InstanceMethods::

method::asStream
Return a link::Classes/Stream:: from this pattern. One pattern proxy can be used to produce any number of independent streams.

code::
a = PatternProxy.new;
a.source = Pgeom(1, Pwhite(1.01, 1.2), inf);
b = a.asStream; c = a.asStream;

b.next;
b.next;
b.next;

c.next; // c is independent from b
c.next;

a.source = Pgeom([1, 2, 3], Pwhite(1.01, 1.2), inf); // replace the source

b.next;
c.next;

::

method::embedInStream
Given a link::Classes/Stream:: like e.g. link::Classes/Routine::, yield all values from the pattern in the proxy before continuing. One pattern proxy can be used to produce values for any number of independent streams.

argument::inval
The inval is passed into all substreams and can be used to control how they behave from the outside.

argument::embed
See link::Classes/Object#-streamArg:: for explanation.

argument::default
Replacement for code::nil:: outputs of the source pattern. One use case is link::#-endless::.

code::
a = PatternProxy.new;
a.source = Pgeom(1, Pwhite(1.01, 1.2), 4);
r = Routine { loop { 2.yield; 3.yield; a.embedInStream }; };
r.nextN(12); // the next 12 values from r
a.source = Pgeom([1, 2, 3], Pwhite(1.01, 1.2), inf); // replace the source
r.nextN(12); // the next 12 values from r
::


method::source
set the source. If a quantization is given, schedule this change to the next beat

method::clear
set the source to nil

method::quant
set or get the quantization value

method::condition
provide a condition under which the pattern is switched when a new one is inserted. the stream value and a count is passed into the function. the methods strong::count_(n):: simply counts up to n and switches the pattern then

method::embedInStream
just like any pattern, embeds itself in stream

subsection::Methods implemented for subclasses

PatternProxy implements some methods for the benefits of its subclasses link::Classes/Pdefn:: / link::Classes/Pdef:: / link::Classes/Tdef:: which are not useful for link::Classes/PatternProxy:: and link::Classes/TaskProxy::.

method::envir
provide a default environment for the proxy. If given, it is used as an environment for the routine function. When set for the first time, the routine pattern is rebuilt.

method::set
set arguments in the environment. If there is none, it is created and the pattern is rebuilt.

method::endless
returns a Prout that plays the proxy endlessly, replacing strong::nil:: with a strong::default:: value (1). This allows to create streams that idle on until a new pattern is inserted.

Examples::

code::
a = PatternProxy(Pseq([1, 2, 3], inf));

x = Pseq([0, 0, a], inf).asStream;

t = Task({ loop({ x.next.postln; 0.3.wait }) }).play;


a.source = Pseq([55, 66, 77], inf);
a.source = Pseq([55, 66, 77], 1);

t.stop;
::

code::
// PatternProxy, like Pdefn can be accessed in multiple streams

(
SynthDef("Pdefhelp", { arg out, freq, sustain=1, amp=1, pan;
	var env, u=1;
	env = EnvGen.kr(Env.perc(0.03, sustain), 1, doneAction: Done.freeSelf);
	5.do { var d; d = exprand(0.01, 1); u = SinOsc.ar(d * 300, u, rrand(0.1,1.2) * d, 1) };
	Out.ar(out, Pan2.ar(SinOsc.ar(u + 1 * freq, 0, amp * env), pan));

}).add;
s.boot;
)

(
x = PatternProxy.new;
x.source = Pseq([0, 3, 2], inf);

Pset(\instrument, \Pdefhelp,
	Ppar([
	Pbind(\degree, x),
	Pbind(\degree, x, \dur, 1/3)
])
).play;
)

x.source = Prand([0, 3, [1s, 4]], inf);

x.source = Pn(Pshuf([0, 3, 2, 7, 6], 2), inf);



// if quant is set, the update is done at the next beat or whatever is specified:

x.quant = 4;
x.source = Pn(Pseries(0, 1, 8), inf);

x.quant = nil; // reactivate immediacy

(
x.source = Prout {
	loop {
	4.do { |i|
		#[2, 3, 4].choose.yield;
		#[5, 0, 11].choose.yield;
		#[6, 3, 4].choose.do { |j| (i % j).yield };
	}
	}
}
)
::