Text-tree output.

1.0

Text-tree output.🔗ℹ

This package provides a simple interface to output tree-structured data. The single function write-text-tree writes the provided racket data structures out to a port.

procedure
(write-text-tree value [out]) → void?
value : tree-input/c
out : output-port? = (current-output-port)

TBD

Examples:

> (require racket/port)
> (displayln
    (with-output-to-string
      (λ () (write-text-tree
              (make-hash
                `((collection . "text-tree")
                  (deps base)
                  (build-deps scribble-lib racket-doc rackunit-lib)
                  (scribblings "scribblings/text-tree.scrbl")
                  (test-omit-paths "scribblings")
                  (pkg-desc . "Function to output tree-structured data.")
                  (version . 1.0)
                  (pkg-authors johnstonskj)
                  (license . Apache-2.0)))))))
├── build-deps
│   ├── scribble-lib
│   ├── racket-doc
│   └── rackunit-lib
├── collection
│   └── text-tree
├── deps
│   └── base
├── license
│   └── Apache-2.0
├── pkg-authors
│   └── johnstonskj
├── pkg-desc
│   └── Function to output tree-structured data.
├── scribblings
│   └── scribblings/text-tree.scrbl
├── test-omit-paths
│   └── scribblings
└── version
    └── 1.0

procedure
(text-tree->string value) → string?
value : tree-input/c

A convenience wrapper around write-text-tree that writes value to, and returns, a string.

predicate
(atom? val) → boolean?
val : any/c

Returns #t if the val is one of boolean?, char?, number?, string?, bytes, or symbol?. Atoms are written out using the ~a format function.

predicate
(dotted-pair? val) → boolean?
val : any/c

Returns #t if the val is an dotted or improper pair where the cdr is not a list.

predicate
(simple-dictionary? val) → boolean?
val : any/c

Returns #t if the val is either a hash? or a structure implementing gen:dict?.

predicate
(simple-sequence? val) → boolean?
val : any/c

Returns #t if the val is one of list?, vector?, flvector?, fxvector?, or set?.

value
tree-input/c : contract?

This is the value accepted by the function and consists of atomic values, sequences (restricted to lists, mutable lists, vectors, fixnum vectors, flonum vectors, hash tables, sets, and streams), and dictionaries.

atom? – Individual value.
simple-sequence? – Where every member is a tree-input/c.
simple-sequence? – Where every key is a atom? and every value is a tree-input/c.

1 Parameters🔗ℹ

parameter
(tree-representation-line-chars)
→ (list/c char? char? char? char? char?)
(tree-representation-line-chars line-chars) → void?
line-chars : (list/c char? char? char? char? char?)

A parameter that is used in drawing the tree’s connecting lines. The default value is unicode-line-chars, whereas the value ascii-line-chars may be more broadly supported but is a lower quality output.

Horizontal bar character, default #\─.
Vertical bar character, default #\│.
Bottom-left corner character, default #\└.
Right-facing tee character, default #\├.
Spacing character, default #\space.

value
ascii-line-chars : (list/c char? char? char? char? char?)

A set of simple ASCII characters for a low-fi tree.

Examples:

> (require racket/port)
> (parameterize ((tree-representation-line-chars ascii-line-chars))
  (displayln
    (with-output-to-string
      (λ () (write-text-tree
              (make-hash
                '((collection . "text-tree")
                  (deps "base")
                  (build-deps "scribble-lib" "racket-doc" "rackunit-lib")
                  (license . Apache-2.0))))))))
+-- build-deps
|   +-- scribble-lib
|   +-- racket-doc
|   '-- rackunit-lib
+-- collection
|   '-- text-tree
+-- deps
|   '-- base
'-- license
    '-- Apache-2.0

value
unicode-line-chars : (list/c char? char? char? char? char?)

A set of Unicode line-drawing characters for a higher fidelity tree.

Examples:

> (require racket/port)
> (parameterize ((tree-representation-line-chars unicode-line-chars))
  (displayln
    (with-output-to-string
      (λ () (write-text-tree
              (make-hash
                '((collection . "text-tree")
                  (deps "base")
                  (build-deps "scribble-lib" "racket-doc" "rackunit-lib")
                  (license . Apache-2.0))))))))
├── build-deps
│   ├── scribble-lib
│   ├── racket-doc
│   └── rackunit-lib
├── collection
│   └── text-tree
├── deps
│   └── base
└── license
    └── Apache-2.0

parameter
(unnamed-sequence-string)
→
(or/c string?
      (-> (or/c simple-dictionary? simple-sequence?)
          string?))
(unnamed-sequence-string unnamed) → void?
   unnamed :
(or/c string?
      (-> (or/c simple-dictionary? simple-sequence?)
          string?))
= "<empty>"

This parameter determines the string to use as the root value for anonymous sequences and dictionaries.

Example:

> (displayln (text-tree->string (list (list "date" "May 2024"))))
└── <empty>
├── date
└── May 2024

Example:

> (parameterize ((unnamed-sequence-string "nil"))
    (displayln (text-tree->string (list (list "date" "May 2024")))))
└── nil
    ├── date
    └── May 2024

Examples:

> (define (name-for-unnamed val)
    (cond ((list? val) "empty?")
          ((hash? val) "hash-empty?")))
> (parameterize ((unnamed-sequence-string name-for-unnamed))
    (displayln (text-tree->string (list (list "date" "May 2024")))))
└── empty?
    ├── date
    └── May 2024