yoshida yoshida DEV
Open the editor

Docs Format Expressions

Expressions: Literals and Units

On this page

Literals

  • Numbers: 12, 0.5. A leading dot (.5) and exponent notation (1e3) are invalid: write 0.5 and 1000. An optional unit suffix follows: %, vw, vh.
  • Strings: 'single' or "double" quotes, with the escapes \', \", \\ and \n. Single quotes avoid escaping inside JSON: "foil ? 'FOIL' : 'NEW'".
  • Booleans: true, false.
  • Colors: #RRGGBB, #RRGGBBAA (8-bit per channel), #RRRRGGGGBBBB, #RRRRGGGGBBBBAAAA (16-bit per channel). Hex digits are case-insensitive. The short forms #RGB and #RGBA are also accepted, each digit doubled, so #F80 is #FF8800.

Internally all colors are 16-bit RGBA; an 8-bit value v becomes v * 257, so #FF is exactly full. Use the 16-bit forms when you need fine gradations in 16-bit PNG output (yoshida render --16bit).

A hex color is a valid expression, so "fill": "#FF0000" and "fill": "accent" are both fine, and so is "fill": "foil ? #F5C542 : accent".

Units

Numbers can carry a unit. Without one a number is a pixel value.

UnitMeans
N%N percent of the canvas along the field's axis
NvwN percent of the canvas width, valid in any number field
NvhN percent of the canvas height, valid in any number field

Where % works

% needs an axis, so it is valid only in fields that have one:

Horizontal fields (percent of canvas width)Vertical fields (percent of canvas height)
box.x, box.wbox.y, box.h
at.xat.y
a polygon point's first valuea polygon point's second value
wrap, max_widthmax_height
crop / fade length toward left or rightcrop / fade length toward top or bottom

Anywhere else (size, radius, stroke.width, line_spacing, ...) % is error 3006 with the hint to use vw or vh. Those two always work. Percentages and vw / vh always refer to the canvas, also inside a group moved with translate.

canvas.width and canvas.height cannot use any unit, because the canvas is being defined (error 3006).

Combining units

Units are part of a number, not a separate type, so they can be combined with arithmetic:

"x": "50% - 100"
"w": "90% - 2 * 40"
"size": "6vh"

% as the modulo operator

% as an operator needs operands on both sides (a % b), and after a number literal a space: 7 % 3, since 7%3 reads 7% as a percent unit. 50% directly after a number is the unit. See Operators.

Next

Names and references

↑↓ to moveEnter to openEsc to close