[ prev | next | top ]

## 15. Import/Export Commands

Commands that import or export data between pic and its environment are described here.

### 15.1. File and Table Insertion

The statement

copy filename

inserts the contents of filename in the pic input stream. Any .PS/.PE pair in the file is ignored. You can use this to include pre-generated images.

A variant of this statement replicates the copy thru feature of grap(1). The call

copy filename thru macro

calls macro (which may be either a name or replacement text) on the arguments obtained by breaking each line of the file into blank-separated fields. The macro may have up to 9 arguments. The replacement text may be delimited by braces or by a pair of instances of any character not appearing in the rest of the text.

If you write

copy thru macro

omitting the filename, lines to be parsed are taken from the input source up to the next .PE.

In either of the last two copy commands, GNU gpic permits a trailing ‘until word’ clause to be added which terminates the copy when the first word matches the argument (the default behavior is therefore equivalent to until .PE).

Accordingly, the command

.PS
copy thru % circle at ($1,$2) % until "END"
1 2
3 4
5 6
END
box
.PE

is equivalent to

.PS
circle at (1,2)
circle at (3,4)
circle at (5,6)
box
.PE

### 15.2. Debug Messages

The command print accepts any number of arguments, concatenates their output forms, and writes the result to standard error. Each argument must be an expression, a position, or a text string.

### 15.3. Escape to Post-Processor

If you write

command arg...

pic concatenates the arguments and pass them through as a line to troff or TeX. Each arg must be an expression, a position, or text. This has a similar effect to a line beginning with . or \, but allows the values of variables to be passed through.

For example,

.PS
x = 14
command ".ds string x is " x "."
.PE
\*[string]

prints

x is 14.

### 15.4. Executing Shell Commands

The command

sh { anything... }

macro-expands the text in braces, then executes it as a shell command. This could be used to generate images or data tables for later inclusion. The delimiters shown as {} here may also be two copies of any one character not present in the shell command text. In either case, the body may contain balanced {} pairs. Strings in the body may contain balanced or unbalanced braces in any case.

[ prev | next | top ]