Skip to content

Latest commit

 

History

History
385 lines (326 loc) · 9.92 KB

grammar.md

File metadata and controls

385 lines (326 loc) · 9.92 KB

Pikchr Grammar

This file describes the grammar of the input files to Pikchr. Keywords and operators are shown in bold. Non-terminal symbols are shown in italic. Special token classes are shown in ALL-CAPS. A grammar symbol followed by "*" means zero-or-more. A grammar symbol followed by "?" means zero-or-one. Parentheses are used for grouping. Two grammar symbols within "(..|..)" means one or the other. Marks of the form "▶info" are links to more information and are not part of the grammar.

The following special token classes are recognized:

  • NEWLINE → A un-escaped newline character, U+000A. A backslash followed by zero or more whitespace characters and then a U+000A character is interpreted as ordinary whitespace, not as a NEWLINE.

  • LABEL → An object or place label starting with an upper-case ASCII letter and continuing with zero or more ASCII letters, digits, and/or underscores. A LABEL always starts with an upper-case letter.

  • VARIABLE → A variable name consisting of a lower-case ASCII letter or "$" or "@" and followed by zero or more ASCII letters, digits, and/or underscores. VARIABLEs may contain upper-case letters, but they never begin with an upper-case. In this way, VARIABLEs are distinct from LABELs.

  • NUMBER → A numeric literal. The value can be a decimal integer, a floating point value, or a hexadecimal literal starting with "0x". Decimal and floating point values can optionally be followed by a two-character unit designator that is one of: "in", "cm", "px", "pt", "pc", or "mm". There can be no whitespace in between the numeric portion of the constant and the unit.

  • ORDINAL → A non-zero integer literal followed by one of the suffixes "st", "nd", "rd", or "th". Examples: "1st", "2nd", "3rd", "4th", "5th", and so forth. As a special case, "first" is accepted as an alternative spelling of "1st".

  • STRING → A string literal that begins and ends with double-quotes (U+0022). Within the string literal, a double-quote character can be escaped using backslash (U+005c). A backslash can also be used to escape a backslash. No other escape sequences are recognized and standalone backslashes are elided from the output. Newlines are permitted in strings.

  • COLORNAME → One of the 140 official HTML color names, in any mixture of upper and lower cases. The value of a COLORNAME is an integer which is the 24-bit RGB value of that color. Two additional color names of "None" and "Off" are also recognized and have a value of -1.

  • CODEBLOCK → All tokens contained within nested {...}. This is only used as the body of a "define" statement.

There are many non-terminals in the grammar, but a few are more important. If you are new to the Pikchr language, begin by focusing on these six:

  • statement → A Pikchr script is just a list of statements.

  • attribute → Each graphic object is configured with zero or more attributes.

  • object → A reference to a prior graphic object, or this to refer to the current object.

  • place → A specific point associated with an object.

  • position → Any (2-D) point in space. An (x,y) pair.

  • expr → A scalar expression.

A complete input file to Pikchr consists of a single statement-list.

statement-list: ▶info

  • statement?
  • statement-list NEWLINE statement?
  • statement-list ; statement?

statement: ▶info

  • object-definition
  • LABEL : object-definition
  • LABEL : place
  • direction
  • VARIABLE assignment-op expr
  • define VARIABLE CODEBLOCK ▶info
  • print print-argument (, print-argument)*
  • assert ( expr == expr )
  • assert ( position == position )

direction:

  • right
  • down
  • left
  • up

assignment-op:

  • =
  • +=
  • -=
  • *=
  • /=

print-argument:

  • expr
  • STRING

object-definition:

  • object-class attribute*
  • STRING text-attribute* attribute*
  • [ statement-list ] attribute*

object-class:

attribute:

color-expr: ▶info

  • expr

new-property-value: ▶info

  • expr
  • expr %

numeric-property: ▶info

  • diameter
  • ht
  • height
  • rad
  • radius
  • thickness
  • width
  • wid

text-attribute: ▶info

  • above
  • aligned
  • below
  • big
  • bold
  • mono
  • monospace
  • center
  • italic
  • ljust
  • rjust
  • small

path-attribute: ▶info

  • from position
  • then? to position
  • then? go? direction line-length?
  • then? go? direction until? even with position
  • (then|go) line-length? heading compass-angle
  • (then|go) line-length? compass-direction
  • close

line-length: ▶info

  • expr
  • expr %

compass-angle: ▶info

  • expr

compass-direction:

  • n
  • north
  • ne
  • e
  • east
  • se
  • s
  • south
  • sw
  • w
  • west
  • nw

location-attribute: ▶info

  • at position
  • with edgename at position
  • with dot-edgename at position

position: ▶info

  • expr , expr
  • place
  • place + expr , expr
  • place - expr , expr
  • place + ( expr , expr )
  • place - ( expr , expr )
  • ( position , position )
  • ( position )
  • fraction of the way between position and position
  • fraction way between position and position
  • fraction between position and position
  • fraction < position , position >
  • distance which-way-from position

fraction:

  • expr

distance

  • expr

which-way-from:

  • above
  • below
  • right of
  • left of
  • n of
  • north of
  • ne of
  • e of
  • east of
  • se of
  • s of
  • south of
  • sw of
  • w of
  • west of
  • nw of
  • heading compass-angle from

place: ▶info

  • object
  • object dot-edgename
  • edgename of object
  • ORDINAL vertex of object

object:

  • LABEL
  • object . LABEL
  • nth-object of|in object

nth-object:

  • ORDINAL object-class
  • ORDINAL last object-class
  • ORDINAL previous object-class
  • last object-class
  • previous object-class
  • last
  • previous
  • ORDINAL []
  • ORDINAL last []
  • ORDINAL previous []
  • last []
  • previous []

dot-edgename:

  • .n
  • .north
  • .t
  • .top
  • .ne
  • .e
  • .east
  • .right
  • .se
  • .s
  • .south
  • .bot
  • .bottom
  • .sw
  • .w
  • .west
  • .left
  • .nw
  • .c
  • .center
  • .start
  • .end

edgename:

  • n
  • north
  • ne
  • e
  • east
  • se
  • s
  • south
  • sw
  • w
  • west
  • nw
  • t
  • top
  • bot
  • bottom
  • left
  • right
  • c
  • center
  • start
  • end

expr:

  • NUMBER
  • VARIABLE
  • COLORNAME
  • place .x
  • place .y
  • object dot-property
  • ( expr )
  • expr + expr
  • expr - expr
  • expr * expr
  • expr / expr
  • - expr
  • + expr
  • abs ( expr )
  • cos ( expr )
  • dist ( position , position )
  • int ( expr )
  • max ( expr , expr )
  • min ( expr , expr )
  • sin ( expr )
  • sqrt ( expr )

dot-property:

  • .color
  • .dashed
  • .diameter
  • .dotted
  • .fill
  • .ht
  • .height
  • .rad
  • .radius
  • .thickness
  • .wid
  • .width