.. This file is auto-generated by the Sphinx pre-build hook in ``docs/source/conf.py`` from ``docs/source/_data/patcher_objects.json`` and the notes in ``docs/source/_data/patcher_notes/``. Do not edit by hand — run ``dart run tool/gen_patcher_snapshot.dart`` to refresh the JSON from the bound engine and ``dart run tool/port_patcher_notes.dart`` to refresh the notes from the engine submodule, then rebuild the docs. Control flow ============ Ordering, looping, conditions and load-time messages. 11 objects. Every entry is pulled directly from the engine registry, which reads the ``ADD_DESCRIPTION`` / ``INLET_DOC`` / ``OUTLET_DOC`` / ``PARAM_DOC`` macros in the libYSE source; the longer notes under each summary are ported from the libYSE documentation. The ``~`` prefix marks DSP / audio-rate objects; ``.`` marks control-rate objects. Links into the patcher guide (messages, time, data, files, ...) lead to the libYSE documentation, which also has this :yse-cpp:`category's page `. .. contents:: :local: :depth: 1 ``.bangbang`` ------------- Sends a bang out every outlet, right to left, whatever arrives. Each outlet's branch finishes before the next outlet fires, so it orders 'do this, then that'. :Dart: ``Obj.gBangbang`` :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any - Bang, int, float or list. The value is ignored. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out0 - BANG - bang - A bang. The last outlet fires first, outlet 0 last. * - 1 - out1 - BANG - bang - A bang. The last outlet fires first, outlet 0 last. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - outlets - 2 - 1-40 - Number of outlets, clamped to 1-40; a float is truncated. Two when absent or not a number. Unlike .trigger, '.bangbang 3' means three outlets. ``.bondo`` ---------- Holds one value per inlet and sends all of them, right to left, whenever any inlet receives one. Keeps a set of related values together, so nothing downstream sees half an update. :Dart: ``Obj.gBondo`` :Kind: Control-rate Every inlet is hot: a value arriving at any inlet is stored there, and then every outlet sends what its inlet holds, the last outlet first and outlet 0 last (see :yse-cpp:`Messages and dispatch `). Wire outlet 0 to whatever acts on the set and the others to cold inlets, and the whole set is in place when outlet 0 fires. Stored values stay until replaced, so each send repeats the values that did not change. An inlet that has received nothing sends 0. **Messages** Every inlet takes all of these: - an int, float, list or word: store it here and send the set. - a list that starts with a number: spread over this inlet and the ones to its right, one item each; items past the last inlet are dropped. With the ``n`` argument the list is stored whole in this inlet instead. - a message that starts with a word (``note 60``): stored whole in this inlet. - bang: send the set without storing anything. - ``set ``: store as above without sending. A bare ``set`` is an ordinary word: it is stored and the set is sent. **Arguments** In order: the number of inlet/outlet pairs (1-256, default 2), then a delay in milliseconds, then ``n`` to store lists whole (``n`` may stand anywhere). With a delay, a stored value sends the set that many milliseconds later instead of at once; another value before then restarts the wait, so a burst of changes sends one set. A bang still sends at once. Waits are counted in whole audio blocks; see :yse-cpp:`Time, scheduling and clocks `. ``.buddy`` is the other way round: it waits until every inlet has a value. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in0 - FLOAT, INT, BANG, LIST - any - Stores a value here and sends every outlet. A bang sends without storing; 'set ' stores without sending. * - 1 - in1 - FLOAT, INT, BANG, LIST - any - Stores a value here and sends every outlet. A bang sends without storing; 'set ' stores without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out0 - ANY - any - What the matching inlet holds: 0 until it receives something. * - 1 - out1 - ANY - any - What the matching inlet holds: 0 until it receives something. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - ports - 2 - 1-256, optional delay in ms, optional 'n' - Number of inlet/outlet pairs (1-256), then an optional delay in ms, and 'n' to store lists whole. ``.buddy`` ---------- Waits until every inlet has received a value, then sends them all at once, right to left, and starts waiting again. Use it to assemble one event from parts that arrive separately. :Dart: ``Obj.gBuddy`` :Kind: Control-rate Each inlet stores the last value it received. When the last empty inlet receives one, every outlet sends its inlet's value, the last outlet first and outlet 0 last (see :yse-cpp:`Messages and dispatch `), and all inlets are empty again. Nothing is ever sent twice, and nothing is sent for an incomplete set. .. code-block:: text [.buddy 2] in1 <- 7 => nothing in0 <- 3 => out1: 7, out0: 3 in0 <- 4 => nothing (in1 is empty again) **Messages** - an int, float, list or word: stored in this inlet, replacing what it held. A list is stored whole and leaves the matching outlet unchanged. - bang: stores the number 0, so a source with no value of its own can still take part. - ``clear``, on inlet 0 only: empty every inlet without sending. On the other inlets the word is stored like any other value. To send a set on any change, keeping the values that did not change, use ``.bondo``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in0 - FLOAT, INT, BANG, LIST - any - Stores a value here; once every inlet holds one, all are sent. A bang stores 0. On inlet 0, 'clear' empties every inlet. * - 1 - in1 - FLOAT, INT, BANG, LIST - any - Stores a value here; once every inlet holds one, all are sent. A bang stores 0. On inlet 0, 'clear' empties every inlet. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out0 - ANY - any - What the matching inlet received, sent once the set is complete. * - 1 - out1 - ANY - any - What the matching inlet received, sent once the set is complete. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - inlets - 2 - 1-256 - Number of inlet/outlet pairs, clamped to 1-256. A float is truncated. ``.if`` ------- Tests a condition and sends one message when it is true and, optionally, another when it is false: '$i1 > 64 then bang else out2 $i1'. The condition and the message items use the .expr language. :Dart: ``Obj.gIf`` :Kind: Control-rate The argument is a statement: .. code-block:: text then [else ] [.if $i1 > 64 then bang else out2 $i1] When the condition is not 0 the ``then`` message is sent, otherwise the ``else`` message. Without ``else``, a false condition sends nothing, which filters a stream. **The condition** is an expression in the language of ``.expr`` (see :doc:`/api/patcher_objects/math`): the same ``$i1``-``$i9`` and ``$f1``-``$f9`` placeholders, operators, functions and int/float rules. **A message** is up to 16 items separated by spaces. Each item is itself an expression without spaces, such as ``1``, ``0.5``, ``$i1`` or ``$i1*2``. One item is sent as an int or a float, depending on its type; two or more are sent as a list. ``bang`` on its own sends a bang. ``out2`` in front of a message sends it from a second, right outlet, which exists only when a message uses it. **Inlets** There is one inlet per placeholder number, up to the highest one used (at most 9). Inlet 0 stores its number and evaluates; the others only store. A bang on inlet 0 evaluates with the stored numbers, and a list on inlet 0 fills the inlets from the left, then evaluates. An inlet that has received nothing reads 0. **Errors** A statement that cannot be read is reported in the log when the object is created, and the object then sends nothing. Text placeholders (``$s``) are not supported, and neither is a ``send `` message to a named receiver: wire the outlet to a ``.s`` instead. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - $1 - FLOAT, INT, BANG, LIST - any float - Value for $i1 / $f1; stores it and evaluates. A bang evaluates with the stored values; a list fills the inlets from the left, then evaluates. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - ANY - any - The then or else message, unless it starts with out2. One item is sent as an int or float, several as a list, 'bang' as a bang. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - statement - — - any statement - then [else ], e.g. '$i1 > 64 then bang else out2 $i1'. ``.loadbang`` ------------- Sends a bang when the patch it is in has finished loading, so a saved patch can set up its own starting state. A bang at the inlet sends one by hand. :Dart: ``Obj.gLoadbang`` :Kind: Control-rate The bang is sent once, after the whole patch has been loaded with ``Patcher.parseJson``: every object created, every cord connected. Objects inside subpatchers fire in the same pass. An object created with ``Patcher.createObject`` in a running patch does not fire until the patch is saved and loaded again. Send it a bang to fire it by hand; a host that builds a patch object by object can do this to initialise it. The order in which two ``.loadbang`` objects fire is not defined. When one initialisation must come before another, use one ``.loadbang`` and a ``.trigger``. See :yse-cpp:`Patch file format ` for the whole load sequence. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG - bang - A bang sends a bang, as a load does. Use it to initialise a patch built with CreateObject. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BANG - bang - A bang when the patch has finished loading, and for each bang in. ``.loadmess`` ------------- Sends its arguments as a message when the patch it is in has finished loading, such as '.loadmess 0.5' to set a gain. A bang at the inlet sends it by hand. :Dart: ``Obj.gLoadmess`` :Kind: Control-rate Fires at the same moment as ``.loadbang`` and follows the same rules (see there). ``.loadmess 0.5`` into a gain does what ``.loadbang`` into a message box holding ``0.5`` would. The message is sent in the form it has: - nothing at all when the object has no arguments; - a bang for the single word ``bang``; - an int or a float for a single number, an int when written without a ``.`` or an exponent: ``60`` is an int, ``60.0`` a float; - otherwise a list with the text unchanged. **Messages** - bang: send the stored message. - ``set ``: replace the stored message without sending. A bare ``set`` empties it. This works from a list and from a message box. - any other list is ignored, so values passing through cannot replace the initialisation. A ``set`` longer than 256 characters is refused, and the old message is kept. Arguments longer than that are cut at the last whole word that fits. ``set`` does not change the saved arguments: the patch saves the message the object was created with. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger/set - BANG, LIST - bang, or 'set ' - A bang sends the stored message, as a load does. 'set ' replaces it without sending; a bare 'set' empties it. Other lists are ignored. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - ANY - any - The stored message when the patch has finished loading, and for each bang in: a bang, an int, a float or a list, by its form. Nothing when empty. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - message - — - any message, up to 256 characters - The message to send, such as '60' or 'mode 2'. At most 256 characters; with none, the object sends nothing. ``.match`` ---------- Watches a stream of numbers and sends the last few as a list when they match the pattern in its arguments. The word 'nn' matches any number, so '.match 1 nn 3' sends '1 5 3' after 1, 5, 3. :Dart: ``Obj.gMatch`` :Kind: Control-rate The object keeps the most recent numbers, as many as the pattern is long. When those spell the pattern, it sends them as a list and forgets them, so matches never overlap. .. code-block:: text [.match 1 nn 3] 1, 5, 3 => 1 5 3 [.match 1 2 3] 1 2 1 2 3 => 1 2 3 [.match 1 1 1] 1 1 1 1 1 => 1 1 1 (once) A value that ends one attempt can start the next, as in the second example. **Matching** - A number in the pattern matches only that exact number. Ints and floats are compared as floats, so ``5`` matches ``5.0``. A calculated float can miss a number that looks equal; put ``.round`` in front. - ``nn`` matches any number. - A word in the stream, or a value that is not finite, takes a place and matches nothing, not even ``nn``. - A pattern word other than ``nn`` (``NN`` included) matches nothing, so the object never fires. With no pattern at all it never fires either. The output keeps the values as they arrived, so the places filled by ``nn`` show what came in. An int is sent as an int and a float as a float. **Messages** - an int, float or list: each number, or each list item, takes the next place in the stream. - ``clear``: forget the numbers received so far. The pattern stays. - ``set ``: a new pattern, written like the arguments. It also forgets the numbers received so far. A bare ``set`` leaves no pattern. The saved arguments do not change. The pattern holds at most 256 elements. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, LIST - any - Int, float or list: each number takes the next place in the stream. Also 'clear' and 'set '. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - match - LIST - list of numbers - The values that matched, in arrival order and spelling, as a list as long as the pattern. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - pattern - — - any list of numbers and nn - The sequence to watch for: numbers, matched exactly, and 'nn' for any number. At most 256 elements. ``.next`` --------- Tells the first message of a burst from the rest: a bang leaves the left outlet when a message starts a new logical event, and the right outlet when it belongs to the same event as the message before it. :Dart: ``Obj.gNext`` :Kind: Control-rate A *logical event* is everything one stimulus causes: one host call, one GUI action, one tick of a timed object, one MIDI message (see *Logical events* in :yse-cpp:`Messages and dispatch `). Time does not matter: two host calls are two events however close together, and the whole fan-out of one ``.trigger`` is one event however long it takes. The first message of an event sends a bang from the left outlet, and every later message of the same event sends one from the right. Exactly one outlet fires per message. Typical use is to do something once per burst, such as resetting a counter at the start of a ``.coll`` dump without knowing how long the dump is. .. code-block:: text [.uzi 3] -> [.next] bang => left, right, right The content of a message is ignored, so a 0 counts like any other value. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any - Bang, int, float or list. Only which event it belongs to matters; every word is an ordinary message. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - separated - BANG - bang - A bang when this message starts a new logical event. The first message ever always goes here. * - 1 - same - BANG - bang - A bang when this message belongs to the same event as the previous one. ``.onebang`` ------------ A one-shot: lets one message through as a bang from the left outlet, then sends every further message out the right outlet until the right inlet re-arms it. :Dart: ``Obj.gOnebang`` :Kind: Control-rate The object is a gate with two states. When armed, the next message on the left inlet sends a bang from the left outlet and closes the gate. When closed, a message sends a bang from the right outlet instead. Every message gives exactly one bang, so the right outlet can count or report the triggers that were blocked; leave it unconnected for a plain one-shot. - Anything on the right inlet arms the gate, including the word ``stop``. Arming an armed gate changes nothing: five arms and five triggers give one pass and four rejects. - Everything on the left inlet is a trigger, including 0. The one exception is the bare word ``stop``, which closes the gate without sending anything. ``stop 1`` is a trigger. - The gate starts closed. A non-zero argument starts it armed; ``0.5`` counts as non-zero, and an argument that is not a number counts as 0. To open and close a path with numbers, use ``.gate``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any - Bang, int, float or list, treated as a bang: it leaves outlet 0 if the gate is armed, outlet 1 if not. The bare word 'stop' closes the gate silently. * - 1 - arm - FLOAT, INT, BANG, LIST - any - Anything here arms the gate, silently. Arming twice still passes only once. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - pass - BANG - bang - A bang when a message arrives while the gate is armed. The gate closes. * - 1 - reject - BANG - bang - A bang when a message arrives while the gate is closed. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial - 0 - 0 or non-zero - Non-zero starts the gate armed, so the first message passes. Closed by default. ``.trigger`` ------------ Sends its input out every outlet, right to left, converted per outlet to an int, a float, a bang, a list or text, or replaced by a constant. Use it to make the order of two branches explicit. :Dart: ``Obj.gTrigger`` :Kind: Control-rate Each argument makes one outlet, in order. When a message arrives, every outlet sends, the last outlet first and outlet 0 last. Each outlet's branch finishes before the next outlet sends (see :yse-cpp:`Messages and dispatch `). .. code-block:: text [.trigger b i] 7 => out1: 7, then out0: bang The common use is ``.trigger b i``: the number reaches a cold inlet first, and only then does the bang make the object compute with it. **Formats** - ``i``: an int. A float is truncated toward zero; a list or a bang sends 0. - ``f``: a float. A list or a bang sends 0. - ``b``: a bang, whatever arrived. - ``l``: a list unchanged. Anything else sends the list ``0``. - ``s``: text unchanged. Text travels as a list, so a list passes through ``s`` too; a number or a bang sends the empty symbol. ``i`` and ``f`` do not read lists: a list ``5 6`` sends 0 from an ``i`` outlet. Use ``.unpack`` or ``.route`` to take numbers out of a list. Any other argument is a constant, sent on every input whatever arrived: a number without a ``.`` or an exponent is an int (``7``), one with them is a float (``0.5``), and anything else is sent as text. The format letters are lower case and single characters, so ``I`` or ``bang`` are constants. With no arguments there are two ``i`` outlets. At most 256 outlets. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any - Bang, int, float or list, sent out every outlet, right to left. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out0 - INT - any int - The input as an int: a float is truncated toward zero, a list or a bang sends 0. * - 1 - out1 - INT - any int - The input as an int: a float is truncated toward zero, a list or a bang sends 0. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - formats - i i - any list of i/f/b/l/s letters and constants - One argument per outlet: 'i', 'f', 'b', 'l' or 's' to convert the input, or any other token as a constant. Two 'i' outlets by default, at most 256. ``.uzi`` -------- Sends a burst of bangs at once, each preceded by its index, then a carry bang when the run is done. The patcher's loop: '.uzi 16' runs sixteen iterations inside one message. :Dart: ``Obj.gUzi`` :Kind: Control-rate A bang starts a run. For each iteration, the index goes out the right outlet, then a bang out the left outlet, so whatever the bang drives already has the new index. After the last iteration the middle outlet sends a bang. .. code-block:: text [.uzi 3] bang => index 1, bang, index 2, bang, index 3, bang, carry [.uzi 4 0] bang => indices 0 1 2 3 Each send finishes everything it triggers before the next one, and the whole run is one logical event (see :yse-cpp:`Messages and dispatch `). A run of 0 iterations still sends the carry bang. **Messages** On the left inlet: - bang: run. - int or float: set the count, then run. A float is truncated. - ``pause`` (or ``break``): stop the run that is in progress after the current iteration. Only a message triggered by the run itself can arrive during a run, so this is how a loop exits early, such as stopping a search once the value is found. A paused run sends no carry bang. Outside a run it does nothing. - ``resume`` (or ``continue``): finish a paused run, numbering on from where it stopped. It does nothing if no run is paused. - ``offset ``: skip the first n iterations of every run from now on, so the run sends count minus n bangs and the index starts at base plus n. ``offset 0`` turns this off. Other words are ignored. The right inlet sets the count for the next run without starting it. **Limits** The count is clamped to 0-4096. A creation argument above that is reported in the log. A bang or ``resume`` that arrives while a run is in progress, for example from an outlet wired back to the left inlet, is ignored, so such a loop always ends. A count changed during a run applies to the next run. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - start - FLOAT, INT, BANG, LIST - any - A bang runs the loop; an int or float sets the count, then runs it. Also 'pause', 'resume' and 'offset '. * - 1 - count - FLOAT, INT - 0-4096 - Sets the count for the next run without starting it. Clamped to 0-4096; a float is truncated. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - bang - BANG - bang - One bang per iteration, right after its index. * - 1 - carry - BANG - bang - A bang once a run has finished. Not sent when a run is paused. * - 2 - index - INT - base to base+count-1 - The iteration's number, sent just before its bang. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - count - 1 - 0-4096 - Bangs per run, clamped to 0-4096 (a larger value is logged). A float is truncated. * - base - 1 - -1000000000 to 1000000000 - The first index. '.uzi 8 0' counts 0 to 7.