diff --git a/docs/commands/device-output/index.adoc b/docs/commands/device-output/index.adoc index fceb713..305c324 100644 --- a/docs/commands/device-output/index.adoc +++ b/docs/commands/device-output/index.adoc @@ -12,15 +12,21 @@ Commands for device output operations in PostScript. This category contains PostScript operators for device output. -== Status +== Commands -This category is ready for command documentation to be added. Commands in this category include operators from the PostScript Language Reference Manual. +[cols="1,3"] +|=== +| Command | Description -See other completed categories for documentation examples: -* link:/commands/references/[Path Construction] -* link:/commands/references/[Painting] -* link:/commands/references/[Transformations] -* link:/commands/references/[Font & Text] +| link:/commands/references/showpage/[`showpage`] +| Output the page and reinitialize graphics state (Level 1) + +| link:/commands/references/copypage/[`copypage`] +| Output the page without reinitializing graphics state (Level 1; page retention changes in Level 3) + +| link:/commands/references/nulldevice/[`nulldevice`] +| Discard graphical output (Level 1) +|=== == See Also diff --git a/docs/commands/font-text/index.adoc b/docs/commands/font-text/index.adoc index 43abadb..42e2235 100644 --- a/docs/commands/font-text/index.adoc +++ b/docs/commands/font-text/index.adoc @@ -66,6 +66,9 @@ PostScript provides comprehensive font and text capabilities including font sele | link:/commands/references/cshow/[`cshow`] | Show with per-character control (Level 2) + +| link:/commands/references/xyshow/[`xyshow`] +| Show with explicit x/y displacements (Level 2) |=== === Text Measurement diff --git a/docs/commands/index.adoc b/docs/commands/index.adoc index af0c7e6..f3f6418 100644 --- a/docs/commands/index.adoc +++ b/docs/commands/index.adoc @@ -31,6 +31,10 @@ link:/commands/references/[View all array/string commands →] link:/commands/references/[View all dictionary commands →] +=== Relational and Boolean + +link:/commands/relational-boolean/[View all relational and boolean commands →] + === Control Flow link:/commands/references/[View all control flow commands →] diff --git a/docs/commands/references/and.adoc b/docs/commands/references/and.adoc new file mode 100644 index 0000000..8fcef22 --- /dev/null +++ b/docs/commands/references/and.adoc @@ -0,0 +1,65 @@ +--- +layout: default +title: and +parent: Command Reference +nav_order: 7 +--- += and + +Compute logical or bitwise AND. + +== Description + +With two booleans, `and` returns true only when both operands are true. With two integers, it applies bitwise AND to their binary representations and returns an integer. + +Both operands must have the same type: boolean or integer. Reals and mixed boolean/integer operands cause `typecheck`. This consumes two already evaluated operands; it does not short-circuit execution. + +== Syntax + +[source,postscript] +---- +bool1 bool2 and bool3 +int1 int2 and int3 +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`bool1 bool2` or `int1 int2` + +|After +|`bool3` or `int3` +|=== + +== Examples + +[source,postscript] +---- +true false and % false +true true and % true +12 10 and % 8 (1100 AND 1010 = 1000) +---- + +== Related Commands + +* link:/commands/references/or/[`or`] - Logical and bitwise operation +* link:/commands/references/xor/[`xor`] - Logical and bitwise operation +* link:/commands/references/not/[`not`] - Logical and bitwise operation + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two booleans nor two integers. diff --git a/docs/commands/references/copypage.adoc b/docs/commands/references/copypage.adoc new file mode 100644 index 0000000..bf77b43 --- /dev/null +++ b/docs/commands/references/copypage.adoc @@ -0,0 +1,64 @@ +--- +layout: default +title: copypage +parent: Command Reference +nav_order: 2 +--- += copypage + +Output the current page without reinitializing the graphics state. + +== Description + +In Levels 1 and 2, `copypage` outputs the current page while retaining its marks and graphics state, so further drawing can be added to the same image. + +In Level 3, it behaves like `showpage` except that it does not reinitialize the graphics state: under normal page-device behavior, the page is output and erased. Do not rely on earlier marks remaining when running in Level 3. Page-device procedures can customize output behavior. + +== Syntax + +[source,postscript] +---- +- copypage - +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|No operands required + +|After +|Unchanged +|=== + +== Examples + +[source,postscript] +---- +/Helvetica findfont 12 scalefont setfont +72 720 moveto (Original) show +copypage +72 700 moveto (Additional line) show +showpage +% Levels 1/2: the second output contains both lines. +% Level 3: the second output contains only the additional line. +---- + +== Related Commands + +* link:/commands/references/showpage/[`showpage`] - Output and reinitialize the graphics state +* link:/commands/references/nulldevice/[`nulldevice`] - Discard graphical output + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`undefined`:: +In Level 2 and higher, copypage was called from a BeginPage or EndPage procedure. Errors from page-device procedures can also propagate. diff --git a/docs/commands/references/eq.adoc b/docs/commands/references/eq.adoc new file mode 100644 index 0000000..c712051 --- /dev/null +++ b/docs/commands/references/eq.adoc @@ -0,0 +1,69 @@ +--- +layout: default +title: eq +parent: Command Reference +nav_order: 1 +--- += eq + +Test two objects for equality. + +== Description + +Returns `true` when the two operands are equal, and `false` otherwise. + +Integers and reals compare by numeric value. Strings compare by their bytes, and names compare by their spelling; a name and a string with the same characters are equal. Other differing types are unequal, rather than causing `typecheck`. + +Arrays and dictionaries compare by shared object identity, not by matching contents. Literal/executable attributes do not affect equality. String contents must be readable. + +== Syntax + +[source,postscript] +---- +any1 any2 eq bool +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`any1 any2` + +|After +|`bool` +|=== + +== Examples + +[source,postscript] +---- +7 7.0 eq % true +(cat) (cat) eq % true +/cat /cat eq % true +/cat (cat) eq % true +7 (7) eq % false +[1 2] dup eq % true +[1 2] [1 2] eq % false +---- + +== Related Commands + +* link:/commands/references/ne/[`ne`] - Complementary equality test +* link:/commands/references/lt/[`lt`] - Ordered comparison + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`invalidaccess`:: +A string needed for comparison does not permit reading. + +`stackunderflow`:: +The operand stack contains fewer than two operands. diff --git a/docs/commands/references/false.adoc b/docs/commands/references/false.adoc new file mode 100644 index 0000000..b847fb8 --- /dev/null +++ b/docs/commands/references/false.adoc @@ -0,0 +1,61 @@ +--- +layout: default +title: "false" +parent: Command Reference +nav_order: 12 +--- += false + +Push the boolean value `false`. + +== Description + +Executing the name `false` pushes the boolean value `false` onto the operand stack. It takes no operands. Strictly speaking, this is a name in `systemdict` associated with a boolean object, rather than an operator. + +Booleans are distinct from integers: `true` is not the number 1, and `false` is not the number 0. Use booleans as conditions for `if` and `ifelse`. + +== Syntax + +[source,postscript] +---- +- false false +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|No operands required + +|After +|`false` +|=== + +== Examples + +[source,postscript] +---- +false type % booleantype +false not % true +false { (yes) } { (no) } ifelse % (no) +---- + +== Related Commands + +* link:/commands/references/true/[`true`] - The other boolean value +* link:/commands/references/not/[`not`] - Negate a boolean +* link:/commands/references/ifelse/[`ifelse`] - Select a branch + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`stackoverflow`:: +The operand stack has no room for another object. diff --git a/docs/commands/references/ge.adoc b/docs/commands/references/ge.adoc new file mode 100644 index 0000000..2d9a0ac --- /dev/null +++ b/docs/commands/references/ge.adoc @@ -0,0 +1,70 @@ +--- +layout: default +title: ge +parent: Command Reference +nav_order: 3 +--- += ge + +Test whether the first operand is greater than or equal to the second. + +== Description + +Returns a boolean indicating whether the first operand is greater than or equal to the second. Both operands must be numbers or both must be strings. Integers and reals may be mixed. + +Strings are ordered lexicographically by unsigned byte values, with the first differing byte deciding the order. If one string is a prefix of the other, the shorter string comes first. This is case-sensitive byte ordering, not locale-aware sorting. Names are not accepted, even though names can be compared with strings by `eq` and `ne`. + +== Syntax + +[source,postscript] +---- +num1 num2 ge bool +string1 string2 ge bool +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`num1 num2` or `string1 string2` + +|After +|`bool` +|=== + +== Examples + +[source,postscript] +---- +5 5.0 ge % true +(cat) (car) ge % true +2 3 ge % false +---- + +== Related Commands + +* link:/commands/references/eq/[`eq`] - Compare values +* link:/commands/references/ne/[`ne`] - Compare values +* link:/commands/references/gt/[`gt`] - Compare values +* link:/commands/references/le/[`le`] - Compare values +* link:/commands/references/lt/[`lt`] - Compare values + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`invalidaccess`:: +A string needed for comparison does not permit reading. + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two numbers nor two strings. diff --git a/docs/commands/references/gt.adoc b/docs/commands/references/gt.adoc new file mode 100644 index 0000000..5fd1a40 --- /dev/null +++ b/docs/commands/references/gt.adoc @@ -0,0 +1,70 @@ +--- +layout: default +title: gt +parent: Command Reference +nav_order: 4 +--- += gt + +Test whether the first operand is greater than the second. + +== Description + +Returns a boolean indicating whether the first operand is greater than the second. Both operands must be numbers or both must be strings. Integers and reals may be mixed. + +Strings are ordered lexicographically by unsigned byte values, with the first differing byte deciding the order. If one string is a prefix of the other, the shorter string comes first. This is case-sensitive byte ordering, not locale-aware sorting. Names are not accepted, even though names can be compared with strings by `eq` and `ne`. + +== Syntax + +[source,postscript] +---- +num1 num2 gt bool +string1 string2 gt bool +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`num1 num2` or `string1 string2` + +|After +|`bool` +|=== + +== Examples + +[source,postscript] +---- +6 5.0 gt % true +(cat) (car) gt % true +5 5 gt % false +---- + +== Related Commands + +* link:/commands/references/eq/[`eq`] - Compare values +* link:/commands/references/ne/[`ne`] - Compare values +* link:/commands/references/ge/[`ge`] - Compare values +* link:/commands/references/le/[`le`] - Compare values +* link:/commands/references/lt/[`lt`] - Compare values + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`invalidaccess`:: +A string needed for comparison does not permit reading. + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two numbers nor two strings. diff --git a/docs/commands/references/le.adoc b/docs/commands/references/le.adoc new file mode 100644 index 0000000..a1545c4 --- /dev/null +++ b/docs/commands/references/le.adoc @@ -0,0 +1,70 @@ +--- +layout: default +title: le +parent: Command Reference +nav_order: 5 +--- += le + +Test whether the first operand is less than or equal to the second. + +== Description + +Returns a boolean indicating whether the first operand is less than or equal to the second. Both operands must be numbers or both must be strings. Integers and reals may be mixed. + +Strings are ordered lexicographically by unsigned byte values, with the first differing byte deciding the order. If one string is a prefix of the other, the shorter string comes first. This is case-sensitive byte ordering, not locale-aware sorting. Names are not accepted, even though names can be compared with strings by `eq` and `ne`. + +== Syntax + +[source,postscript] +---- +num1 num2 le bool +string1 string2 le bool +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`num1 num2` or `string1 string2` + +|After +|`bool` +|=== + +== Examples + +[source,postscript] +---- +5 5.0 le % true +(car) (cat) le % true +3 2 le % false +---- + +== Related Commands + +* link:/commands/references/eq/[`eq`] - Compare values +* link:/commands/references/ne/[`ne`] - Compare values +* link:/commands/references/ge/[`ge`] - Compare values +* link:/commands/references/gt/[`gt`] - Compare values +* link:/commands/references/lt/[`lt`] - Compare values + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`invalidaccess`:: +A string needed for comparison does not permit reading. + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two numbers nor two strings. diff --git a/docs/commands/references/lt.adoc b/docs/commands/references/lt.adoc new file mode 100644 index 0000000..be1378f --- /dev/null +++ b/docs/commands/references/lt.adoc @@ -0,0 +1,70 @@ +--- +layout: default +title: lt +parent: Command Reference +nav_order: 6 +--- += lt + +Test whether the first operand is less than the second. + +== Description + +Returns a boolean indicating whether the first operand is less than the second. Both operands must be numbers or both must be strings. Integers and reals may be mixed. + +Strings are ordered lexicographically by unsigned byte values, with the first differing byte deciding the order. If one string is a prefix of the other, the shorter string comes first. This is case-sensitive byte ordering, not locale-aware sorting. Names are not accepted, even though names can be compared with strings by `eq` and `ne`. + +== Syntax + +[source,postscript] +---- +num1 num2 lt bool +string1 string2 lt bool +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`num1 num2` or `string1 string2` + +|After +|`bool` +|=== + +== Examples + +[source,postscript] +---- +4 5.0 lt % true +(a) (ab) lt % true +5 5 lt % false +---- + +== Related Commands + +* link:/commands/references/eq/[`eq`] - Compare values +* link:/commands/references/ne/[`ne`] - Compare values +* link:/commands/references/ge/[`ge`] - Compare values +* link:/commands/references/gt/[`gt`] - Compare values +* link:/commands/references/le/[`le`] - Compare values + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`invalidaccess`:: +A string needed for comparison does not permit reading. + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two numbers nor two strings. diff --git a/docs/commands/references/ne.adoc b/docs/commands/references/ne.adoc new file mode 100644 index 0000000..200acbf --- /dev/null +++ b/docs/commands/references/ne.adoc @@ -0,0 +1,69 @@ +--- +layout: default +title: ne +parent: Command Reference +nav_order: 2 +--- += ne + +Test two objects for inequality. + +== Description + +Returns `true` when the two operands are unequal, and `false` otherwise. + +Integers and reals compare by numeric value. Strings compare by their bytes, and names compare by their spelling; a name and a string with the same characters are equal. Other differing types are unequal, rather than causing `typecheck`. + +Arrays and dictionaries compare by shared object identity, not by matching contents. Literal/executable attributes do not affect equality. String contents must be readable. + +== Syntax + +[source,postscript] +---- +any1 any2 ne bool +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`any1 any2` + +|After +|`bool` +|=== + +== Examples + +[source,postscript] +---- +7 7.0 ne % false +(cat) (cat) ne % false +/cat /cat ne % false +/cat (cat) ne % false +7 (7) ne % true +[1 2] dup ne % false +[1 2] [1 2] ne % true +---- + +== Related Commands + +* link:/commands/references/eq/[`eq`] - Complementary equality test +* link:/commands/references/lt/[`lt`] - Ordered comparison + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`invalidaccess`:: +A string needed for comparison does not permit reading. + +`stackunderflow`:: +The operand stack contains fewer than two operands. diff --git a/docs/commands/references/not.adoc b/docs/commands/references/not.adoc new file mode 100644 index 0000000..fad8a0f --- /dev/null +++ b/docs/commands/references/not.adoc @@ -0,0 +1,64 @@ +--- +layout: default +title: not +parent: Command Reference +nav_order: 10 +--- += not + +Negate a boolean or complement the bits of an integer. + +== Description + +For a boolean, `not` exchanges `true` and `false`. For an integer, it inverts every bit, including the sign bit, rather than performing arithmetic negation. In two's-complement representation the result is `-int1 - 1`. Reals are not accepted. + +== Syntax + +[source,postscript] +---- +bool1 not bool2 +int1 not int2 +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`bool1` or `int1` + +|After +|`bool2` or `int2` +|=== + +== Examples + +[source,postscript] +---- +true not % false +false not % true +0 not % -1 +5 not % -6 +---- + +== Related Commands + +* link:/commands/references/and/[`and`] - Logical and bitwise operation +* link:/commands/references/or/[`or`] - Logical and bitwise operation +* link:/commands/references/xor/[`xor`] - Logical and bitwise operation + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`stackunderflow`:: +The operand stack is empty. + +`typecheck`:: +The operand is neither a boolean nor an integer. diff --git a/docs/commands/references/nulldevice.adoc b/docs/commands/references/nulldevice.adoc new file mode 100644 index 0000000..4fc4da4 --- /dev/null +++ b/docs/commands/references/nulldevice.adoc @@ -0,0 +1,64 @@ +--- +layout: default +title: nulldevice +parent: Command Reference +nav_order: 3 +--- += nulldevice + +Install an output device that discards graphical marks. + +== Description + +`nulldevice` selects a device with no physical output or raster storage. Drawing and font operations still execute, but their marks are discarded; `showpage` and `copypage` produce no output. + +The null device has an identity default transformation matrix and a degenerate clipping path at the origin. Bracket its use with `gsave` and `grestore` to restore the previous device and graphics state. It is useful for exercising graphics or font operations without producing a page. + +== Syntax + +[source,postscript] +---- +- nulldevice - +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|No operands required + +|After +|Unchanged +|=== + +== Examples + +[source,postscript] +---- +gsave + nulldevice + /Helvetica findfont 12 scalefont setfont + 0 0 moveto (Measure without output) show + currentpoint % Leaves the final x and y coordinates +grestore +---- + +== Related Commands + +* link:/commands/references/showpage/[`showpage`] - Output a page +* link:/commands/references/copypage/[`copypage`] - Copy a page +* link:/commands/references/gsave/[`gsave`] - Save the graphics state +* link:/commands/references/grestore/[`grestore`] - Restore the previous graphics state + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +None specified for this operator. diff --git a/docs/commands/references/or.adoc b/docs/commands/references/or.adoc new file mode 100644 index 0000000..c0dd37d --- /dev/null +++ b/docs/commands/references/or.adoc @@ -0,0 +1,65 @@ +--- +layout: default +title: or +parent: Command Reference +nav_order: 8 +--- += or + +Compute logical or bitwise inclusive OR. + +== Description + +With two booleans, `or` returns true when at least one operand is true. With two integers, it applies bitwise inclusive OR to their binary representations and returns an integer. + +Both operands must have the same type: boolean or integer. Reals and mixed boolean/integer operands cause `typecheck`. This consumes two already evaluated operands; it does not short-circuit execution. + +== Syntax + +[source,postscript] +---- +bool1 bool2 or bool3 +int1 int2 or int3 +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`bool1 bool2` or `int1 int2` + +|After +|`bool3` or `int3` +|=== + +== Examples + +[source,postscript] +---- +true false or % true +false false or % false +12 10 or % 14 (1100 OR 1010 = 1110) +---- + +== Related Commands + +* link:/commands/references/and/[`and`] - Logical and bitwise operation +* link:/commands/references/xor/[`xor`] - Logical and bitwise operation +* link:/commands/references/not/[`not`] - Logical and bitwise operation + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two booleans nor two integers. diff --git a/docs/commands/references/showpage.adoc b/docs/commands/references/showpage.adoc new file mode 100644 index 0000000..6775da7 --- /dev/null +++ b/docs/commands/references/showpage.adoc @@ -0,0 +1,64 @@ +--- +layout: default +title: showpage +parent: Command Reference +nav_order: 1 +--- += showpage + +Output the current page and prepare the next page. + +== Description + +With the normal page-device procedures, `showpage` sends the accumulated marks to the output device, clears the page, and reinitializes the graphics state. Establish the font, current point, and other graphics settings again for the next page. It does not clear the operand or dictionary stacks. + +In Level 2 and higher, the page device's `EndPage` procedure controls whether the page is output and erased. Graphics initialization and `BeginPage` then prepare the next page. Device configuration controls such details as copies and media. + +== Syntax + +[source,postscript] +---- +- showpage - +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|No operands required + +|After +|Unchanged +|=== + +== Examples + +[source,postscript] +---- +/Helvetica findfont 12 scalefont setfont +72 720 moveto (First page) show +showpage + +/Helvetica findfont 12 scalefont setfont +72 720 moveto (Second page) show +showpage +---- + +== Related Commands + +* link:/commands/references/copypage/[`copypage`] - Output without reinitializing the graphics state +* link:/commands/references/nulldevice/[`nulldevice`] - Discard graphical output + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`undefined`:: +In Level 2 and higher, showpage was called from a BeginPage or EndPage procedure. Errors from page-device procedures can also propagate. diff --git a/docs/commands/references/true.adoc b/docs/commands/references/true.adoc new file mode 100644 index 0000000..fcf3536 --- /dev/null +++ b/docs/commands/references/true.adoc @@ -0,0 +1,61 @@ +--- +layout: default +title: "true" +parent: Command Reference +nav_order: 11 +--- += true + +Push the boolean value `true`. + +== Description + +Executing the name `true` pushes the boolean value `true` onto the operand stack. It takes no operands. Strictly speaking, this is a name in `systemdict` associated with a boolean object, rather than an operator. + +Booleans are distinct from integers: `true` is not the number 1, and `false` is not the number 0. Use booleans as conditions for `if` and `ifelse`. + +== Syntax + +[source,postscript] +---- +- true true +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|No operands required + +|After +|`true` +|=== + +== Examples + +[source,postscript] +---- +true type % booleantype +true not % false +true { (yes) } { (no) } ifelse % (yes) +---- + +== Related Commands + +* link:/commands/references/false/[`false`] - The other boolean value +* link:/commands/references/not/[`not`] - Negate a boolean +* link:/commands/references/ifelse/[`ifelse`] - Select a branch + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`stackoverflow`:: +The operand stack has no room for another object. diff --git a/docs/commands/references/xor.adoc b/docs/commands/references/xor.adoc new file mode 100644 index 0000000..7a8ffde --- /dev/null +++ b/docs/commands/references/xor.adoc @@ -0,0 +1,65 @@ +--- +layout: default +title: xor +parent: Command Reference +nav_order: 9 +--- += xor + +Compute logical or bitwise exclusive OR. + +== Description + +With two booleans, `xor` returns true when exactly one operand is true. With two integers, it applies bitwise exclusive OR to their binary representations and returns an integer. + +Both operands must have the same type: boolean or integer. Reals and mixed boolean/integer operands cause `typecheck`. This consumes two already evaluated operands; it does not short-circuit execution. + +== Syntax + +[source,postscript] +---- +bool1 bool2 xor bool3 +int1 int2 xor int3 +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`bool1 bool2` or `int1 int2` + +|After +|`bool3` or `int3` +|=== + +== Examples + +[source,postscript] +---- +true false xor % true +true true xor % false +12 10 xor % 6 (1100 XOR 1010 = 0110) +---- + +== Related Commands + +* link:/commands/references/and/[`and`] - Logical and bitwise operation +* link:/commands/references/or/[`or`] - Logical and bitwise operation +* link:/commands/references/not/[`not`] - Logical and bitwise operation + +== PostScript Level + +*Available in*: PostScript Level 1 and higher (LanguageLevel 1). + +== Error Conditions + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +Operands are neither two booleans nor two integers. diff --git a/docs/commands/references/xyshow.adoc b/docs/commands/references/xyshow.adoc new file mode 100644 index 0000000..99d31e6 --- /dev/null +++ b/docs/commands/references/xyshow.adoc @@ -0,0 +1,80 @@ +--- +layout: default +title: xyshow +parent: Command Reference +nav_order: 14 +--- += xyshow + +Paint text using explicit horizontal and vertical displacements. + +== Description + +`xyshow` paints the string using the current font and current point. For each character rendered, it consumes an x/y pair from a numeric array or an encoded number string. The pair specifies the displacement in user space from that character's origin to the next origin, replacing the normal character width rather than adding to it. + +Supply a pair for every character, including the last: the last pair sets the final current point. With composite fonts, count characters selected by font mapping, which need not equal the number of bytes in the string. Extra displacement values are ignored. A numeric array must contain numbers; an encoded number string uses the binary numeric representation described under Encoded Number Strings in the PLRM, not ordinary text such as `(12 0)`. + +== Syntax + +[source,postscript] +---- +string numarray xyshow - +string numstring xyshow - +---- + +=== Stack Effect + +Stack entries are shown from bottom to top; earlier operands are unchanged. + +[cols="1,3"] +|=== +|State |Operand stack + +|Before +|`string numarray` or `string numstring` + +|After +|Both operands removed; no result +|=== + +== Examples + +[source,postscript] +---- +/Helvetica findfont 12 scalefont setfont +100 700 moveto +(ABC) [14 2 14 -2 14 0] xyshow +currentpoint % 142 700: includes the displacement after C +---- + +== Related Commands + +* link:/commands/references/show/[`show`] - Paint text using normal character widths +* link:/commands/references/ashow/[`ashow`] - Add a uniform displacement to character widths +* link:/commands/references/stringwidth/[`stringwidth`] - Measure normal text displacement + +== PostScript Level + +*Available in*: PostScript Level 2 and higher (LanguageLevel 2). + +Introduced in Level 2; see the PostScript Language Reference Manual, third edition, Appendix A. + +== Error Conditions + +`invalidaccess`:: +The text or displacement data does not permit reading. + +`invalidfont`:: +The current font is invalid. + +`nocurrentpoint`:: +No current point has been established. + +`rangecheck`:: +There are too few displacement values, an encoded number string is malformed, or character mapping exceeds its bounds. + +`stackunderflow`:: +The operand stack contains fewer than two operands. + +`typecheck`:: +The first operand is not a string, the second is not a numeric array or encoded number string, or an array entry is not a number. diff --git a/docs/commands/relational-boolean/index.adoc b/docs/commands/relational-boolean/index.adoc new file mode 100644 index 0000000..083cbde --- /dev/null +++ b/docs/commands/relational-boolean/index.adoc @@ -0,0 +1,61 @@ +--- +layout: default +title: Relational and Boolean +parent: Commands +nav_order: 4.5 +--- + +== Relational and Boolean + +Commands for comparing objects and performing logical and bitwise operations. + +== Overview + +Equality operators compare objects, ordered comparisons accept numbers or strings, and logical operators also support bitwise operations on integers. All commands in this category are available in PostScript Level 1 and higher. + +== Commands + +[cols="1,3"] +|=== +| Command | Description + +| link:/commands/references/eq/[`eq`] +| Test two objects for equality. + +| link:/commands/references/ne/[`ne`] +| Test two objects for inequality. + +| link:/commands/references/ge/[`ge`] +| Test whether the first operand is greater than or equal to the second. + +| link:/commands/references/gt/[`gt`] +| Test whether the first operand is greater than the second. + +| link:/commands/references/le/[`le`] +| Test whether the first operand is less than or equal to the second. + +| link:/commands/references/lt/[`lt`] +| Test whether the first operand is less than the second. + +| link:/commands/references/and/[`and`] +| Compute logical or bitwise AND. + +| link:/commands/references/or/[`or`] +| Compute logical or bitwise inclusive OR. + +| link:/commands/references/xor/[`xor`] +| Compute logical or bitwise exclusive OR. + +| link:/commands/references/not/[`not`] +| Negate a boolean or complement the bits of an integer. + +| link:/commands/references/true/[`true`] +| Push the boolean value `true`. + +| link:/commands/references/false/[`false`] +| Push the boolean value `false`. +|=== + +== See Also + +* link:/commands/[Command Reference Overview]