dictionary

A dictionary associates keys to values.

By default, dictionaries are persistent, retaining their values across games.

Dictionary entries

Formally, a dictionary is a collection of dictionary entries, each of which is a pair of permitted values. A permitted value is either a string, a number, position, or a set of squares. The first element in each dictionary entry is called the key of that entry. The second element in each dictionary entry is called the value of that entry. No two entries in the dictionary share a key.

A dictionary can have only a single type of key and only a single type of value, although the types of keys and value can be different.

A dictionary is defined by preceding its name, which is a variable, with the keyword dictionary.

persistence of dictionaries

A dictionary is persistent by default retaining its value across games, and so any use of such a dictionary will force CQL to be single-threaded.

local (non-persistent) dictionaries

If the first use of the dictionary is preceded by the keyword local the dictionary is local. A local dictionary is not persistent: it is cleared before each new game is read.

	local dictionary D

The example file followpath.cql illustrates the use of local dictionaries.

Only local dictionaries can have keys or values that are positions. If you want to store positions in a persistent dictionary, use the FEN of the dictionary or some other characteristic of the position.

examples

Suppose D is a dictionary. The value of the entry in D with key key is D[key].

      dictionary D
      D["hello"]="goodbye"
      D["up"]="down"
      "goodbye" == D["hello"]
      "down" == D ["up"]
      D["fail"] // this filter will fail to match

If dictionary D has no entry with key key then D[_key_] will fail to match; otherwise the expression will match.

Dictionary values can be assigned using the syntax in the example above.

Dictionaries cannot currently be used as the actual argument to a function or returned as the value of a filter. Thus, whenever a dictionary is used, its actual name, as a variable, must be used.

counting elements of a dictionary

If D is the name of a dictionary, then #D is the number of entries in the dictionary:

  dictionary Dict
  #Dict==0
  Dict[a3]="knight"
  #Dict==1

iterating through a dictionary

Simple looping through the keys of a dictionary can be done using this syntax:

      key ∊ dictionary body

where key is a variable; dictionary is the name of a dictionary; and body is any filter:

      dictionary E["1"]=="2"
      dictionary E["No"]=="yes"
      K∊E
       message
        ("E[K]: " E[K])

This syntax works with any allowed type:

      dictionary F[ a2 ]= 45
      F[ b1-8 ] = 4
      R∊F
        message ("F[R]: " F[R])

Note that the a2 is surrounded by spaces when enclosed in brackets. This is because the symbol

      [a2]

is interpreted as a piece designator representing the square a2 rather than an index into a dictionary. (Likewise, [x] is interpreted as × , so be careful when using a variable named x as an index into a dictionary.)

clearing entries in a dictionary

To delete an entry with key key in a dictionary D, use this syntax:

      unbind D[key]

This form of unbind always matches the position unless the key filter fails to match the position. To delete all entries in a dictionary D, use

      unbind D

This form of unbind always matches the current position.

    dictionary D
    D["check"]="mate"
    D["back"]="rank"
    #D==2
    unbind D["check"]
    not D["check"]
    #D==1
    unbind D
    #D==0

Examples of use of dictionary

Suppose we want to find pairs of games sharing the same initial position:

      cql(input "hhdbvi.pgn")
      dictionary InitialD
      initial
      if InitialD[fen]~~"gamenumber: (\d+)"
        comment ("Position already seen at game number: " \1)
      else
        InitialD[fen]=str("gamenumber: " gamenumber)

More sophisticated matching can also be done, like searching to see if any position in the current study occurred earlier, and so on.

Dictionaries are often useful with readfile and writefile. Typically, a file will be written encoding information about fens of games, and then fed into a dictionary with readfile.

summarizing dictionary contents at the end of processing

Note: CQL currently lacks a good way to iterate through a dictionary in the last position of the last game, which is sometimes useful if the dictionary is summarizing some computation.

One way to do this, although cumbersome is as follows.

First, note that to check if the current position is the last position evaluated in the current game, use either terminal or position

      terminal // if variations not set
      not position (positionid + 1) // if variations set

But there is no way to check if the current game is last game in the current pgn file in CQL; you must manually find it. CQL always outputs the total number of games in a file, so cql must be run once to get the last game number, e.g. using

      cql -i filename.pgn -cql false

Suppose there are 93839 games. Then, if variations is not set, use

  cql (input filename.pgn)
  dictionary D
  ...
  if terminal and gamenumber==93839
   message ("Number of entries in D: " #D)
  

Technically one can use ~~ together with readfile to parse the input pgn file and count the games, for instance by counting the occurrence of the regex \[White and also the name of the input .pgn file as an argument using -assign, but that would likely not be any easier).