ref: e4562fa250aa010e1cab060acbe52da62454e9ce
dir: /orca.man/
.TH ORCA 1
.SH NAME
orca \- an esoteric programming language designed to quickly create procedural sequencers
.SH SYNOPSIS
.B games/orca
[
.I -i
] [
.I -p
] [
.I -bpm bpm
] [
.I -s WxH
] [
.I -r random_seed
] [
.I -c cursor
] [
.I -l undo_limit
] [
.I -n
] [
.I file
]
.SH DESCRIPTION
.I Orca
is not a synthesizer, but a flexible livecoding
environment capable of sending MIDI, OSC & UDP to your audio/visual
interfaces.
.PP
Every letter of the alphabet is an operation, where lowercase letters
operate on bang, uppercase letters operate each frame. Extensive
documentation of the language is available on the project's GitHub web
page, see
.B SOURCE
section.
.PP
There are a number of options:
.TP
.B -i
Destination IP address for UDP and OSC messages.
.TP
.B -u
Port number for UDP messages to be delivered to.
.TP
.B -m
Path to MIDI device for output.
.TP
.B -s
Set initial dimensions of the grid to
.IR W
x
.IR H .
.TP
.B -p
Starts
.I Orca
in paused state.
.TP
.B -r
Starts with a specific random seed.
.TP
.B -b
Sets initial "beats per minute" value.
.TP
.B -c
Sets the cursor character.
.TP
.B -l
Sets the maximum number of undo steps. Default is 100.
.TP
.B -n
Forces the use of
.I nsec()
instead of relying on RDTSC.
.PP
.SH KEYS
.TP
.B '
Enter rectangle
.I selection
mode, use arrows to extend it.
.TP
.B Ctrl+i Insert
Toggle between
.I append
and
.I insert
(overwrite) mode.
.TP
.B Escape
Return to normal mode or deselect.
.TP
.B ´ ` ~
Toggle
.I slide
mode, use arrows to move the selected text around.
.TP
.B Space
Toggle pause.
.TP
.B Ctrl+r
Reset frame counter.
.TP
.B Ctrl+f
Forward one frame, useful in paused mode.
.TP
.B Ctrl+c Ctrl+x
Snarf/cut the selected text.
.TP
.B Ctrl+v
Paste from the snarf buffer.
.TP
.B Ctrl+Shift+v
Paste from the snarf buffer, ignoring empty cells within it, thus not
overwriting what's been at the destination if possible.
.TP
.B Ctrl+z
Undo.
.TP
.B Ctrl+y
Redo.
.TP
.B Ctrl+u Ctrl+l
Convert selected text to upper/lower case.
.TP
.B Ctrl+a Ctrl+e
Jump to the beginning/end of the line.
.TP
.B Home End
Jump to the first/last line.
.TP
.B Delete Backspace Ctrl+h
Keys to remove text.
.TP
.B #
Comment/uncomment selected text.
.TP
.B Ctrl+k
Enter a command. See
.B COMMANDS
section for more information.
.TP
.B Alt+arrow
Move selected text.
.TP
.B Shift+arrow
Extend the selection. Works only in drawterm.
.TP
.B Ctrl+arrow
Jump by the number of cells set for the rulers.
.TP
.B < >
Adjust BPM.
.TP
.B ( ) _ +
Adjust grid size.
.TP
.B [ ] { }
Adjust rulers.
.TP
.B Ctrl+s
Save to file.
.SH MOUSE
Mouse buttons works as one expects it. Left button selects a
rectangle on the grid. Snarf and paste are available by the usual
means. Right button held opens a menu.
.PP
Holding
.I Shift
and pressing left mouse button will extend the selection without
changing the cursor position.
.PP
Holding
.I Alt
and pressing left mouse button will move the selection to the new
cursor position, the cell under the mouse pointer.
.SH COMMANDS
Commands can be entered into Orca either manually with
.B Ctrl+k
or with a
.B $
operator. Arguments may be separated with a (semi)colon as well as
any whitespace characters.
All commands except
.I undo
,
.I redo
and
.I color
have a shorthand equivalent to their first two characters.
.PP
Any command can start with
.I ,
(comma) to select the entire grid before executing the command.
.TP
.B |cmd arg...
Pipe the selected text to a shell command and paste its output back
into the grid. Dots are replaced with spaces before feeding the input
to the command, and the other way around when it comes to command's
output.
.TP
.B <cmd arg...
Execute a shell command and paste its output into the grid. Dots are
replaced with spaces.
.TP
.B >cmd arg...
Pipe the selected text to a shell command. Dots are replaced with spaces.
.TP
.B play
Resume.
.TP
.B stop
Pause.
.TP
.B run
Forward one frame.
.TP
.B copy
Copy the selection to the snarf buffer.
.TP
.B paste
Paste from the snarf buffer.
.TP
.B erase
Erase the selected cells.
.TP
.B bpm NUMBER
Set new BPM value.
.TP
.B apm NUMBER
Animate BPM to the value.
.TP
.B frame NUMBER
Set frame value.
.TP
.B skip NUMER
Increase frame value.
.TP
.B rewind NUMBER
Decrease frame value.
.TP
.B ip ADDR
Set UDP/OSC destination IP address.
.TP
.B udp NUMBER|PATH
Set UDP destination port. Parameter is treated as a filename if it's
an absolute path.
.TP
.B midi PATH
Set MIDI output path.
.TP
.B print
Print selected rectangle to
.IR stdout .
.TP
.B write TEXT [X] [Y]
Writes the text at the cursor position or at
.I X,Y
if specified.
.TP
.B inject FILE [X] [Y]
Injects a file at the cursor position or at
.I X,Y
if specified
.TP
.B select X Y [W] [H]
Select the specified rectangle.
.TP
.B color [rrggbb ...]
Change colors. Without any parameters it prints the current values.
.PP
.I Orca
treats
.I stdin
as a stream of commands, you can run it like so:
.EX
aux/listen1 -t tcp!127.0.0.1!49160 games/orca
.EE
.PP
Then start the following in a separate "command" window:
.EX
telnet tcp!127.0.0.1!49160
.EE
.PP
.SH PLUMBING
Orca supports injecting files at the current cursor position by
plumbing. Add this to your plumbing rules to get it working:
.EX
type is text
data matches '[a-zA-Z¡-0-9_\-.,/]+'
data matches '([a-zA-Z¡-0-9_\-.,/]+)\.orca'
arg isfile $0
data set $file
plumb to orca
plumb start window games/orca $file
.EE
.PP
.SH SOURCE
https://git.sr.ht/~ft/orca