The StreamWeaver modules give you a 'visual analogue' of unix-style pipes, using the Weaver diagram manager program, into which you can place and connect instances of the supplied modules. The 'StreamView' module provides for input and output of editable text data in a window. Two others — 'ReadFile' and 'WriteFile' — let you pass file data directly to and from pipelines. The 'PipeStream' module will run any shell command line; you can set up any number of these in a diagram, connected together with 'pipelines' that feed the output from one module to the input of another. 'SerialPort' will pass data to and from the hardware serial ports on your machine.
Remember that — like all Weaver modules — these modules only respond to (and generate) data packets of a relevant type, in this case 'text' and 'byte data'. They will ignore all others, such as the MIDI packets passed between MusicWeaver elements. Only the MusicWeaver modules that generate text data — such as "MidiMon" — can be usefully connected to them.
This is a multiconnector module: the input stream can be passed through to a succeeding element on a separate output, distinct from the one on which typed or selected text will appear. A second input connection (also passed through) will trigger sending of currently selected displayed text if any packet arrives there (probably not very useful, but it's there if you want it...).
The two buttons at the top of the window should be fairly obvious. The left hand one will send any selected text; the other sends an 'End-Of-Data' signal, which will terminate the command in any PipeStream that receives it unless that is set to ignore these. If a StreamView receives an End-Of-Data, it displays a separator line (but takes no other action).
The StreamView window behaves like a standard BTextView, except in one respect: in 'Lines' mode the 'Enter' key only inserts a newline in the window when it is at the very end of the text, but it always sends the entire line. This lets you easily resend any line by moving the cursor anywhere within it and typing 'Enter', without disturbing the displayed layout. 'Ctrl-Enter' has essentially the reverse effect: it always inserts a newline, but never transmits the line. [Yes — I borrowed this from Eddie...] This non-standard behaviour is only seem in 'Lines' mode (see below). (The display text is not saved, by the way, when you save the diagram.}
The 'Send as:' selector at top right of the panel determines which user actions result in data being transmitted. In the default state('Lines'), typed-in data is sent only when 'Enter' is typed, as a complete line. In 'Keystrokes' mode it is sent a character at a time, keystroke by keystroke. (Keystroke mode is only effective on typed-in data — it doesn't change how a selected block is sent.) When the mode is 'Selected Only', nothing is ever sent as characters are entered or a new line is started: you must highlight the data you want to send and click 'SEND Selected'. In these latter two modes, the panel accepts input in a perfectly standard way — 'Enter' is always echoed in the window. Also remember, though, that in Keystroke mode everything is sent, including things like cursor movement and deletions.
While a file is open to accept data, its name is displayed in the control panel. It will remain open until an End-Of-Data is received or the 'CLOSE' button is clicked. If no file is open, the panel displays '<Closed>'. The current directory in the filepanel, though not any filename, is recorded in the configuration file when you save.
For convenience, the File Selector Panel remains visible once it is opened, so you can quickly transmit several files in sequence. If you want to send multiple files in a particular order, you should drag (or select) them in that order separately, rather than as a group, as the order in which a group of files is processed is up to the Tracker's fancy alone.
The current directory in the filepanel is recorded in the configuration file when you save, but the filename itself is not.
There are now two variants of this module: the original one that uses pipes, which result in output from the command being batched in a buffer, and "PipeStream_PTY" that passes on stdout and stderr immediately whenever they are generated by the command.
This is a 'Multiconnector' element. The first output path connected is by default the command's standard output, but a second one may also be attached to get a 'pass-through' of the input stream. A second input connection (also passed through) will trigger (re-)execution of the command when any packet arrives there (same as the 'Run' button).
The element control panel has two text entry fields: one for the desired execution directory, and the other for the command itself. The directory field is unimportant unless the command accesses or creates files (or unless the command itself is not in the default shell path); if you leave it blank, it will be taken as the system default — presumably /boot/home. (If you type in an invalid directory path, an alert box will appear to notify you, but the name is retained; you can create the directory — via the Tracker or otherwise — before starting the command if you wish. Changing the directory while a command is running has no effect until a new run is started.) If you prefer to browse for a directory, rather than typing it in, you can use the 'Dir' button on the right to bring up a selection panel.
Typing Enter after typing the command line will start execution immediately (and the displayed status will change from 'Stopped' to 'RUNNING'). You can also use the 'Run' button to begin execution. You have to use this if you want to run the same command again, because the text-entry control ignores the Enter key if the line has not been changed. (Caution: clicking 'Run' when the command is already running will cause it to stop rather than run. The 'Trigger' input will restart a running command but may cause problems — see below.)
Depending on the command you enter, it may finish its own execution and terminate, or it may terminate when it receives 'end-of-data' on its input, or it might just keep on going until forcibly killed. If you need to kill it, the 'Stop' button should do the job — but see below for variant behaviour. When a command terminates, an end-of-data is always sent to the output path (whether or not there has actually been any output).
The popup-selection button at top right of the panel controls the run mode. 'Normal' means that the command will just run once each time it is started; if it is processing standard input, it will (if well behaved.) quit when it gets an end-of-data. If you would rather that end-of-data signals on the input stream did not get passed to the command (so that it will keep on running until stopped) set the selection to 'Ignore E-O-D'. If you want it to get restarted automatically each time it terminates, use 'Auto-Restart'. Response to the 'Stop' button is slightly different in this last mode: the first click of the button just switches the mode back to 'Normal', so that the command will complete its processing if possible; if you need to really shut it down, click it a second time. [This is an attempt to bypass an apparent bug in the posix layer that causes 'orphan threads' if a 'kill' occurs at the wrong time. See warning below.]
When you save a diagram to a configuration file, the state of the element is preserved in that file. The command and directory are recorded (as text strings), as is the mode setting and whether or not the command is actually running when the save is performed.
The original version of the module only handles standard input and standard output. It does not, for example, directly handle standard error output. If you want to see this on the Output connector of the element, just redirect with the '2>&1' bash convention. Or of course you can redirect it elsewhere to a file or a named pipe. PipeStream_PTY passes stderr to its output by default, though you can still redirect it if you wish.
As there is only one input stream, you cannot easily use commands such as 'diff' that by nature need two inputs, except again by using files or named pipes [which sort of seems to negate the 'visual pipeline' concept!].
Warning: There is a problem somewhere in the original version that will leave 'orphan' threads if you use the Trigger input to "start" an already running command. This does not seem to happen with the PTY one.
Initially, when first placed, a SerialPort element is not attached to any port. Select the desired port from the popup menu of the top button ('Select') in its panel. Only one instance of the module can be attached to each available port.
If you need to alter any port settings from the defaults, use the menu brought up by the lower button ('Settings...'). Note that the 'Flow Control' submenu is disabled while a port is actually selected, because this mode cannot be changed on an active port; if you must change it, switch to 'NO CONN' in the port-selection menu, adjust the flow control mode, then reselect the desired port.
The current port, and all the settings, are saved when you make a configuration file, and will be restored when the file is invoked.
[Caution 1: On the BeBox, you will see — in addition to 'serial1' through 'serial4' — 'com3' and 'com4'. Don't select these latter two! They'll just hang the machine. I really don't know why they're there...]
[Caution 2: To send commands to a modem, you are likely to need to terminate them with the return character, rather than the newline generated by the 'Enter' key. This can cause endless confusion and annoyance, but I'm afraid you're on your own there.]
You are permitted to distribute the Weaver program, the StreamWeaver modules, and documentation in the form of the supplied ZIP archive without charge for non-commercial purposes, provided that the whole package is kept intact. For commercial use or distribution (other than charging a reasonable media and copying fee) please contact the author.
Pete Goodeve Berkeley, California e-mail: pete@jwgibbs.cchem.Berkeley.EDU pete.goodeve@computer.org