[ prev | next | top ]

21. PIC Reference

This is an annotated grammar of pic.

21.1. Lexical Items

In general, pic is a free-format, token-oriented language that ignores whitespace outside strings. But certain lines and contructs are specially interpreted at the lexical level:

A comment begins with # and continues to \n (comments may also follow text in a line). A line beginning with a period or backslash may be interpreted as text to be passed through to the post-processor, depending on command-line options. An end-of-line backslash is interpreted as a request to continue the line; the backslash and following newline are ignored.

Here are the grammar terminals:


A positive integer.


A floating point numeric constant. May contain a decimal point or be expressed in scientific notation in the style of printf(3)’s %e escape. A trailing ‘i’ or ‘I’ (indicating the unit ‘inch’) is ignored.


A string enclosed in double quotes. A double quote within TEXT must be preceded by a backslash. Instead of TEXT you can use

sprintf ( TEXT [, <expr> ...] )

except after the ‘until’ and ‘last’ keywords, and after all ordinal keywords (‘th’ and friends).


A string starting with a character from the set [a-z], optionally followed by one or more characters of the set [a-zA-Z0-9_]. (Values of variables are preserved across pictures.)


A string starting with a character from the set [A-Z], optionally followed by one or more characters of the set [a-zA-Z0-9_].


A line starting with a command character (‘.’ in groff mode, ‘\’ in TeX mode).


A string either enclosed by ‘{’ and ‘}’ or with X and X, where X doesn’t occur in the string.


Delimiters as in BALANCED-TEXT ; the body will be interpreted as ‘⟨ command⟩ ...’.


The name of a file. This has the same semantics as TEXT .



21.2. Semi-Formal Grammar

Tokens not enclosed in ⟨ ⟩ are literals, except:


\n is a newline.


Three dots is a suffix meaning ‘replace with 0 or more repetitions of the preceding element(s).


An enclosure in square brackets has its usual meaning of ‘this clause is optional’.


Square-bracket-enclosed portions within tokens are optional. Thus, ‘h[eigh]t’ matches either ‘height’ or ‘ht’.

If one of these special tokens has to be referred to literally, it is surrounded with single quotes.

The top-level pic object is a picture.

<picture> ::=
  <statement> ...
  .PE \n

The arguments, if present, represent the width and height of the picture, causing pic to attempt to scale it to the given dimensions in inches. In no case, however, will the X and Y dimensions of the picture exceed the values of the style variables maxpswid and maxpsheight (which default to the normal 8.5i by 11i page size).

If the ending ‘.PE’ is replaced by ‘.PF’, the page vertical position is restored to its value at the time ‘.PS’ was encountered. Another alternate form of invocation is ‘.PS < FILENAME ’, which replaces the ‘.PS’ line with a file to be interpreted by pic (but this feature is deprecated).

The ‘.PS’, ‘.PE’, and ‘.PF’ macros to perform centering and scaling are normally supplied by the post-processor.

In the following, either ‘|’ or a new line starts an alternative.

<statement> ::=
  <command> ;
  <command> \n

<command> ::=
  <primitive> [<attribute>]
  LABEL : [;] <command>
  LABEL : [;] <command> [<position>]
  { <command> ... }
  VARIABLE [:] = <any-expr>
  up | down | left | right
  command <print-arg> ...
  print <print-arg> ...
  copy [FILENAME] thru MACRONAME [until TEXT]
  copy [FILENAME] thru BALANCED-BODY [until TEXT]
  for VARIABLE = <expr> to <expr> [by [*] <expr>] do BALANCED-BODY
  if <any-expr> then BALANCED-BODY [else BALANCED-BODY]
  reset [VARIABLE [[,] VARIABLE ...]]

<print-arg> ::=

The current position and direction are saved on entry to a ‘{ ... }’ construction and restored on exit from it.

Note that in ‘if’ constructions, newlines can only occur in BALANCED-BODY . This means that

{ ... }
{ ... }

will fail. You have to use the braces on the same line as the keywords:

if {
} else {

This restriction doesn’t hold for the body after the ‘do’ in a ‘for’ construction.

<any-expr> ::=
  <any-expr> <logical-op> <any-expr>
  ! <any-expr>

<logical-op> ::=
  == | != | && | ’||’

<text-expr> ::=

Logical operators are handled specially by pic since they can deal with text strings also. pic uses strcmp(3) to test for equality of strings; an empty string is considered as ‘false’ for ‘&&’ and ‘||’.

<primitive> ::=
  box                   # closed object — rectangle
  circle                # closed object — circle
  ellipse               # closed object — ellipse
  arc                   # open object — quarter-circle
  line                  # open object — line
  arrow                 # open object — line with arrowhead
  spline                # open object — spline curve
  TEXT TEXT ...         # text within invisible box
  plot <expr> TEXT      # formatted text
  ’[’ <command> ... ’]’

Drawn objects within ‘[ ... ]’ are treated as a single composite object with a rectangular shape (that of the bounding box of all the elements). Variable and label assignments within a block are local to the block. Current direction of motion is restored to the value at start of block upon exit. Position is not restored (unlike ‘{ }’); instead, the current position becomes the exit position for the current direction on the block’s bounding box.

<attribute> ::=
  h[eigh]t <expr>       # set height of closed figure
  wid[th] <expr>        # set width of closed figure
  rad[ius] <expr>       # set radius of circle/arc
  diam[eter] <expr>     # set diameter of circle/arc
  up [<expr>]           # move up
  down [<expr>]         # move down
  left [<expr>]         # move left
  right [<expr>]        # move right
  from <position>       # set from position of open figure
  to <position>         # set to position of open figure
  at <position>         # set center of open figure
  with <path>           # fix corner/named point at specified location
  with <position>       # fix position of object at specified location
  by <expr-pair>        # set object’s attachment point
  then                  # sequential segment composition
  dotted [<expr>]       # set dotted line style
  dashed [<expr>]       # set dashed line style
  thick[ness] <expr>    # set thickness of lines
  chop [<expr>]         # chop end(s) of segment
  ’->’ | ’<-’ | ’<->’   # decorate with arrows
  invis[ible]           # make primitive invisible
  solid                 # make closed figure solid
  fill[ed] [<expr>]     # set fill density for figure
  colo[u]r[ed] TEXT     # set fill and outline color for figure
  outline[d] TEXT       # set outline color for figure
  shaded TEXT           # set fill color for figure
  same                  # copy size of previous object
  cw | ccw              # set orientation of curves
  ljust | rjust         # adjust text horizontally
  above | below         # adjust text vertically
  aligned               # align parallel to object
  TEXT TEXT ...         # text within object
  <expr>                # motion in the current direction

Missing attributes are supplied from defaults; inappropriate ones are silently ignored. For lines, splines, and arcs, height and width refer to arrowhead size.

The ‘at’ primitive sets the center of the current object. The ‘with’ attribute fixes the specified feature of the given object to a specified location. (Note that ‘with’ is incorrectly described in the Kernighan paper.)

The ‘by’ primitive is not documented in the tutorial portion of the Kernighan paper, and should probably be considered unreliable.

The primitive ‘arrow’ is a synonym for ‘line ->’.

Text is normally an attribute of some object, in which case successive strings are vertically stacked and centered on the object’s center by default. Standalone text is treated as though placed in an invisible box.

A text item consists of a string or sprintf-expression, optionally followed by positioning information. Text (or strings specified with ‘sprintf’ may contain [gtn]roff font changes, size changes, and local motions, provided those changes are undone before the end of the current item.

A position is an (x,y) coordinate pair. There are lots of different ways to specify positions:

<position> ::=

<position-not-place> ::=
  <position> + <expr-pair>
  <position> - <expr-pair>
  ( <position> , <position> )
  <expr> [of the way] between <position> and <position>
  <expr> ’<’ <position> , <position> ’>’

<expr-pair> ::=
  <expr> , <expr>
  ( expr-pair )

<place> ::=
  <label> <corner>
  <corner> [of] <label>

<label> ::=
  LABEL [. LABEL ...]

<corner> ::=
  .n | .e | .w | .s
  .ne | .se | .nw | .sw
  .c[enter] | .start | .end
  .t[op] | .b[ot[tom]] | .l[eft] | .r[ight]
  left | right | <top-of> | <bottom-of>
  <north-of> | <south-of> | <east-of> | <west-of>
  <center-of> | <start-of> | <end-of>
  upper left | lower left | upper right | lower right

<xxx-of> ::=
  xxx                   # followed by ‘of’

<nth-primitive> ::=
  <ordinal> <object-type>
  [<ordinal>] last <object-type>

<ordinal> ::=
  INT th
  INT st | INT nd | INT rd
  ‘ <any-expr> ’th

<object-type> ::=

As Kernighan notes, “since barbarisms like 1th and 3th are barbaric, synonyms like 1st and 3rd are accepted as well.” Objects of a given type are numbered from 1 upwards in order of declaration; the last modifier counts backwards.

The “’th” form (which allows you to select a previous object with an expression, as opposed to a numeric literal) is not documented in DWB’s pic(1).

The ⟨ xxx-of⟩ rule is special: The lexical parser checks whether xxx is followed by the token ‘of’ without eliminating it so that the grammar parser can still see ‘of’. Valid examples of specifying a place with corner and label are thus

A .n
.n of A
.n A
north of A


north A
A north

both cause a syntax error. (DWB pic also allows the weird form ‘A north of’.)

Here the special rules for the ‘with’ keyword using a path:

<path> ::=
  ( <relative-path> , <relative-path> )

<relative-path> ::=
  . LABEL [. LABEL ...] [<corner>]

The following style variables control output:

Image grohtml-290748.png

Any of these can be set by assignment, or reset using the reset statement. Style variables assigned within ‘[ ]’ blocks are restored to their beginning-of-block value on exit; top-level assignments persist across pictures. Dimensions are divided by scale on output.

All pic expressions are evaluated in floating point; units are always inches (a trailing ‘i’ or ‘I’ is ignored). Expressions have the following simple grammar, with semantics very similar to C expressions:

<expr> ::=
  <place> <place-attribute>
  <expr> <op> <expr>
  - <expr>
  ( <any-expr> )
  ! <expr>
  <func1> ( <any-expr> )
  <func2> ( <any-expr> , <any-expr> )
  rand ( )

 .x | .y | .h[eigh]t | .wid[th] | .rad

<op> ::=
  + | - | * | / | % | ^ | ’<’ | ’>’ | ’<=’ | ’>=’

<func1> ::=
  sin | cos | log | exp | sqrt | int | rand | srand

<func2> ::=
  atan2 | max | min

Both exp and log are base 10; int does integer truncation; and rand() returns a random number in [0-1).

There are define and undef statements which are not part of the grammar (they behave as pre-processor macros to the language). These may be used to define pseudo-functions.

define name { replacement-text }

This defines name as a macro to be replaced by the replacement text (not including the braces). The macro may be called as

name(arg1, arg2, ..., argn)

The arguments (if any) will be substituted for tokens $1, $2 ... $n appearing in the replacement text. To undefine a macro, say undef name, specifying the name to be undefined.

[ prev | next | top ]