org/honey-spec.org

   1
   2 * Introduction
   3
   4 This is a specification of the interface between the middle-end and
   5 back-end of the arxana system.
   6
   7 * Dispatcher
   8
   9 The dispatcher is an applicaton layer which mediates interactions
  10 between the middle end and the back-end(s).
  11
  12 ** Registries
  13
  14 These commands and variables implement the plexus registry.
  15
  16 *** type-registry
  17
  18 variable type-registry
  19
  20 This is where the dispatcher maintains information about different
  21 types of supported backends is stored.
  22
  23 *** plexus-registry
  24
  25 This is where the dispatcher maintains information about the plexi
  26 currently defined in the system is stored.
  27
  28 *** storage-types
  29
  30 function storage-types ()
  31
  32 Return a list of types of databases which the system currently
  33 recognizes.
  34
  35 *** storage-type-p
  36
  37 predicate storage-type-p (type)
  38
  39 Query whhether a particular type is currently supported.
  40
  41 *** remove-handler
  42
  43 function
  44
  45 remove-handler (type)
  46
  47 Remove a certain type of handler from the type registry.
  48
  49 *** show-plexus-registry
  50
  51 function show-plexus-registry ()
  52
  53 List the plexi currently open in the system.
  54
  55 *** set-current-plexus
  56
  57 function set-current-plexus (plex)
  58
  59 Define the default plexus to which subsequent commands will apply.
  60
  61 *** show-current-plexus
  62
  63 function show-current-plexus ()
  64
  65 Return the plexus currently being examined.
  66
  67 *** with-current-plexus
  68
  69 macro with-current-plexus (plex &rest expr)
  70
  71 Evaluate the enclosed code in the context of a specified plexus.
  72
  73
  74 ** Labelling nemata
  75
  76 For the convenience of the user, the system allows one to label nemata
  77 and plexi with descriptive names which can be used in place of the
  78 identifiers which it assigns to them.
  79
  80 *** label-nema
  81
  82 function label-nema (uid label)
  83
  84 Assign the label to the given object.
  85
  86 *** label2uid
  87
  88 function label2uid (label)
  89
  90 Return the unique identifier corresponding to a label.
  91
  92 *** uid2label
  93
  94 function uid2label (uid)
  95
  96 Return the label associated to a unique identifier.
  97
  98
  99 * Honey
 100
 101 Honey is the protocol whereby arxana communicates with the database
 102 routines in which the triples reside.  Standardizing the form of
 103 this interface makes it possible to swap out one type of database (say
 104 hash tables) for another type (say a relational database) without
 105 making any changes to the middle-end code or changing the functionality.
 106
 107 Wth a few exceptions which will be noted below, the commands here come
 108 in two versions --- a system version which is called by the
 109 dispatcher and which directly interacts with the appropriate database
 110 and a user version which is a wrapper around the system-level form
 111 in which the dispatcher adds convenience and bookkeeping.
 112
 113 ** Instance operations
 114
 115 These operations create, initialize, and destroy instances of plexi.
 116
 117 *** initialize-handler
 118
 119 function
 120
 121 system: initialize-handler ()
 122
 123 Initialize the handler for a certain type the first time that that
 124 type is added to the type registry.
 125
 126 *** finalize-handler
 127
 128 function
 129
 130 system: finalize-handler ()
 131
 132 Clean up whatever data structures the handler was using whien it is
 133 removed from the type registry or when arxana shuts down.
 134
 135 *** add-plexus
 136
 137 function
 138
 139 system: add-plexus ()
 140 user: add-plexus ()
 141
 142 Create a new plexus.
 143
 144 *** reset-plexus
 145
 146 function
 147
 148 system: reset-plexus (plex)
 149 user: reset-plexus (plex)
 150
 151 Restore a plexus to its original state.
 152
 153 *** remove-plexus
 154
 155 system: remove-plexus (plex)
 156 user: remove-plexus (plex)
 157
 158 Remove a plexus.
 159
 160 function reset-plexus ()
 161
 162 ** Bulk operatons
 163
 164 These operations act on the database as a whole.
 165
 166 *** download-en-masse
 167
 168 function
 169
 170 system: download-en-masse (plex)
 171 user: download-en-masse ()
 172
 173 Produce a serialization of the database as quintuples.
 174
 175 *** upload-en-masse
 176
 177 function
 178
 179 system: upload-en-masse (plex)
 180 user: upload-en-masse (plex)
 181
 182 Load a representation of a database as quintuples into memory.
 183
 184 *** add-en-masse
 185
 186 function
 187
 188 system: add-en-masse (plex)
 189 user:  add-en-masse (plex)
 190
 191 Add multiple nemata given as list of quartuplets.
 192
 193 ** Individual operations
 194
 195 These operations act on individual items in the database.
 196
 197 *** add-nema
 198
 199 function
 200
 201 system add-nema (plex src txt snk)
 202 user: add-nema (src txt snk)
 203
 204 Enter a new nema to the database.
 205
 206 *** get-content
 207
 208 function
 209
 210 system: get-content (plex nema)
 211 user: get-content (uid)
 212
 213 Return the content of the nema.
 214
 215 *** get-source
 216
 217 function
 218
 219 system: get-source (plex nema)
 220 user: get-source (uid)
 221
 222 Return the source of the nema.
 223
 224 *** get-sink
 225
 226 function
 227
 228 system: get-sink (plex nema)
 229 user: get-sink (uid)
 230
 231 Return the sink of the nema.
 232
 233 *** get-forward-links
 234
 235 function
 236
 237 system: get-forward-links (plex nema)
 238 user: get-forward-links (uid)
 239
 240 Return all links having given object as source.
 241
 242 *** get-backward-links
 243
 244 function
 245
 246 system: get-backward-links (plex nema)
 247 user: get-backward-links (uid)
 248
 249 Return all links having given object as sink.
 250
 251 *** update-content
 252
 253 function
 254
 255 system: update-content (plex nema txt)
 256 user: update-content (uid txt)
 257
 258 Replace the content of the nema.
 259
 260 *** update-source
 261
 262 function
 263
 264 system: update-source (plex nema new-src)
 265 user: update-source (uid new-src)
 266
 267 Replace the source of the nema.
 268
 269 *** update-sink
 270
 271 function
 272
 273 system: update-sink (plex nema new-snk)
 274 user: update-sink (uid new-snk)
 275
 276 Change the sink of the nema.
 277
 278 *** remove-nema
 279
 280 function
 281
 282 system: remove-nema (plex nema)
 283 user: remove-nema (uid)
 284
 285 Remove this nema from the database.
 286
 287 ** Queries
 288
 289 These are commands for querying the database.
 290
 291 *** uid-p
 292
 293 predicate
 294
 295 user: uid-p (uid)
 296
 297 Is this a valid uid?
 298
 299 *** uid-list
 300
 301 function
 302
 303 user: uid-list ()
 304
 305 List of all valid uid's.
 306
 307 *** ground-p
 308
 309 predicate
 310
 311 system: ground-p (plex nema)
 312 user: ground-p (uid)
 313
 314 Is this nema the ground?
 315
 316 *** source-p
 317
 318 predicate
 319
 320 system: source-p (plex x y)
 321 user: source-p (x y)
 322
 323 Is the former nema the sink of the latter?
 324
 325 *** sink-p
 326
 327 predicate
 328
 329 system: sink-p (plex x y)
 330 user: sink-p (x y)
 331
 332 Is the former nema the sink of the latter?
 333
 334 *** links-from
 335
 336 function
 337
 338 system: links-from (plex x y)
 339 user: links-from (x y)
 340
 341 Return all links from nema x to nema y.
 342
 343 *** links-p
 344
 345 predicate
 346
 347 system: links-p (plex x y)
 348 user: links-p (x y)
 349
 350 Does nema x link to nema y?"
 351
 352 *** triple-p
 353
 354 predicate
 355
 356 system: triple-p (plex x y z)
 357 user: triple-p (x y z)
 358
 359 Do the three items form a triplet?
 360
 361 *** plexus-p
 362
 363 predicate
 364
 365 user: plexus-p (x)
 366
 367 Is this object a plexus?
 368
 369 ** Iteration
 370
 371 These commands allow the end user to run loops over the database
 372 without having to interact directly with the backend structures.
 373
 374 *** do-plexus
 375
 376 macro
 377
 378 system: do-plexus (plex var body res)
 379 user: do-plexus (var body res)
 380
 381 Loop over the current plexus binding var to each nema in turn,
 382 evaluating the body, and returning res.
 383
 384 *** map-plexus
 385
 386 function
 387
 388 system: map-plexus (plex func)
 389 user: map-plexus (func)
 390
 391 Evaluate func over all nemata in the plexus and return a list of the
 392 results.
 393
 394 *** filter-plexus
 395
 396 function
 397
 398 system: filter-plexus (plex pred)
 399 user: filter-plexus (pred)
 400
 401 Return a list of all nemata satisfying the condition pred.