scolobb/dds
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

functions.scrbl: Add shortcuts for @examples.

Browse source
This commit is contained in:
Sergiu Ivanov 2022-04-24 23:59:55 +02:00
parent e1a97235c0
commit da6f5acf4e
1 changed files with 51 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
scribblings/utils.scrbl
View file

@ -6,6 +6,15 @@
(only-in racket/set set) (only-in racket/set set)
(only-in racket/stream stream->list stream-take))) (only-in racket/stream stream->list stream-take)))
@(define utils-evaluator
(parameterize ([sandbox-output 'string]
[sandbox-error-output 'string]
[sandbox-memory-limit 50])
(make-evaluator 'typed/racket #:requires '("utils.rkt"))))
@(define-syntax-rule (ex . args)
(examples #:eval utils-evaluator . args))
@title[#:tag "utils"]{dds/utils: Various Utilities} @title[#:tag "utils"]{dds/utils: Various Utilities}
@defmodule[dds/utils] @defmodule[dds/utils]
@ -14,12 +23,6 @@ This module defines miscellaneous utilities, supporting the other modules of
the package: evaluating sexps, manipulating lists, the package: evaluating sexps, manipulating lists,
@hyperlink["https://orgmode.org/"]{Org-mode} interoperability, etc. @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 #:requires '("utils.rkt"))))
@section{Base types} @section{Base types}
@defidform[Variable]{ @defidform[Variable]{
@ -50,7 +53,7 @@ typing} either via a direct @racket[if] check using a predicate, or using
@racket[assert] that the type of @racket[expr] is @racket[type]. @racket[assert] that the type of @racket[expr] is @racket[type].
@examples[#:eval utils-evaluator @ex[
(define some-number : Any 1) (define some-number : Any 1)
(assert-type some-number Integer) (assert-type some-number Integer)
(assert-type some-number Positive-Integer) (assert-type some-number Positive-Integer)
@ -68,7 +71,7 @@ explicit @racket[hash-ref] calls.
Temporarily injects the mappings from the given hash table as bindings in Temporarily injects the mappings from the given hash table as bindings in
a namespace including @racket[racket/base] and then evaluates the expression. a namespace including @racket[racket/base] and then evaluates the expression.
@examples[#:eval utils-evaluator @ex[
(let ([ht (hash 'a 1 'b 1)]) (let ([ht (hash 'a 1 'b 1)])
(eval-with ht '(+ b a 1))) (eval-with ht '(+ b a 1)))
] ]
@ -77,7 +80,7 @@ The local bindings from the current lexical scope are not
conserved. Therefore, the following outputs an error about a conserved. Therefore, the following outputs an error about a
missing identifier: missing identifier:
@examples[#:eval utils-evaluator @ex[
(eval:error (eval:error
(let ([ht (hash 'a 1 'b 1)] (let ([ht (hash 'a 1 'b 1)]
[z 1]) [z 1])
@ -89,7 +92,7 @@ missing identifier:
Like @racket[eval-with], but returns only the first value computed by Like @racket[eval-with], but returns only the first value computed by
@racket[expr]. @racket[expr].
@examples[#:eval utils-evaluator @ex[
(let ([ht (hash 'a 1 'b 1)]) (let ([ht (hash 'a 1 'b 1)])
(eval1-with ht '(+ b a 1))) (eval1-with ht '(+ b a 1)))
]} ]}
@ -101,7 +104,7 @@ 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 to the values they are associated with in the hash table, then puts the body in
the context of these bindings. the context of these bindings.
@examples[#:eval utils-evaluator @ex[
(define env #hash((a . 1) (b . 2))) (define env #hash((a . 1) (b . 2)))
(auto-hash-ref/explicit (env a b) (+ a (* 2 b))) (auto-hash-ref/explicit (env a b) (+ a (* 2 b)))
] ]
@ -117,7 +120,7 @@ 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 a leading semicolon and binds them to the value they are associated with in the
hash table. hash table.
@examples[#:eval utils-evaluator @ex[
(define env #hash((a . 1) (b . 2))) (define env #hash((a . 1) (b . 2)))
(auto-hash-ref/: env (+ :a (* 2 :b))) (auto-hash-ref/: env (+ :a (* 2 :b)))
] ]
@ -136,7 +139,7 @@ Note that only one expression can be supplied in the body.
Produces a list of symbols appearing in the quoted expression Produces a list of symbols appearing in the quoted expression
passed in the first argument. passed in the first argument.
@examples[#:eval utils-evaluator @ex[
(extract-symbols '(1 (2 3) x (y z 3))) (extract-symbols '(1 (2 3) x (y z 3)))
] ]
@ -159,7 +162,7 @@ for examples of usage.
Converts any value to string by calling @racket[display] on it and capturing Converts any value to string by calling @racket[display] on it and capturing
the result in a string. the result in a string.
@examples[#:eval utils-evaluator @ex[
(any->string '(a 1 (x y))) (any->string '(a 1 (x y)))
]} ]}
@ -167,7 +170,7 @@ the result in a string.
Converts all the values of a @racket[VariableMapping] to string. Converts all the values of a @racket[VariableMapping] to string.
@examples[#:eval utils-evaluator @ex[
(stringify-variable-mapping (hash 'a '(and a b) 'b '(not b))) (stringify-variable-mapping (hash 'a '(and a b) 'b '(not b)))
]} ]}
@ -175,7 +178,7 @@ Converts all the values of a @racket[VariableMapping] to string.
Reads any value from string. Reads any value from string.
@examples[#:eval utils-evaluator @ex[
(string->any "(or b (not a))") (string->any "(or b (not a))")
]} ]}
@ -188,7 +191,7 @@ a list.
every non-list element of @racket[sexp]. If this is not the case, a contract every non-list element of @racket[sexp]. If this is not the case, a contract
violation for func will be generated. violation for func will be generated.
@examples[#:eval utils-evaluator @ex[
(map-sexp (λ (x) (add1 (cast x Number))) '(1 2 (4 10) 3)) (map-sexp (λ (x) (add1 (cast x Number))) '(1 2 (4 10) 3))
]} ]}
@ -199,7 +202,7 @@ 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]. @racket[unorg] is a shortcut for @racket[read-org-sexp].
@examples[#:eval utils-evaluator @ex[
(unorg "(#t \"#t\" \"#t \" '(1 2 \"#f\"))") (unorg "(#t \"#t\" \"#t \" '(1 2 \"#f\"))")
]} ]}
@ -216,7 +219,7 @@ 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 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. element with @racket[string->any] or keeps it as is if it is not a string.
@examples[#:eval utils-evaluator @ex[
(unstringify-pairs '(("a" . 1) ("b" . "(and a (not b))"))) (unstringify-pairs '(("a" . 1) ("b" . "(and a (not b))")))
]} ]}
@ -228,7 +231,7 @@ produces from tables.
@racket[unorgv] is a synonym of @racket[read-org-variable-mapping]. @racket[unorgv] is a synonym of @racket[read-org-variable-mapping].
@examples[#:eval utils-evaluator @ex[
(read-org-variable-mapping (read-org-variable-mapping
"((\"a\" . \"(and a b)\") (\"b\" . \"(or b (not a))\"))") "((\"a\" . \"(and a b)\") (\"b\" . \"(or b (not a))\"))")
]} ]}
@ -237,7 +240,7 @@ produces from tables.
Reads a list of symbols from a string. Reads a list of symbols from a string.
@examples[#:eval utils-evaluator @ex[
(read-symbol-list "a b c") (read-symbol-list "a b c")
]} ]}
@ -247,7 +250,7 @@ Removes the first and the last symbol of a given string.
Useful for removing the parentheses in string representations of lists. Useful for removing the parentheses in string representations of lists.
@examples[#:eval utils-evaluator @ex[
(drop-first-last "(a b)") (drop-first-last "(a b)")
]} ]}
@ -256,7 +259,7 @@ Useful for removing the parentheses in string representations of lists.
Converts a list of sets of symbols to a list of strings containing Converts a list of sets of symbols to a list of strings containing
those symbols. those symbols.
@examples[#:eval utils-evaluator @ex[
(list-sets->list-strings (list (set 'x 'y) (set 'z) (set) (set 't))) (list-sets->list-strings (list (set 'x 'y) (set 'z) (set) (set 't)))
]} ]}
@ -266,7 +269,7 @@ those symbols.
Pretty prints a set by listing its elements in alphabetic order. Pretty prints a set by listing its elements in alphabetic order.
@examples[#:eval utils-evaluator @ex[
(pretty-print-set (set 'a 'b 1)) (pretty-print-set (set 'a 'b 1))
]} ]}
@ -277,7 +280,7 @@ Pretty-prints a set of sets of symbols.
Typically used for pretty-printing the annotations on the edges of Typically used for pretty-printing the annotations on the edges of
a state graph. a state graph.
@examples[#:eval utils-evaluator @ex[
(pretty-print-set-sets (set (set 'a 'b) (set 'c))) (pretty-print-set-sets (set (set 'a 'b) (set 'c)))
]} ]}
@ -285,7 +288,7 @@ a state graph.
All examples in this section depend on @racket[typed/graph]: All examples in this section depend on @racket[typed/graph]:
@examples[#:eval utils-evaluator @ex[
(require typed/graph) (require typed/graph)
] ]
@ -293,7 +296,7 @@ All examples in this section depend on @racket[typed/graph]:
Typesets the graph via @racket[graphviz] and @racket[display]s it. Typesets the graph via @racket[graphviz] and @racket[display]s it.
@examples[#:eval utils-evaluator @ex[
(dotit (weighted-graph/directed '((1 a b) (2 b c)))) (dotit (weighted-graph/directed '((1 a b) (2 b c))))
]} ]}
@ -309,7 +312,7 @@ may be called multiple times for the same vertex.
This function does not rely on @racket[rename-vertex!], so it can be used to This function does not rely on @racket[rename-vertex!], so it can be used to
permute vertex labels. permute vertex labels.
@examples[#:eval utils-evaluator @ex[
(define g (directed-graph '((a b) (b c)))) (define g (directed-graph '((a b) (b c))))
(define (double-labels [x : Any]) (define (double-labels [x : Any])
(define x-str (symbol->string (cast x Symbol))) (define x-str (symbol->string (cast x Symbol)))
@ -329,7 +332,7 @@ functions. If @racket[graph] is an weighted graph, the result is a weighted
graph. If @racket[graph] is an unweighted graph, the result is an graph. If @racket[graph] is an unweighted graph, the result is an
unweighted graph. unweighted graph.
@examples[#:eval utils-evaluator @ex[
(define g (weighted-graph/directed '((10 a b) (11 b c)))) (define g (weighted-graph/directed '((10 a b) (11 b c))))
(define (double-labels [x : Any]) (define (double-labels [x : Any])
(define x-str (symbol->string (cast x Symbol))) (define x-str (symbol->string (cast x Symbol)))
@ -351,7 +354,7 @@ a list containing the corresponding list of values.
If @racket[keys] can be treated as edges (i.e. pairs of vertices), the results If @racket[keys] can be treated as edges (i.e. pairs of vertices), the results
produced by this function are suitable for graph constructors. produced by this function are suitable for graph constructors.
@examples[#:eval utils-evaluator @ex[
(collect-by-key '(a b a) '(1 2 3)) (collect-by-key '(a b a) '(1 2 3))
]} ]}
@ -361,7 +364,7 @@ produced by this function are suitable for graph constructors.
Like @racket[collect-by-key], but produce a list of sets instead of a list Like @racket[collect-by-key], but produce a list of sets instead of a list
of lists. of lists.
@examples[#:eval utils-evaluator @ex[
(collect-by-key/sets '(a b a) '(1 2 3)) (collect-by-key/sets '(a b a) '(1 2 3))
]} ]}
@ -370,7 +373,7 @@ of lists.
Converts the values of a hash table from lists to sets. Converts the values of a hash table from lists to sets.
@examples[#:eval utils-evaluator @ex[
(ht-values/list->set #hash((a . (1 1)))) (ht-values/list->set #hash((a . (1 1))))
]} ]}
@ -384,7 +387,7 @@ hash table orders them for @racket[hash-map].
@bold{TODO:} Remove after Typed Racket has caught up with Racket 8.4, in which @bold{TODO:} Remove after Typed Racket has caught up with Racket 8.4, in which
@racket[hash->list] gets a new optional argument @racket[try-order?]. @racket[hash->list] gets a new optional argument @racket[try-order?].
@examples[#:eval utils-evaluator @ex[
(hash->list/ordered #hash((b . 1) (a . 1))) (hash->list/ordered #hash((b . 1) (a . 1)))
]} ]}
@ -396,7 +399,7 @@ Given a list of lists, splits every single list at the given position, and then
returns two lists of lists: one consisting of the first halves, and the one returns two lists of lists: one consisting of the first halves, and the one
consisting of the second halves. consisting of the second halves.
@examples[#:eval utils-evaluator @ex[
(multi-split-at '((1 2 3) (a b c)) 2) (multi-split-at '((1 2 3) (a b c)) 2)
]} ]}
@ -409,7 +412,7 @@ the shortest list in @racket[lists].
This function is essentially @racket[in-parallel], wrapped in This function is essentially @racket[in-parallel], wrapped in
a couple conversions. a couple conversions.
@examples[#:eval utils-evaluator @ex[
(lists-transpose '((a b) (1 2))) (lists-transpose '((a b) (1 2)))
(lists-transpose '((a b) (1 2 3) (#t))) (lists-transpose '((a b) (1 2 3) (#t)))
] ]
@ -427,7 +430,7 @@ untyped code.
@racket[lsts] is a list of rows, in which each row is split in two halves. @racket[lsts] is a list of rows, in which each row is split in two halves.
The function returns the list of the same rows, with the two halves appended. The function returns the list of the same rows, with the two halves appended.
@examples[#:eval utils-evaluator @ex[
(append-lists '(((1 2) (a b)) (append-lists '(((1 2) (a b))
((3 4) (c d)))) ((3 4) (c d))))
]} ]}
@ -454,7 +457,7 @@ range @racket[min] to @racket[max]-1.}
] ]
@examples[#:eval utils-evaluator @ex[
(require typed/racket/stream) (require typed/racket/stream)
(stream->list (stream-take (in-random) 5)) (stream->list (stream-take (in-random) 5))
(stream->list (stream-take (in-random 10) 5)) (stream->list (stream-take (in-random 10) 5))
@ -471,7 +474,7 @@ Generates a stream containing all the pairs of the elements from @racket[s1]
and @racket[s2]. The elements of @racket[s2] are enumerated in order for every and @racket[s2]. The elements of @racket[s2] are enumerated in order for every
element of the @racket[s1], taken in order as well. element of the @racket[s1], taken in order as well.
@examples[#:eval utils-evaluator @ex[
(require typed/racket/stream) (require typed/racket/stream)
(stream->list (cartesian-product-2/stream (in-range 1 5) '(a b))) (stream->list (cartesian-product-2/stream (in-range 1 5) '(a b)))
] ]
@ -479,7 +482,7 @@ element of the @racket[s1], taken in order as well.
The streams can be infinite. If the second stream is infinite, only the first The streams can be infinite. If the second stream is infinite, only the first
element of @racket[s1] will be enumerated. element of @racket[s1] will be enumerated.
@examples[#:eval utils-evaluator @ex[
(stream->list (stream-take (cartesian-product-2/stream '(a b) (in-naturals)) 10)) (stream->list (stream-take (cartesian-product-2/stream '(a b) (in-naturals)) 10))
]} ]}
@ -496,7 +499,7 @@ which the streams are enumerated.
Union types can be used to build the Cartesian product of streams containing Union types can be used to build the Cartesian product of streams containing
values of different types. values of different types.
@examples[#:eval utils-evaluator @ex[
(stream->list (cartesian-product/stream (list (in-range 3) (in-range 4 6) '(a b)))) (stream->list (cartesian-product/stream (list (in-range 3) (in-range 4 6) '(a b))))
]} ]}
@ -507,7 +510,7 @@ values of different types.
Returns the @racket[n]-th Cartesian power of the Boolean domain. Returns the @racket[n]-th Cartesian power of the Boolean domain.
@examples[#:eval utils-evaluator @ex[
(boolean-power 2) (boolean-power 2)
]} ]}
@ -516,7 +519,7 @@ Returns the @racket[n]-th Cartesian power of the Boolean domain.
Like @racket[boolean-power], but returns a stream. Like @racket[boolean-power], but returns a stream.
@examples[#:eval utils-evaluator @ex[
(stream->list (boolean-power/stream 2)) (stream->list (boolean-power/stream 2))
]} ]}
@ -524,7 +527,7 @@ Like @racket[boolean-power], but returns a stream.
Converts any non-@racket[#f] value to 1 and @racket[#f] to 0. Converts any non-@racket[#f] value to 1 and @racket[#f] to 0.
@examples[#:eval utils-evaluator @ex[
(any->01 #t) (any->01 #t)
(any->01 #f) (any->01 #f)
(any->01 'hello) (any->01 'hello)
@ -534,7 +537,7 @@ Converts any non-@racket[#f] value to 1 and @racket[#f] to 0.
Converts 0 to @racket[#f] and 1 to @racket[#t]. Converts 0 to @racket[#f] and 1 to @racket[#t].
@examples[#:eval utils-evaluator @ex[
(01->boolean 0) (01->boolean 0)
(01->boolean 1) (01->boolean 1)
]} ]}
@ -554,6 +557,9 @@ contracts by Typed Racket.
[sandbox-memory-limit 50]) [sandbox-memory-limit 50])
(make-evaluator 'racket #:requires '((submod "utils.rkt" untyped))))) (make-evaluator 'racket #:requires '((submod "utils.rkt" untyped)))))
@(define-syntax-rule (ex/untyped . args)
(examples #:eval utils-evaluator/untyped . args))
@defproc[(lists-transpose [lists (listof (listof any/c))]) @defproc[(lists-transpose [lists (listof (listof any/c))])
(listof (listof any/c))]{ (listof (listof any/c))]{
@ -563,7 +569,7 @@ the shortest list in @racket[lists].
This function is essentially @racket[in-parallel], wrapped in This function is essentially @racket[in-parallel], wrapped in
a couple conversions. a couple conversions.
@examples[#:eval utils-evaluator/untyped @ex/untyped[
(lists-transpose '((a b) (1 2))) (lists-transpose '((a b) (1 2)))
(lists-transpose '((a b) (1 2 3) (#t))) (lists-transpose '((a b) (1 2 3) (#t)))
]} ]}