## tos - Text output stream

### Module Description

The tos module implements a text output stream. It extends the str module, so all words from the str module, can be used on a tos variable. The data written to the stream is always appended. Alignment is normally done for the last written data. By using the start alignment pointers words the start of the alignment can be changed. The end of the alignment is always the end of the stream. The message catalog can be used for localization of strings. Note: the numerical words in this module use the the numeric output string. The writer can be used to direct the result of the formatter to a writer word by calling tos-flush:

     Stack usage writer word: c-addr u x -- flag = Write c-addr u, return success

### Module Words

#### Output stream structure

tos% ( -- n )
  Get the required space for a tos variable

#### Output stream creation, initialisation and destruction

tos-init ( tos -- )
  Initialise the empty output stream
tos-(free) ( tos -- )
  Free the tos data from the heap
tos-create ( "<spaces>name" -- ; -- tos )
  Create a named output stream in the dictionary
tos-new ( -- tos )
  Create a new output stream on the heap
tos-free ( tos -- )
  Free the output stream from the heap

#### Stream words

tos-rewrite ( tos -- )
  Rewrite the output stream

#### Alignment start pointer words

tos-pntr@ ( tos -- u )
  Get the current alignment start pointer
tos-pntr! ( n tos -- flag )
  Set the alignment pointer from start [n>=0] or from end [n<0], return success
tos-pntr+! ( n tos -- flag )
  Add the offset n to the alignment pointer, return success

#### Writer words

tos-set-writer ( x xt tos -- )
  Use the stream for writing using the writer callback xt and its data x
tos-flush ( tos -- )
  Flush the contents of the stream to the writer

#### Message catalog words

tos-msc! ( msc tos -- )
  Set the message catalog for the output stream
tos-msc@ ( tos -- msc | nil )
  Get the message catalog for the output stream

#### Write data words

tos-write-char ( char tos -- )
  Write character to the stream
tos-write-chars ( char u tos -- )
  Write u chars to the stream
tos-write-string ( c-addr u tos -- )
  Write the string c-addr u to the stream, using the message catalog if present
tos-write-line ( tos -- )
  Write end-of-line from config to the stream, not align able
tos-write-number ( n tos -- )
  Write the number n in the current base to the stream
tos-write-double ( d tos -- )
  Write the double d in the current base to the stream
tos-write-float ( r tos -- )
  Write the float r to the stream in notation: [-]0.digitsE[-]digits, using PAD and PRECISION
tos-write-fixed-point ( r tos -- )
  Write the float r to the stream in fixed-point notation: [-]digits.digits0, using PAD and PRECISION

#### Alignment words

tos-align ( char u1 u2 tos -- )
  Align the previous written data with padding character char, u1 trailing chars and u2 leading chars
tos-align-left ( char u tos -- )
  Align the previous written data to the left, using padding character char with width u
tos-align-right ( char u tos -- )
  Align the previous written data to the right, using padding character char with width u
tos-center ( char u tos -- )
  Center the previous written data, using padding character char with width u

#### Inspection

tos-dump ( tos -- )
  Dump the text output stream

generated 03-Jun-2010 by ofcfrth-0.10.0