The ChoiceLink is a kind of Link used during pattern matching, to indicate that any one of several different terms need to be grounded. The ChoiceLink presents a menu of choices or possibilities. For specifying a choice of types, use the TypeChoice link.
The ChoiceLink is NOT a boolean operator. It does NOT examine the truth value of the atoms presented as choices! However, the ChoiceLink does evaluate to a boolean value: it can be either true or false, depending on whether any of its sub-graphs can be found in the AtomSpace. Thus, for example,
ChoiceLink Atom A Atom B Atom C
means the same thing as
OrLink PresentLink Atom A PresentLink Atom B PresentLink Atom C
Caution: At this time, PresentLink is incompletely implemented, and the above combination of PresentLink and OrLink does not work. If this is what you want to do, use ChoiceLink instead!
By default, the pattern matcher will exhaustively explore all grounding possibilities: thus, at some point during the search, it will check for the presence of A AND for B AND for C. This does not mean that choice is kind-of-like boolean-AND; it not. Neither is it some kind of boolean-OR. It merely presents a menu of items from which a selection can be made. The items themselves are atoms; the truth-values associated with the atoms are ignored.
Thus for example, the following pattern
AndLink ChoiceLink InheritanceLink VariableNode $x ConceptNode "monkey" InheritanceLink VariableNode $x ConceptNode "mushroom" ChoiceLink InheritanceLink VariableNode $x ConceptNode "six toes" InheritanceLink VariableNode $x ConceptNode "mycelium"
states that $x, whatever it is, is either a monkey or a mushroom, and that it also has either six toes or a mycleium. ChoiceLinks may be nested with AndLinks to form arbitrarily complex pattern-matching expressions.
Note that ChoiceLinks do NOT bind their variables: the four notations $x in the example above all refer to the same variable. That is, the variable declaration "leaks out" of the ChoiceLink; the variable $x is free.
A ChoiceLink with just a single subterm effectively tests whether that term is present or absent in the atomspace. Thus, ChoiceLinks are related to PresentLink: when these have only one argument, they are identical. For multiple arguments they are related in the same way that or is related to and: only one term in a ChoiceLink needs to be grounded, whereas all of the terms in a PresentLink must be grounded.
Thus, for example,
AndLink ChoiceLink Atom A ChoiceLink Atom B
is the same as
PresentLink Atom A Atom B
At this time, it is not advisable to combine ChoiceLink with NotLink, probably because it does not work in the current atomspace implementation. That is, in principle, the expression
NotLink ChoiceLink Atom A
should be identical to the expression
AbsentLink Atom A
ChoiceLinks were implemented in early 2015, and they work well; they are tested by ChoiceLinkUTest.