# sph-lib examples

to use the features you have to import the relevant modules first, which are mentioned in the titles of the following sections. for example

~~~
(use-modules (sph list))
~~~

# (sph)
## display trace and debug messages
~~~
(+ 3 (debug-log (+ 1 2)))
(debug-log 1 2 3) -> 1
~~~

debug-log returns the first argument and writes all arguments formatted to standard output.
intercept the execution flow for tracing without disturbing it

## [nullary](https://en.wikipedia.org/wiki/Arity#Nullary)
alternative to (lambda () body ...)

~~~
(call-with-values (nullary (partition a? b)) list)
~~~

## let
let with simplified form that additionally makes binding just one variable a bit shorter
~~~
(let (a 1)
  body ...)
~~~

## display-line
~~~
(display-line "test")
~~~

## define-syntax-rule
~~~
(define-syntax-rule (test a b) (+ a b))

(define-syntax-rules test
  ((test a b) (+ a b))
  ((test a) a))
~~~

## short-forms
~~~
l q qq
lambda quote quasiquote
~~~

### l for lambda
~~~
(map (l (a) (+ a 1)) a)
~~~
as alternative to
~~~
(map (lambda (a) (+ a 1)) a)
~~~

### quoting without auxillary read syntax
~~~
(q a)
(qq a)
~~~
as alternatives to
~~~
(quote a)
(quasiquote a)
~~~

# (sph list)
## map the integers in a given range
~~~
(map-integers 10 (l (n) n))
~~~
result
~~~
(0 1 2 3 4 5 6 7 8 9)
~~~

# associative data structures with (sph alist) and (sph hashtable)
## creation
key and value specified alternatingly
~~~
(alist "a" 1 (q b) 2)
(ht-create "a" 1 (q b) 2)
~~~

in application similar to
~~~
(list 1 2 3)
(vector 4 5 6)
~~~

`-q` variants that implicitly quote keys
~~~
(alist-q a 1 b 2)
(ht-create-symbol-q a 1 b 2)
~~~

### get an alist from a hashtable
~~~
; hashtable max-depth -> list:alist
(ht-alist ht)
(ht-alist ht 2)
(ht-alist ht (inf))
~~~

## access
~~~
(alist-ref x (q a))
(ht-ref x (q a))
~~~

`-q` variants that implicitly quote keys
~~~
(alist-ref-q x a)
(ht-ref-q x a)
~~~

### nested references
~~~
(alists-ref x 1 2 3)
(ht-tree-ref x 1 2 3)
~~~

# (sph tree)
## create filesystem paths from nested lists
~~~
(define input
  (q
    ("/usr"
      ("share" "guile")
      "include"
      "")))

(prefix-tree->path-list input)
~~~
result:
~~~
("/usr/share/guile" "/usr/include" "/usr/")
~~~

# other features
* filesystem-glob: resolves ``*/**/?`` in paths
* string-replace-string: fast replacer for strings in strings
* string-brackets-enclosed?: check that a string contains correctly nested and balanced count of brackets or any other pair of start/end characters
* html-fold-multipart-form: parse html multipart/form data, with support for nested data
* port-lines-map: map over lines read from ports like standard input
* copy-file-recursive
* ensure-directory-structure
* ensure-trailing-slash
* poll-watch: watch for filesystem stat changes
* list-logical-match: match values by (and (or (and 1 2 3) 4)) conditions
* list-sort-with-accessor
* tree-map: map over lists and sublists
* realpath*
* split-by-pattern: rudimentary ellipsis pattern matching. a more powerful version can currently be found in sph-sc
* group: build an association list from a list with a custom predicate
* group-recursively
* nested scheme syntax config files with (sph lang config)
* path-pipe-chain: link procedures or shell commands with temporary paths or pipes for data flow between them
* list-ref-randomise-cycle
* any->string, any->string-write: get strings for any object
* call-at-interval
* compact: remove false values from a list
* flatten: merge sublists
* date stream
* fold*: fold with multiple state values
* map-slice and map-segments
* vector-accessor and vector-setter: procedures like (lambda () (vector-ref a 1))
* vector-object: (myvector 3) - access vector elements like object properties