#lang scribble/manual
@(require (for-label racket))

@title{Pwalk}
 A one-dimensional random walk over a list of values that are embedded@section{related}
  Classes/Pbrown
@section{categories}
  Streams-Patterns-Events>Patterns>List

@section{ClassMethods}
 

@section{method}
 new

@section{argument}
 list
The items to be walked over.

@section{argument}
 stepPattern
Returns integers that will be used to increment the index into list.

@section{argument}
 directionPattern
Used to determine the behavior at boundaries. When the index crosses a boundary, the next direction is drawn from this stream: 1 means use stepPattern as is, -1 means go in the reverse direction. Common patterns:
@section{definitionList}
 
## 1 || always wrap around to the other boundary.
## Pseq([1, -1], inf) || go forward first, then backward, then forward again.
::

@section{argument}
 startPos
Where to start in the list.

@section{Examples}
 


@racketblock[
(
a = Pwalk(
	Array.series(20, 0, 1),		// integers, 0-19
		// steps up to 2 in either direction, weighted toward positive
	Pwrand([-2, -1, 0, 1, 2], [0.05, 0.1, 0.15, 1, 0.1].normalizeSum, inf),
		// reverse direction at boundaries
	Pseq([1, -1], inf),
	10);	// start in the middle
x = a.asStream;
)

200.do({ x.next.post; ", ".post });

b = a.copy.directionPattern_(1);	// this one will always wrap around
x = b.asStream;

200.do({ x.next.post; ", ".post });



// non-random walk: easy way to do up-and-down arpeggiation
s.boot;
(
a = Pwalk(
	[60, 64, 67, 72, 76, 79, 84].midicps,	// C major
	Pseq([1], inf),
	Pseq([1, -1], inf),	// turn around at either end
	0);
x = a.asStream;

SynthDef(\help_walk, { arg freq;
	Out.ar(0, Saw.ar([freq, freq+1], 0.5) * EnvGen.kr(Env.perc(0.01, 0.1), doneAction: Done.freeSelf))
}).add;
)

(
r = Task({
	{
		Synth.new(\help_walk, [\freq, x.next]);
		0.1.wait;
	}.loop;
}).play(SystemClock);
)

r.stop;
::
]