1. Dictionary Operations

Dictionary operations provide PostScript’s primary mechanism for associating keys with values. Dictionaries serve as namespaces, configuration stores, and the foundation for the language’s scoping and name lookup mechanisms.

2. Overview

Dictionaries in PostScript are:

  • Key-value stores: Associate arbitrary keys (typically names) with values

  • Scoped namespaces: Organized in a dictionary stack for hierarchical lookup

  • Dynamic: Can grow beyond initial capacity (Level 2)

  • Fundamental: Used for variable storage, procedure definitions, and system configuration

3. Dictionary Stack

PostScript maintains a dictionary stack that controls name lookup:

  • Top dictionary is searched first (current dictionary)

  • Search proceeds down the stack until name is found

  • Standard dictionaries: systemdict, globaldict (Level 2), userdict

  • User dictionaries can be pushed/popped with begin / end

4. Command Categories

4.1. Dictionary Creation

Command Description

dict

Create new dictionary with initial capacity

4.2. Dictionary Stack Operations

Command Description

begin

Push dictionary onto dictionary stack

end

Pop dictionary from dictionary stack

currentdict

Get current dictionary (top of stack)

countdictstack

Count dictionaries on stack

dictstack

Copy dictionary stack to array

4.3. Dictionary Content Operations

Command Description

def

Define key-value pair in current dictionary

load

Look up and return value from dictionary stack

store

Store value in dictionary stack (create if needed)

known

Check if key exists in specific dictionary

where

Find which dictionary contains key

undef

Remove key from dictionary (Level 2)

4.4. Dictionary Inspection

Command Description

maxlength

Get maximum capacity

length

Get current number of entries

get

Get value for specific key

put

Put key-value pair

forall

Iterate over all key-value pairs

5. Common Patterns

5.1. Creating and Using Dictionaries 

% Create a dictionary with initial capacity
5 dict begin
  /width 100 def
  /height 200 def
  /color /red def
end

% Use the dictionary
currentdict /width get  % Returns 100

5.2. Dictionary as Configuration 

/config 10 dict def
config begin
  /fontSize 12 def
  /fontName /Helvetica def
  /lineHeight 14 def
end

% Access configuration
config /fontSize get

5.3. Name Lookup 

% Define in current dictionary
/myvar 42 def

% Find which dictionary contains it
/myvar where {
  % Found - dictionary is on stack
  /myvar get  % Get the value
} {
  % Not found
  /myvar load  % Will cause undefined error
} ifelse

6. Important Considerations

6.1. Dictionary Stack Hierarchy

The standard dictionary stack (bottom to top):

  1. systemdict - Read-only system definitions

  2. globaldict - Global definitions (Level 2)

  3. userdict - User definitions

  4. User-created dictionaries (via begin)

6.2. Level 1 vs. Level 2 Differences

Level 1: * Fixed capacity - [dictfull] error if exceeded * Must specify sufficient size at creation * No global VM concept

Level 2: * Auto-expanding - grows beyond initial capacity * Initial size is optimization hint * Global vs. local VM distinctions

6.3. VM Allocation

  • Dictionaries allocated in local or global VM based on allocation mode

  • Global VM dictionaries persist across jobs

  • Cannot store local VM objects in global VM dictionaries

6.4. Access Control

  • Dictionaries can be made readonly

  • Readonly dictionaries cannot have entries added/modified

  • No-access prevents reading contents

7. Common Pitfalls

Dictionary Stack Balance - Every begin must have matching end. Unbalanced stacks cause [dictstackunderflow] or [dictstackoverflow].
Fixed Capacity (Level 1) - In Level 1, exceeding dictionary capacity causes [dictfull] error. Always allocate sufficient space.
Global/Local VM - Cannot store local VM objects into global VM dictionaries - causes [invalidaccess].
Use begin/end Blocks - Bracket dictionary use with begin/end for scoped access: 
mydict begin
  % Definitions go into mydict
  /key value def
end

8. See Also