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

@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.

@bold{Note:} I am currently migrating this module to Typed Racket.
This documentation only lists the functions and the types which have already
been converted.  However, the typed part is currently hidden in an untyped
module, so you cannot yet use the types directly.

@bold{TODO:} Hyperlinks are currently broken in this document because it
actually documents a submodule.  Fix them once the migration to Typed Racket
has reached a fixed point.

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

@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)))
]}

@defform[(auto-hash-ref/explicit stx)
         #:contracts ([stx (VariableMapping A)])]{

Given a @racket[VariableMapping] and a sequence of symbols, binds these symbols
to the values they are associated with in the hash table, then puts the body in
the context of these bindings.

@examples[#:eval utils-evaluator
(define env #hash((a . 1) (b . 2)))
(auto-hash-ref/explicit (env a b) (+ a (* 2 b)))
]

Note that only one expression can be supplied in the body.

}

@defform[(auto-hash-ref/: stx)
	 #:contracts ([stx (VariableMapping A)])]{

Given an expression and a @racket[VariableMapping], looks up the symbols with
a leading semicolon and binds them to the value they are associated with in the
hash table.

@examples[#:eval utils-evaluator
(define env #hash((a . 1) (b . 2)))
(auto-hash-ref/: env (+ :a (* 2 :b)))
]

Thus the symbol @racket[:a] is matched to the key @racket['a] in the
hash table.

Note that only one expression can be supplied in the body.

}

@section{Analysis of quoted expressions}

@defproc[(extract-symbols [form Any]) (Listof Symbol)]{

Produces a list of symbols appearing in the quoted expression
passed in the first argument.

@examples[#:eval utils-evaluator
(extract-symbols '(1 (2 3) x (y z 3)))
]

}

@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.

@defproc[(any->string [x Any]) String]{

Converts any value to string by calling @racket[display] on it and capturing
the result in a string.

@examples[#:eval utils-evaluator
(any->string '(a 1 (x y)))
]}

@defproc[(stringify-variable-mapping [ht (VariableMapping Any)]) (VariableMapping String)]{

Converts all the values of a @racket[VariableMapping] to string.

@examples[#:eval utils-evaluator
(stringify-variable-mapping (hash 'a '(and a b) 'b '(not b)))
]}

@defproc[(string->any [str String]) Any]{

Reads any value from string.

@examples[#:eval utils-evaluator
(string->any "(or b (not a))")
]}

@defproc[(map-sexp [func (-> Any Any)] [sexp Any]) Any]{

Given a @racket[Sexp], applies the @racket[func] to any object which is not
a list.

@racket[map-sexp] will not check whether @racket[func] is indeed applicable to
every non-list element of @racket[sexp].  If this is not the case, a contract
violation for func will be generated.

@examples[#:eval utils-evaluator
(map-sexp (λ (x) (add1 (cast x Number))) '(1 2 (4 10) 3))
]}

@defproc*[([(read-org-sexp [str String]) Any]
	   [(unorg [str String]) Any])]{

Reads a @racket[sexp] from a string produced by Org-mode for a named table.

@racket[unorg] is a shortcut for @racket[read-org-sexp].

@examples[#:eval utils-evaluator
(unorg "(#t \"#t\" \"#t \" '(1 2 \"#f\"))")
]}

@defform[(GeneralPair A B)]{

A @racket[(Pair A B)] or a @racket[(List A B)].

}

@defproc[(unstringify-pairs [pairs (Listof (GeneralPair String Any))])
         (Listof (GeneralPair Symbol Any))]{

Given a list of pairs of strings and some other values (possibly strings),
converts the first element of each pair to a string, and reads the second
element with @racket[string->any] or keeps it as is if it is not a string.

@examples[#:eval utils-evaluator
(unstringify-pairs '(("a" . 1) ("b" . "(and a (not b))")))
]}

@defproc*[([(read-org-variable-mapping [str String]) (VariableMapping Any)]
           [(unorgv [str String]) (VariableMapping Any)])]{

Reads a @racket[VariableMapping] from a string, such as the one which Org-mode
produces from tables.

@racket[unorgv] is a synonym of @racket[read-org-variable-mapping].

@examples[#:eval utils-evaluator
(read-org-variable-mapping
  "((\"a\" . \"(and a b)\") (\"b\" . \"(or b (not a))\"))")
]}

@defproc[(read-symbol-list (str String)) (Listof Symbol)]{

Reads a list of symbols from a string.

@examples[#:eval utils-evaluator
(read-symbol-list "a b c")
]}

@defproc[(drop-first-last (str String)) String]{

Removes the first and the last symbol of a given string.

Useful for removing the parentheses in string representations of lists.

@examples[#:eval utils-evaluator
(drop-first-last "(a b)")
]}

@section{Additional graph utilities}
@defproc[(dotit [graph Graph]) Void]{

Typeset the graph via graphviz and display it.

@examples[#:eval utils-evaluator
(require typed/graph)
(dotit (weighted-graph/directed '((1 a b) (2 b c))))
]}

@section{Pretty printing}

@section{Additional list and hash map utilities}

@section{Functions and procedures}

@section{Randomness}

@section{Additional stream utilities}

@section{Boolean operations}