vipsi - the built-in words
Author: kio@little-bat.de
Keywords: vipsi shell script interpreter programming

# vipsi - shell and script language

## the built-in words

### instructions

#### new

    new [identifier [=value] | file text_value | dir text_value] [,…]

create variable, file or directory.
optionally assign initial value to variable.

#### del

    del [identifier | file text_value | dir text_value] [,…]

delete and forget variable, file or directory.

e.g.: `del a,b[1],c.wert`

#### swap

    swap [variable_ref,variable_ref | file text_value,file text_value] [,…]

swap two list items.
if they are named, names are swapped too.

#### var

    var identifier [=value] [,…]

Create variable if it does not already exist.
optionally assign initial value.

#### freeze

    freeze [file] text_value

compress text or file. undo compression with melt.
note: files must fit into ram twice.

e.g.: `var a="fuzzy";a#=a;a#=a;a#=a; freeze a; count a;`

#### melt

uncompress text or file which has been compressed with freeze.
note: files must fit into ram twice.

e.g.: `var a="fuzzy";a#=a;a#=a;a#=a; freeze a; melt a;`

#### put

    put [#num_value,] value [,…]

write data in text format. default stream is stdout. default text encoding is UTF-8 unicode.

    isText:   character set and end-of-line conversion applied.
    isNumber: number is written in readable format; e.g. +123.456e-78.
    isList:   enclosed in curly brackets; e.g.: { 123 456 "anton" {} }.
              member functions (procedures) are ignored.
    isProc:   prints source (if available) or disassembly.
    isVoid:   prints an asterics: *.

#### log

    log value [,…]

write data to stderr.
except for that, 'log' works exactly like 'put'.

#### get

    get [#num_value,] variable_ref [,…]

read data in text format. default stream is stdin. default text encoding is UTF-8 unicode. default timeout is off (blocking). input stops at next end of line for each variable. reading from a tty (terminal) uses the line editor.

data interpretation depends on destination variable type:

    isText:   character set conversion applied.
    isNumber: numeric format: -123.456e+78
    others:   error.

#### edit

    edit [#num_value,] variable_ref [,…]

edit (write and reread) data in text format. default stream is stdin. default text encoding is UTF-8 unicode. default timeout is off (blocking).

edit finished with end of line (return) for each variable. reading from a tty (terminal) uses the line editor. data presentation is the same as for 'put'.

#### getchar

    getchar [#num_value,] variable_ref [,…]

read single character in text format. default stream is stdin. default text encoding is UTF-8 unicode. default timeout is off (blocking). reads from tty (terminal) without echo.

data deposition depends on destination variable type:

    isText:   character is stored as text.
    isNumber: character code is stored as number.
    others:   error.

#### write

    write [#num_value,] variable_ref

write text in binary mode. default stream is stdout.
no conversions applied. text is written 'as is'.

#### read

    read[#num_value,]variable_ref

read text in binary mode. default stream is stdin. default timeout is off (blocking).

reads from tty (terminal) without echo. no conversion applied. text is read 'as is', every byte making a character. destination text variable is filled with data from stream. on timeout, eof or error the text is truncated.

#### ioctl

    ioctl[#num_value,] [identifier=value|variable_ref=identifier]

Set stream settings or querry stream state

•••under development•••

set only:

            ioctl flush|flushin|flushout

set/read:

            ioctl timeout = 0 (off)  or  number (seconds)
            ioctl text    = "utf-8"  or  "mac-roman"
            ioctl pos     = number         (file: read-write-pointer)
                            {row,col}      (tty:  cursor location)

read only:

            ioctl var = type               ("tty", "file", etc.)
            ioctl var = inavail            (bytes readable w/o blocking)
            ioctl var = outfree            (bytes writable w/o blocking)
            ioctl var = error              (0=ok, 1=eof, 2=timeout, ...)
            ioctl var = size               (file: number, tty: {rows,cols})
            ioctl var = name               (filename)
            ioctl var = isopen/isopenin/isopenout

#### include

    include text_value [,…]

load and execute named script file just as if it's contents were part of the current source.

note: the file is included at the time when this instruction is executed, that means: maybe never, maybe repeatedly, if it occurs in a loop. it is not included at pre-compile time or in some kind of pre-processor as in C.

#### dir

    [ variable_ref=dir text_value | dir [#num_value,] text_value ]

print contents of named directory.
name may be full or partial or start with ~ for user's home directory and may contain a match pattern with wildcards for files to list.

1. function: returns a 2-dimensional list. the list items are named.
2. statement: prints beautified folder listing to stderr or stream number.

#### info

    info identifier [,…]

print info for built-in word: `info idf | token | @"idf|token" | "token|idf"`

#### sort

    sort list_value[,…]

sort list in ascending order

#### rsort

    rsort list_value [,…]

sort list in descending order

#### convert

    convert variable_ref from|to identifier
    text_value = convert( text_value|list_value to|from identifier )

convert text from utf-8 to named encoding or vice versa.

1. instruction: if used as an instruction, the supplied variable is converted.
2. function: if used as a function, the converted data is returned as result.

possible encoding:

        printable      escape characters breaking vipsi's syntax for text literals
        quoted         escape and add '"'s at both ends
        html           convert > to &gt; etc.; does not convert non_ascii characters
        mac_roman      convert to mac roman character set
        iso_latin_1    convert to iso latin 1 character set
        iso_latin_2    convert to iso latin 2 character set
        windows        convert to iso latin 1
        archimedes     convert to iso latin 1
        ucs_2          convert to 2-byte unicode
        ucs_4          convert to 4-byte unicode
        ascii_us       convert to 7-bit ascii
        ascii_ger      convert to 7-bit ascii, german variant (Ä…ß instead of […\)
        dos            convert to dos latin US character set (codepage 437)
        atari          convert to atari st character set

    e.g.: convert mytext to printable;
          convert mytext to mac_roman;
          convert mytext from html;
          log convert(mytext to quoted);

#### open

    open [#num_value,] filename

open file/stream for reading and writing

#### openin

    openin [#num_value,] filename

open file/stream for reading

#### openout

    openout [#num_value,] filename

open file/stream for writing

#### close

    close [#num_value]

close open file/stream

#### rename

    rename variable_ref = text_value

assign name to variable. e.g. `rename a[0]="anton"`

#### cd

    cd text_value

change working directory. e.g.: `cd "../";`

#### pwd

    pwd [#num_value]

print working directory path. default stream is stderr. similar to `log fullpath "./".`

#### words

    words [#num_value]

List most known tokens, procedures and functions. default stream is stderr.