On this page:
What is the Result Buffer?, Buffer Commands, Using the Buffer.
Hypatia never leaves files open, so, with each result that is written to hy Hypatia opens the file, performs the write process, and closes the file again.
For single results this works fast enough. If a loop (see chapter "Loops") writes thousands of results to hy, though, the slowness of this process will be felt.
In such a case buffer mode will make Hypatia considerably faster by storing the results in a buffer which resides in memory, until they get written to hy in a single write-to-disc operation at the end of the loop (or do not get written to a file at all, if they are not needed anymore).
As an additional feature, buffer mode lets you write the results to a file of your choice instead of hy.
Unlike silent or accumulation modes, which apply to individual calculation lines, buffer mode is turned on with a command, and remains in effect until it is turned off again, or until Hypatia is closed.
With buffer mode turned on, every result that would be written to hy gets written to the buffer instead.
BUFFER START -- turns buffer mode on, with an empty buffer. If buffer mode is already on, clears the buffer.
BUFFER SHOW -- displays buffer content (only when not more than 40 lines or 4000 characters).
BUFFER SAVE filename comment -- saves the current content of the buffer to the specified file, anything after filename gets included as a comment line.
BUFFER FLUSH -- writes buffer to hy replacing its previous content, clears the buffer and turns buffer mode off.
BUFFER DISCARD -- clears the buffer without saving it to a file, and turns buffer mode off.
BUFFER -- displays buffer mode (ON, ON but empty, or OFF).
(buffer) -- if buffer mode is on inserts the content of the buffer into the input line.
If you want to view the content of the buffer when it has more than 40 lines or 4000 characters, you can save it to a file with BUFFER SAVE filename, and open it with EDIT filename.
When buffer mode is on, everything that would otherwise be written to the result file hy will be written to the buffer, in exactly the same way.
Accumulation mode (& or && at the end of a calculation line) and silent mode (# at the end of a calculation line) work with the buffer exactly as they do with hy.
The commands & and && also work the same way: in buffer mode, the command & clears the buffer, while && adds a line break.
(Do not confuse the commands & and &&, which stand on their own, with the & and && control symbols at the end of a calculation line!)
After turning buffer mode on with the BUFFER START command, the buffer is empty. The result file hy will remain unaffected and can still be copied with COPY, opened in an editor with EDIT, or inserted into an input line with (hy). Only the BUFFER FLUSH command will replace it with the content of the buffer.
The commands HY and EDIT and the clipboard commands COPY and COPYALL always refer to the result file hy, even when buffer mode is on.
As long as buffer mode is on, the expression (buffer) can be used as if buffer were an insert file, exactly as you might use (hy):
... (buffer) ... means insert buffer into the input line.
... (buffer) i ITEM ... means the ith item in the buffer (when i is negative, counted backwards from the end).
@myude = (buffer) means assign the content of the buffer to a user defined element.
When buffer mode is on, the BUFFER SAVE command lets you export the current content of the buffer to a file without deleting the buffer.
BUFFER FLUSH replaces hy with the content of the buffer, clears the buffer, and turns buffer mode off.
If the buffer is empty, BUFFER FLUSH only turns buffer mode off, but does not overwrite hy.
To end buffer mode without writing the content of the buffer to hy (because you do not need it anymore, or because you have already saved it to a different file), use BUFFER DISCARD.
Home, Up: Results, Prev: Result Commands, Next Chapter: Scripts