Describe

M. Douglas Williams

m.douglas.williams at gmail.com

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

• Booleans

• Numbers

• Strings

• Byte Strings

• Characters

• Symbols

• Regular Expressions

• Byte Regular Expressions

• Keywords

• Lists and Pairs

• Mutable Lists and Pairs

• Vectors

• Boxes

• Weak Boxes

• Hash Tables

• Procedures

• Ports

• Void

• EOF

• Path

• Structures

• Other Named Things

• Other (Unnamed) Things

The describe library is available from the PLaneT repository.

(require (planet williams/describe/describe))

1 Interface

The describe library provides the following functions:

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

(variant (λ (x) x)) -> procedure

(variant 1) -> fixnum-integer

(variant (let/cc k k)) -> continuation

(variant (let/ec k k)) -> escape-continuation

Examples:

(integer->string 0) -> "zero"

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

(integer->string (expt 10 100)) -> "ten duotrigillion"

(integer->string (expt 10 150)) -> "at least 10^102"

Examples: (describe (sqrt 10))
3.1622776601683795 is an inexact positive real number

(describe (sqrt -10))
0+3.1622776601683795i is an inexact positive imaginary number

(describe #\a)
#\a is the character whose code-point number is 97(#x61) and general category is ’ll (letter, lowercase)

(describe '(this is a proper list))
(this is a proper list) is a proper immutable list of length 5

(describe car)
#<procedure:car> is a primitive procedure named car that accepts 1 argument and returns 1 result

2 Example

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

#lang 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.

--- 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 not-a-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

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

The describe function should probably have an optional or keyword argument to specify the output port.

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-describe structure type property.