On this page:
$message
define-message
define+  provide-message
$show-datum
$show-string
$regarding
scope-message
call-in-message-scope
call-in-message-scope*
in-message-scope
get-message-scope
8.0

9 Messages

 (require xiden/message) package: xiden

A message is an instance of the $message prefab structure used to share information in the Xiden runtime, in logs, and between processes. When the term “message” is ambiguous, then Xiden message applies the context of this section.

Message types may form a heirarchy using colon-separated identifiers that start with $. The $message type itself has no semantics beyond serving as the root type, and its identifier does not appear in other structure type identifiers. For example, identifiers pertaining to command line messages start with $cli, not $message:cli.

The type heirarchy serves only to organize statements under a given topic. Meaning that a $transfer:budget? would capture messages pertaining to a budget for a byte transfer, but an instance of $transfer:budget:exceeded is an exact statement reporting an overrun.

A message may require another message to serve as context. A type heirarchy is unhelpful for this purpose, since $transfer:budget:exceeded could apply to a download in the context of a build process or a verification process. It is difficult to define a single type to capture this kind of variation, so Xiden instead composes messages into machine-readable documents.

struct

(struct $message ()
    #:prefab)
The base type for all messages.

syntax

(define-message id [field-expr ...])

(define-message id super-id [field-expr ...])
Like struct, in that (define-message foo (a b c)) is equivalent to (struct foo $message (a b c) #:prefab).

The second form allows declaration of a supertype, but that supertype must be a subtype of $message.

syntax

(define+provide-message id form ...)

Like define-message, with an included (provide (struct-out id)).

struct

(struct $show-datum $message (value)
    #:prefab)
  value : any/c
Represents a request to show the user the given Racket value.

struct

(struct $show-string $message (message)
    #:prefab)
  message : any/c
Represents a request to show the user the given string.

struct

(struct $regarding $message (subject body)
    #:prefab)
  subject : $message?
  body : $message?
Represents a request to show one message in the context of another.

procedure

(scope-message m [scope])  $message?

  m : $message?
  scope : (listof $message?) = (get-message-scope)
Returns m if scope is null.

Otherwise, returns (scope-message ($regarding (car scope) m) (cdr scope)).

Use to wrap a message with $regarding, where the exact structure of the output may depend on the current dynamic extent.

procedure

(call-in-message-scope m proc)  any

  m : $message
  proc : (-> any)
Equivalent to (call-in-message-scope* (cons m (get-message-scope)) proc).

procedure

(call-in-message-scope* ms proc)  any

  ms : (listof $message?)
  proc : (-> any)
Returns (proc). While proc has control, (get-message-scope) is eq? to ms.

syntax

(in-message-scope m body ...)

Expands to (call-in-message-scope m (lambda () body ...)).

procedure

(get-message-scope)  (listof $message?)

Returns a list of messages representing a dynamic scope for other messages. See call-in-message-scope.