dds/scribblings/utils.scrbl

#lang scribble/manual
@(require scribble/example racket/sandbox
	  (for-label racket graph "../utils.rkt"
	  	     (only-in typed/racket/base
		     	      Any AnyValues)))

@title[#:tag "utils"]{dds/utils: Various Utilities}

@defmodule[dds/utils]

This module defines miscellaneous utilities, supporting the other modules of
the package: evaluating sexps, manipulating lists,
@hyperlink["https://orgmode.org/"]{Org-mode} interoperability, etc.


@(define utils-evaluator
  (parameterize ([sandbox-output 'string]
  		 [sandbox-error-output 'string]
		 [sandbox-memory-limit 50])
   (make-evaluator 'typed/racket/base #:requires '("utils.rkt"))))

@section{Base Types}
@defidform[Variable]{

Any Racket symbol.  Designates a variable in a discrete dynamical network.

}

@defform[(VariableMapping A)]{

An immutable mapping (a hash table) assigning elements of type @racket[A] to
the variables.

}

@section{Hashtable injection}

This section defines some utilities to streamline the usage of hash tables
mapping symbols to values.  The goal is essentially to avoid having to write
explicit @racket[hash-ref] calls.

@defproc[(eval-with [ht (VariableMapping Any)] [expr Any]) AnyValues]{

Temporarily injects the mappings from the given hash table as bindings in
a namespace including @racket[racket/base] and then evaluates the expression.

@examples[#:eval utils-evaluator
(let ([ht (hash 'a 1 'b 1)])
  (eval-with ht '(+ b a 1)))
]

The local bindings from the current lexical scope are not
conserved.  Therefore, the following outputs an error about a
missing identifier:

@examples[#:eval utils-evaluator
(eval:error
(let ([ht (hash 'a 1 'b 1)]
      [z 1])
  (eval-with ht '(+ b z a 1)))
)]}

@defproc[(eval1-with [ht (VariableMapping Any)] [expr Any]) Any]{

Like @racket[eval-with], but returns only the first value computed by
@racket[expr].

@examples[#:eval utils-evaluator
(let ([ht (hash 'a 1 'b 1)])
  (eval1-with ht '(+ b a 1)))
]}
@section{Analysis of quoted expressions}

@section{Org-mode interoperability}

Org-mode supports laying out the output of code blocks as tables, which is very
practical for various variable mappings (e.g., states).  However, when the hash
table maps variables to lists, Org-mode will create a column per list element,
which may or may not be the desired effect.  This section defines some
utilities for nicer interoperation with Org-mode tables.  It also defines some
shortcuts to reduce the number of words to type when using dds with Org-mode.
See
@hyperlink["https://git.marvid.fr/scolobb/dds/src/branch/master/example/example.org"]{example.org}
for examples of usage.

@section{Additional graph utilities}

@section{Pretty printing}

@section{Additional list and hash map utilities}

@section{Functions and procedures}

@section{Randomness}

@section{Additional stream utilities}

@section{Boolean operations}