postsvg 0.1.0

data/docs/postscript/operators/control-flow.adoc

@@ -0,0 +1,230 @@
+= Control Flow Operators
+
+== General
+
+Control flow operators enable conditional execution, loops, and procedure
+execution in PostScript programs. These operators use procedures (executable
+arrays enclosed in curly braces) to define code blocks.
+
+[[if]]
+== if
+
+=== General
+
+The `if` operator executes a procedure if a boolean condition is true.
+
+=== Syntax
+
+[source,postscript]
+----
+bool {procedure} if <1> <2> <3>
+----
+<1> Boolean value (true or false)
+<2> Procedure to execute if true
+<3> Operator that conditionally executes
+
+Where,
+
+`bool`:: Boolean value (true or false)
+`procedure`:: Code to execute if bool is true
+
+Stack effect: `bool proc -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+5 3 gt {               % If 5 > 3
+  (5 is greater) show
+} if
+----
+
+Executes procedure only when condition is true.
+====
+
+[[ifelse]]
+== ifelse
+
+=== General
+
+The `ifelse` operator executes one procedure if true, another if false.
+
+=== Syntax
+
+[source,postscript]
+----
+bool {proc1} {proc2} ifelse <1> <2> <3> <4>
+----
+<1> Boolean condition
+<2> Procedure for true case
+<3> Procedure for false case
+<4> Operator that branches
+
+Where,
+
+`bool`:: Boolean value
+`proc1`:: Execute if true
+`proc2`:: Execute if false
+
+Stack effect: `bool proc1 proc2 -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+x 0 lt {
+  x neg              % Absolute value
+} {
+  x
+} ifelse
+----
+
+Conditional branching.
+====
+
+[[for]]
+== for
+
+=== General
+
+The `for` operator executes a procedure for each value in a numeric range.
+
+=== Syntax
+
+[source,postscript]
+----
+initial increment limit {procedure} for <1> <2> <3> <4> <5>
+----
+<1> Starting value
+<2> Increment value
+<3> Ending value (inclusive)
+<4> Procedure to execute
+<5> Loop operator
+
+Where,
+
+`initial`:: Starting value (number)
+`increment`:: Step size (number)
+`limit`:: Ending value (number)
+`procedure`:: Code to execute (receives current value)
+
+Stack effect: `init incr limit proc -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+1 1 10 {             % Loop from 1 to 10, step 1
+  dup mul            % Square each number
+  = % Print
+} for
+----
+
+Prints squares 1, 4, 9, ..., 100.
+====
+
+[[repeat]]
+== repeat
+
+=== General
+
+The `repeat` operator executes a procedure a specified number of times.
+
+=== Syntax
+
+[source,postscript]
+----
+n {procedure} repeat <1> <2> <3>
+----
+<1> Number of iterations
+<2> Procedure to execute
+<3> Repeat operator
+
+Where,
+
+`n`:: Number of times to execute (integer)
+`procedure`:: Code to execute
+
+Stack effect: `n proc -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+5 {
+  (Hello) show
+} repeat
+----
+
+Executes procedure 5 times.
+====
+
+[[loop]]
+== loop
+
+=== General
+
+The `loop` operator executes a procedure indefinitely until `exit` is called.
+
+=== Syntax
+
+[source,postscript]
+----
+{procedure} loop <1> <2>
+----
+<1> Procedure to execute repeatedly
+<2> Loop operator
+
+Where,
+
+`procedure`:: Code to execute (must contain `exit` to terminate)
+
+Stack effect: `proc -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+0             % Counter
+{
+  dup 10 ge {exit} if  % Exit when >= 10
+  1 add                % Increment
+} loop
+----
+
+Infinite loop with exit condition.
+====
+
+[[exit]]
+== exit
+
+=== General
+
+The `exit` operator terminates the innermost enclosing loop (`for`, `repeat`,
+or `loop`).
+
+=== Syntax
+
+[source,postscript]
+----
+exit <1>
+----
+<1> Exit from loop
+
+Stack effect: `-- `
+
+== See Also
+
+* link:../fundamentals.adoc#execution-model[Execution Model]
+* link:dictionary.adoc[Dictionary Operators]
+* link:index.adoc[Back to Operator Reference]

data/docs/postscript/operators/dictionary.adoc

@@ -0,0 +1,191 @@
+= Dictionary Operators
+
+== General
+
+Dictionary operators manage PostScript dictionaries, which are associative
+arrays that map keys to values. Dictionaries implement variable storage and
+scoping in PostScript.
+
+[[def]]
+== def
+
+=== General
+
+The `def` operator defines a key-value pair in the current dictionary (the
+topmost dictionary on the dictionary stack).
+
+=== Syntax
+
+[source,postscript]
+----
+key value def <1> <2> <3>
+----
+<1> Key (typically a literal name)
+<2> Value (any PostScript object)
+<3> Operator that stores the association
+
+Where,
+
+`key`:: Key for the entry (typically a name)
+`value`:: Value to associate with the key
+
+Stack effect: `key value -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+/x 100 def             % Define x = 100
+/mycolor [1 0 0] def   % Define color array
+----
+
+Creates variables in the current dictionary.
+====
+
+[[dict]]
+== dict
+
+=== General
+
+The `dict` operator creates a new dictionary with space for n key-value pairs.
+
+=== Syntax
+
+[source,postscript]
+----
+int dict <1> <2>
+----
+<1> Initial capacity (number of entries)
+<2> Operator that creates dictionary
+
+Where,
+
+`int`:: Initial capacity (integer)
+
+Stack effect: `int -- dict`
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+20 dict                % Create dictionary for 20 entries
+----
+
+The dictionary grows automatically if needed.
+====
+
+[[begin]]
+== begin
+
+=== General
+
+The `begin` operator pushes a dictionary onto the dictionary stack, making it
+the current dictionary for name lookups and `def` operations.
+
+=== Syntax
+
+[source,postscript]
+----
+dict begin <1> <2>
+----
+<1> Dictionary to activate
+<2> Operator that pushes dictionary
+
+Where,
+
+`dict`:: Dictionary to make current
+
+Stack effect: `dict -- `
+
+=== Examples
+
+[example]
+====
+[source,postscript]
+----
+10 dict begin          % Create and activate new scope
+  /x 5 def             % Define in local dictionary
+  /y 10 def
+  x y add              % Use local variables
+end                    % Exit scope
+----
+
+Creates a local variable scope.
+====
+
+[[end]]
+== end
+
+=== General
+
+The `end` operator pops the topmost dictionary from the dictionary stack,
+ending the current scope.
+
+=== Syntax
+
+[source,postscript]
+----
+end <1>
+----
+<1> Operator that pops dictionary
+
+Stack effect: `-- `
+
+=== Examples
+
+See `begin` example above.
+
+== Dictionary Usage Patterns
+
+=== Local variables
+
+[example]
+====
+[source,postscript]
+----
+% Define a procedure with local variables
+/myproc {
+  10 dict begin        % Local scope
+    /a exch def        % Store parameters
+    /b exch def
+    a b add            % Use locals
+  end                  % Clean up scope
+} def
+
+% Call with arguments
+5 3 myproc             % Returns 8
+----
+
+Procedures often use local dictionaries for parameters.
+====
+
+=== Configuration dictionaries
+
+[example]
+====
+[source,postscript]
+----
+% Create configuration
+/config 5 dict def
+config begin
+  /width 100 def
+  /height 200 def
+  /color [1 0 0] def
+end
+
+% Use configuration
+config /width get      % Retrieve width
+----
+
+Dictionaries as data structures.
+====
+
+== See Also
+
+* link:../fundamentals.adoc#dictionaries-and-scopes[Dictionaries and Scopes]
+* link:control-flow.adoc[Control Flow]
+* link:index.adoc[Back to Operator Reference]