Revise the examples

examples/README.md

@@ -12,6 +12,7 @@ The explorer will be useful for verifying AtomSpace contents.
 
 * basic.scm       - Creating, saving and viewing Atoms.
 * bulk-save.scm   - Bulk save of an entire AtomSpaces.
-* restore.scm     - Fetch of individual Atoms and entire AtomSpaces.
-* values-save.scm    - Save of Values
-* values-restore.scm - Restore of Values, to be run after the above.
+* restore-keyless.scm - Fetch of individual Atoms and entire AtomSpaces.
+* restore-ro.scm      - Read-only fetch of individual Atoms and AtomSpaces.
+* values-save.scm     - Save of Values
+* values-restore.scm  - Restore of Values, to be run after the above.

examples/restore.scm → examples/restore-keyless.scm

@@ -1,16 +1,20 @@
 ;
-; restore.scm
+; restore-keyless.scm
 ;
 ; Simple example of restoring individual atoms, and the bulk restore of
-; entire AtomSpaces.
+; entire AtomSpaces, assuming that the CID's of the Atoms and AtomSpace
+; is known by some other means.
 ;
 (use-modules (opencog))
 (use-modules (opencog persist))
 (use-modules (opencog persist-ipfs))
 
 ; Open connection to the IPFS server.
-; Note that we don't need any keys, if we are not publishing
-; to IPNS.
+; Note that we don't need any keys, if we are not publishing to IPNS.
+; This does, however, require explicit knowledge of the CID's of
+; individual Atoms, or of the AtomSpaces, which are obtained by some
+; other mechanism.
+;
 ; (ipfs-open "ipfs://localhost/")
 ; (ipfs-open "ipfs://localhost:5001/")
 (ipfs-open "ipfs:///")
@@ -49,7 +53,8 @@
 (ipfs-load-atomspace "/ipns/QmVkzxhCMDYisZ2QEMA5WYTjrZEPVbETZg5rehsijUxVHx")
 ; Caution: the above IPNS entry is in active use for develpment, and
 ; might resolve into any kind of crazy test atomspace. Or it might not
-; resolve at all...
+; resolve at all... Note also: at this time, IPNS resolution can take
+; a minute or longer, due to a well-known and still unfixed IPFS bug.
 
 ; Review the stats
 (ipfs-stats)

examples/restore-ro.scm

@@ -0,0 +1,51 @@
+;
+; restore-ro.scm
+;
+; Simple example of read-only access to an AtomSpace.
+;
+(use-modules (opencog))
+(use-modules (opencog persist))
+(use-modules (opencog persist-ipfs))
+
+; Open connection to the IPFS server.
+; One can specify either an IPNS CID, or an IPFS CID that identifies the
+; AtomSpace.
+; (ipfs-open "ipfs://localhost/ipns/QmVkzxhCMDYisZ2QEMA5WYTjrZEPVbETZg5rehsijUxVHx")
+; (ipfs-open "ipfs://localhost:5001/ipns/QmVkzxhCMDYisZ2QEMA5WYTjrZEPVbETZg5rehsijUxVHx")
+(ipfs-open "ipfs:///ipfs/QmaHDniEkN8uzcoPFc8htBakBLg4qkhZsj3nhyYbHM5Q2i")
+
+; (ipfs-resolve-atomspace)
+
+; Given a specific Atom, fetch the current Values on that Atom
+(define c (ConceptNode "example concept"))
+(fetch-atom c)
+
+; Restore the EvaluationLink that was previously created, by restoring
+; the Incoming Set of the ListLink it contains. Recall, that the
+; original EvaluationLink was:
+;
+;    (EvaluationLink
+;       (PredicateNode "Some relationship")
+;       (ListLink
+;          (ConceptNode "foo")
+;          (ConceptNode "bar")))
+;
+(define ll (List (Concept "foo") (Concept "bar")))
+(fetch-incoming-set ll)
+
+; Review the stats
+(ipfs-stats)
+
+; Or one can fetch the entire contents of the AtomSpace.
+(load-atomspace)
+
+; Verify the AtomSpace contents
+(cog-prt-atomspace)
+
+; Review the stats
+(ipfs-stats)
+
+; Close the connection.
+(ipfs-close)
+
+; The End.  That's all for now.