#lang scribble/doc

@(require scribble/manual
          (planet williams/describe/describe)
          (for-label
           racket
           (planet williams/describe/describe)))

@title[#:tag "describe"]{Describe}

M. Douglas Williams

@tt{M.douglas.williams at gmail.com}

This library provides functions to describe Racket objects. Currently, the following types of objects are described:

@itemize{
  @item{Booleans}
  @item{Numbers}
  @item{Strings}
  @item{Byte Strings}
  @item{Characters}
  @item{Symbols}
  @item{Regular Expressions}
  @item{Byte Regular Expressions}
  @item{Keywords}
  @item{Lists and Pairs}
  @item{Mutable Lists and Pairs}
  @item{Vectors}
  @item{Boxes}
  @item{Weak Boxes}
  @item{Hash Tables}
  @item{Procedures}
  @item{Ports}
  @item{Void}
  @item{EOF}
  @item{Path}
  @item{Structures}
  @item{Other Named Things}
  @item{Other (Unnamed) Things}
  }

The describe library is available from the PLaneT repository.

@defmodule[(planet williams/describe/describe)]

@table-of-contents[]

@section{"Interface"}

The describe library provides the following functions:

@defproc[(variant (x any/c)) symbol?]{
Returns a symbol identifying the type of an object. This is from a post on the Racket mailing list from Robby Findler. The following is a short description of its origin:

... I'm not sure about always, but at some point a while ago, Matthew decided that all values are structs (in the sense that you could have implemented everything with structs and scope, etc even if some of them are implemented in C) and adapted the primitives to make them behave accordingly.}

Examples:

@scheme[(variant (λ (x) x))] -> procedure

@scheme[(variant 1)] -> fixnum-integer

@scheme[(variant (let/cc k k))] -> continuation

@scheme[(variant (let/ec k k))] -> escape-continuation

@defproc[(integer->string (n exact-integer?)) string?]{
Returns a tring with the name of the exact integer n. This works for exact integers whose magnitude is less than 10^102. For values whose magnitudes are greater than or equal to 10^102, the string "at least 10^102" (or "minus at least 10^102") is returned.}

Examples:

@scheme[(integer->string 0)] -> "zero"

@scheme[(integer->string (expt 2 16))] -> "sixty-five thousand five hundred and thirty-six"

@scheme[(integer->string (expt 10 100))] -> "ten duotrigillion"

@scheme[(integer->string (expt 10 150))] -> "at least 10^102"

@defproc[(describe (x any/c)) void?]{
Prints a description of x to the current output port.}

Examples:
@scheme[(describe (sqrt 10))] @linebreak[]
@schemefont{3.1622776601683795 is an inexact positive real number}

@scheme[(describe (sqrt -10))] @linebreak[]
@schemefont{0+3.1622776601683795i is an inexact positive imaginary number}

@scheme[(describe #\a)] @linebreak[]
@schemefont{#\a is the character whose code-point number is 97(#x61) and general category is 'll (letter, lowercase)}

@scheme[(describe '(this is a proper list))] @linebreak[]
@schemefont{(this is a proper list) is a proper immutable list of length 5}

@scheme[(describe car)] @linebreak[]
@schemefont{#<procedure:car> is a primitive procedure named car that accepts 1 argument and returns 1 result}

@defproc[(description (x any/c)) string?]{
Returns a string describing x.}

@section{Example}

The following example demonstrates the varions function of the describe library.

@#reader scribble/comment-reader
(schememod
racket

(require scheme/mpair)
(require (planet williams/describe/describe))

;;; Booleans
(printf "~n--- Booleans ---~n")
(describe #t)
(describe #f)

;;; Numbers
(printf "~n--- Numbers ---~n")

(define (! n)
  (if (= n 0)
      1
      (* n (! (sub1 n)))))

(describe +inf.0)
(describe -inf.0)
(describe +nan.0)

(describe 0)
(describe (! 10))
(describe (! 40))
(describe (- (! 40) (! 41)))
(describe (! 100))
(describe (/ (! 10) (add1 (! 11))))
(describe -1+3i)

(describe 0.0)
(describe (* (! 10) 1.0))
(describe (exact->inexact (! 40)))
(describe (sqrt 10))
(describe (sqrt -10))
(describe (+ (sqrt 10) (sqrt -10)))

;;; Strings

(printf "~n--- Strings ---~n")
(describe "abc")
(describe (string #\1 #\2 #\3))

;;; Byte Strings

(printf "~n--- Byte Strings ---~n")
(describe #"abc")
(describe (bytes 48 49 50))

;;; Characters

(printf "~n--- Characters ---~n")
(describe #\a)
(describe #\A)
(describe #\0)
(describe #\()

;;; Symbols

(printf "~n--- Symbols ---~n")
(describe 'abc)
(describe '|(a + b)|)
(describe (gensym))

;;; Regular Expressions

(printf "~n--- Regular Expressions ---~n")
(describe #rx"Ap*le")
(describe #px"Ap*le")

;;; Byte Regular Expressions

(printf "~n--- Byte Regular Expressions ---~n")
(describe #rx#"Ap*le")
(describe #px#"Ap*le")

;;; Keywords

(printf "~n--- Keywords ---~n")
(describe '#:key)

;;; Lists and Pairs

(printf "~n--- Lists and Pairs ---~n")
(describe '(this is a proper list))
(describe '(this is an improper . list))
(describe (list '(this . is) '(also . a) '(proper . list)))

;;; Mutable Lists and Pairs

(printf "~n--- Mutable Lists and Pairs ---~n")
(describe (mlist 'this 'is 'a 'proper 'list))
(describe (mcons 'this (mcons 'is (mcons 'an (mcons 'improper 'list)))))
(describe (mlist '(this . is) '(also . a) '(proper . list)))

;;; Vectors

(printf "~n--- Vectors ---~n")
(describe #(1 2 3))

;;; Boxes

(printf "~n--- Boxes ---~n")
(describe (box 12))
(describe (box (box 'a)))
(describe (box (sqrt 10)))

;;; Weak Boxes

(printf "~n--- Weak Boxes ---~n")
(describe (make-weak-box 12))
(describe (make-weak-box (make-weak-box 'a)))
(describe (make-weak-box (sqrt 10)))

;;; Hashes

(printf "~n--- Hashes ---~n")
(describe #hash((a . 12) (b . 14) (c . 16)))
(describe #hasheq((a . a) (b . b) (c . c)))
(describe #hasheqv((a . #\a) (b . #\b) (c . #\c)))

(define ht (make-hash))
(hash-set! ht 'a 12)
(hash-set! ht 'b 14)
(hash-set! ht 'c 16)
(describe ht)

(define wht (make-weak-hash))
(hash-set! wht 'a 12)
(hash-set! wht 'b 14)
(hash-set! wht 'c 16)
(describe wht)

;;; Procedures

(printf "~n--- Procedures ---~n")
(describe car)
(describe open-output-file)
(describe current-input-port)
(describe (lambda (x) x))

;;; Ports

(printf "~n--- Ports ---~n")
(describe (current-input-port))
(describe (current-output-port))

;;; Void

(printf "~n--- Void ---~n")
(describe (void))

;;; EOF

(printf "~n--- EOF ---~n")
(describe eof)

;;; Paths

(printf "~n--- Paths ---~n")
(describe (string->path "C:\\Program-files\\PLT"))
(describe (string->path "../dir/file.ext"))

;;; Structures

(printf "~n--- Structures ---~n")
(define-struct transparent-struct (a b c) #:transparent)
(define ts-1 (make-transparent-struct 'a 'b 'c))
(describe ts-1)

;;; Other Named Things (I.E., Opaque Structures)

(printf "~n--- Other Named Things ---~n")
(define-struct opaque-struct (a b c))
(define os-1 (make-opaque-struct 'a 'b 'c))
(describe os-1)
)

Produces the following output.

@verbatim{

--- Booleans ---
#t is a Boolean true
#f is a Boolean false

--- Numbers ---
+inf.0 is positive infinity
-inf.0 is negative infinity
+nan.0 is an inexact positive real number
0 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) zero
3628800 is an exact positive integer fixnum three million six hundred twenty-eight thousand eight hundred
815915283247897734345611269596115894272000000000 is an exact positive integer eight hundred fifteen quattuordecillion nine hundred fifteen tredecillion two hundred eighty-three duodecillion two hundred forty-seven undecillion eight hundred ninety-seven decillion seven hundred thirty-four nonillion three hundred forty-five octillion six hundred eleven septillion two hundred sixty-nine sextillion five hundred ninety-six quintillion one hundred fifteen quadrillion eight hundred ninety-four trillion two hundred seventy-two billion
-32636611329915909373824450783844635770880000000000 is an exact negative integer minus thirty-two quindecillion six hundred thirty-six quattuordecillion six hundred eleven tredecillion three hundred twenty-nine duodecillion nine hundred fifteen undecillion nine hundred nine decillion three hundred seventy-three nonillion eight hundred twenty-four octillion four hundred fifty septillion seven hundred eighty-three sextillion eight hundred forty-four quintillion six hundred thirty-five quadrillion seven hundred seventy trillion eight hundred eighty billion
93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000 is an exact positive integer value whose absolute value is >= 10^102
3628800/39916801 is an exact positive rational number with a numerator of 3628800 and a denominator of 39916801
-1+3i is an exact complex number whose magnitude is 3.1622776601683795
0.0 is an inexact integer zero
3628800.0 is an inexact positive integer
8.159152832478977e+047 is an inexact positive integer
3.1622776601683795 is an inexact positive real number
0+3.1622776601683795i is an inexact positive imaginary number
3.1622776601683795+3.1622776601683795i is an inexact complex number whose magnitude is 4.47213595499958

--- Strings ---
"abc" is an immutable string of length 3
"123" is a mutable string of length 3

--- Byte Strings ---
#"abc" is an immutable byte string of length 3
#"012" is a mutable byte string of length 3

--- Characters ---
#\a is a character whose code-point number is 97(#x61) and general category is 'll (letter, lowercase)
#\A is a character whose code-point number is 65(#x41) and general category is 'lu (letter, uppercase)
#\0 is a character whose code-point number is 48(#x30) and general category is 'nd (number, decimal digit)
#\( is a character whose code-point number is 40(#x28) and general category is 'ps (punctuation, open)

--- Symbols ---
abc is an interned symbol
|(a + b)| is an interned symbol
g890 is an uninterned symbol

--- Regular Expressions ---
#rx"Ap*le" is a regular expression in regexp format
#px"Ap*le" is a regular expression in pregexp format

--- Byte Regular Expressions ---
#rx#"Ap*le" is a byte regular expression in regexp format
#px#"Ap*le" is a byte regular expression in pregexp format

--- Keywords ---
#:key is a keyword

--- Lists and Pairs ---
(this is a proper list) is a proper immutable list of length 5
(this is an improper . list) is an improper immutable list
((this . is) (also . a) (proper . list)) is a proper immutable list of length 3

--- Mutable Lists and Pairs ---
{this is a proper list} is a proper mutable list of length 5
{this is an improper . list} is an improper mutable list
{(this . is) (also . a) (proper . list)} is a proper mutable list of length 3

--- Vectors ---
#(1 2 3) is an immutable vector of length 3

--- Boxes ---
#&12 is a box containing 12, 12 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) twelve
#&#&a is a box containing #&a, #&a is a box containing a, a is an interned symbol
#&3.1622776601683795 is a box containing 3.1622776601683795, 3.1622776601683795 is an inexact positive real number

--- Weak Boxes ---
#<weak-box> is a weak box containing 12, 12 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) twelve
#<weak-box> is a weak box containing #<weak-box>, #<weak-box> is a weak box containing a, a is an interned symbol
#<weak-box> is a weak box containing 3.1622776601683795, 3.1622776601683795 is an inexact positive real number

--- Hashes ---
#hash((a . 12) (c . 16) (b . 14)) is an immutable hash table and that uses equal? to compare keys
  a : 12, 12 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) twelve
  c : 16, 16 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) sixteen
  b : 14, 14 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) fourteen
#hasheq((a . a) (c . c) (b . b)) is an immutable hash table and that uses eq? to compare keys
  a : a, a is an interned symbol
  c : c, c is an interned symbol
  b : b, b is an interned symbol
#hasheqv((a . #\a) (c . #\c) (b . #\b)) is an immutable hash table and that uses eqv? to compare keys
  a : #\a, #\a is a character whose code-point number is 97(#x61) and general category is 'll (letter, lowercase)
  c : #\c, #\c is a character whose code-point number is 99(#x63) and general category is 'll (letter, lowercase)
  b : #\b, #\b is a character whose code-point number is 98(#x62) and general category is 'll (letter, lowercase)
#hash((a . 12) (b . 14) (c . 16)) is a mutable hash table and that uses equal? to compare keys
  a : 12, 12 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) twelve
  b : 14, 14 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) fourteen
  c : 16, 16 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) sixteen
#<hash> is a mutable hash table that holds its keys weakly and that uses equal? to compare keys
  a : 12, 12 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) twelve
  c : 16, 16 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) sixteen
  b : 14, 14 is a byte (i.e., an exact positive integer fixnum between 0 and 255 inclusive) fourteen

--- Procedures ---
#<procedure:car> is a primitive procedure named car that accepts 1 argument and returns 1 result
#<procedure:open-output-file> is a procedure named open-output-file that accepts 1 argument plus optional keyword arguments #:exists and #:mode
#<procedure:current-input-port> is a primitive procedure named current-input-port that accepts 0 or 1 arguments and returns 1 result
#<procedure:...escribe-test.rkt:156:10> is a procedure named ...escribe-test.rkt:156:10 that accepts 1 argument

--- Ports ---
#<input-port:unsaved-editor779> is an open input port
#<output-port> is an open output port

--- Void ---
#<void> is void

--- EOF ---
#<eof> is an eof object

--- Paths ---
#<path:C:\Program-files\PLT> is a complete, absolute windows path
#<path:../dir/file.ext> is an incomplete, relative windows path

--- Structures ---
#(struct:transparent-struct a b c) is a structure of type transparent-struct
  1 : a, a is an interned symbol
  2 : b, b is an interned symbol
  3 : c, c is an interned symbol

--- Other Named Things ---
#<opaque-struct> is an object of type opaque-struct
}

@section{Issues and Comments}

There are undoubtably object types that I have missed and, since Racket is a language that is being actively developed, new object types are sometimes added. If you come across something that is missing, either send me an e-mail or post it on the Racket mailing list.

It would be nice to come up with a way to allow developers to extend the describe library for new object types. Perhaps via something like a prop:custom-description structure type property.