Main Data Type for representing programs working on an AtomSpace.

Note that AtomSpace is an instance of the type class: MonadIO

(We have to use the IO monad because of the use of FFI for calling c functions for working on a mutable instance of the atomspace, so we have side effects).

So, you can lift IO actions inside the monad AtomSpace, through the use of liftIO.

AtomSpaceObj is a specific AtomSpace instance.

getParent given an AtomSpace instance returns the parent AtomSpace.

newAtomSpace creates a new Atomspace, from a optionally given parent atomspace.

onAtomSpace runs the specified computation on the atomspace instance provided.

Syntactic sugar for calling the function onAtomSpace. For example, we can write code like this:

main :: IO ()
main = do
   parentAS <- newAtomSpace Nothing
   childAS <- newAtomSpace (Just parentAS)

   parentAS <: insert (ConceptNode GenConcept noTv)
   childAS  <: do
       insert (ConceptNode PrivateConcept1 (stv 1 1))
       insert (ConceptNode PrivateConcept2 (stv 0.5 1))
   parentAS <: program
   childAS  <: debug
   parentAS <: remove (ConceptNode GenConcept noTv)

program :: AtomSpace ()
program = do
    s <- get (ConceptNode GenConcept noTv)
    ...

runOnNewAtomSpace creates a new AtomSpace (C++ object) and does some computation over it.

insert creates a new atom on the atomspace or updates the existing one.

remove deletes an atom from the atomspace. Returns True in success or False if it couldn't locate the specified atom.

get looks for an atom in the atomspace and returns it. (With updated mutable information)

debug prints the state of the AtomSpace on stderr. (only for debugging purposes)

cogBind calls the pattern matcher with the given bindLink. (you should insert the bindlink to the atomspace before using this function).

printAtom prints the given atom on stdout.

showAtom shows an atom in opencog notation (indented notation).

TruthVal represent the different types of TruthValues.

Atom name type.

Atom is the main data type to represent the different types of atoms.

Here we impose type constraints in how atoms relate between them.

The <~ type operator means that the type on the left "inherits" from the type on the right.

DEFINING NEW ATOM TYPES:

• If it is a node:

  We add a new data constructor such as:

   NewAtomTypeNode :: AtomName -> TVal -> Atom NewAtomTypeT

  where NewAtomTypeT is a phantom type (automatically generated by temp. hask.).

• If it is a link:
  • If it is of a fixed arity:

    We impose the type constraints on each of the members of its outgoing set.

     NewAtomTypeLink :: (a t1,b <~ t2,c <~ t3) =
               TVal -> Atom a -> Atom b -> Atom c -> AtomNewAtomTypeT

  • If it is of unlimited arity:

    We define it as a data constructor that takes a list of atoms as first argument. All the members of its outgoing set will satisfy the same constraints.

    For example suppose NewAtomTypeLink accepts nodes that are concepts:

     NewAtomTypeLink :: TVal -> [Gen ConceptT] -> Atom NewAtomTypeT

Also, you have to modify the module Internal. Adding proper case clauses for this new atom type to the functions "toRaw" and "fromRaw".

Gen groups all the atoms that are children of the atom type a.

appGen evaluates a given function with the atom type instance wrapped inside the Gen type.

AtomGen is a general atom type hiding the type variables. (necessary when working with many instances of different atoms, for example, for lists of general atoms)

TruthVal syntactic sugar.

atomList is simple sugar notation for listing atoms, using operators |> and \>. For example, if you want to define a list of atoms:

l :: [AtomGen]
l = atomList
      |> ConceptNode "concept1" noTv
      |> PredicateNode "predicate2" noTv
      \> ConceptNode "lastconcept" noTv

|> and \> operators are provided for easier notation of list of Gen elements when working with atoms of random arity (e.g. ListLink).

• Without sugar:

  list :: Atom ListT
  list = ListLink [ Gen (ConceptNode "someConcept1" noTv)
                  , Gen (PredicateNode "somePredicate1" noTv)
                  , Gen (PredicateNode "somePredicate2" noTv)
                  , Gen (ListLink [ Gen (ConceptNode "someConcept2" noTv)
                                  , Gen (PredicateNode "somePredicate3" noTv)
                                  ]
                        )
                  ]
  

• With sugar:

  list :: Atom ListT
  list = ListLink |> ConceptNode "someConcept1" noTv
                  |> PredicateNode "somePredicate1" noTv
                  |> PredicateNode "somePredicate2" noTv
                  \> ListLink |> ConceptNode "someConcept2" noTv
                              \> PredicateNode "somePredicate3" noTv
  

AtomType is automatically generated by Template Haskell (based on: atom_types.script file)

<~ builds a list of constraints to assert that all the ancestors of b (included b itself) are ancestors of a.