--- a/DOCUMENTATION.markdown Wed Aug 17 00:10:00 2016 +0000
+++ b/DOCUMENTATION.markdown Wed Aug 17 00:46:28 2016 +0000
@@ -10,52 +10,129 @@
## Package `LOSH`
+This package exports all of the symbols in the other packages.
+
+ If you just want to get everything you can `:use` this one and be done with
+ it. Otherwise you can `:use` only the ones you need.
+
+
+
+## Package `LOSH.ARRAYS`
+
+Utilities related to arrays.
+
+### `DO-ARRAY` (macro)
+
+ (DO-ARRAY (VALUE ARRAY)
+ &BODY
+ BODY)
+
+Perform `body` once for each element in `array` using `value` for the place.
+
+ `array` can be multidimensional.
+
+ `value` will be `symbol-macrolet`ed to the appropriate `aref`, so you can use
+ it as a place if you want.
+
+ Returns the array.
+
+ Example:
+
+ (let ((arr (vector 1 2 3)))
+ (do-array (x arr)
+ (setf x (1+ x))))
+ => #(2 3 4)
+
+
+
+## Package `LOSH.CONTROL-FLOW`
+
+Utilities for managing control flow.
+
+### `RECURSIVELY` (macro)
+
+ (RECURSIVELY BINDINGS
+ &BODY
+ BODY)
+
+Execute body recursively, like Clojure's `loop`/`recur`.
+
+ `bindings` should contain a list of symbols and (optional) default values.
+
+ In `body`, `recur` will be bound to the function for recurring.
+
+ Example:
+
+ (defun length (some-list)
+ (recursively ((list some-list) (n 0))
+ (if (null list)
+ n
+ (recur (cdr list) (1+ n)))))
+
+
+
+## Package `LOSH.DEBUGGING`
+
+Utilities for figuring out what the hell is going on.
+
### `BITS` (function)
(BITS N SIZE)
-### `CALLF` (macro)
+### `DIS` (macro)
- (CALLF &REST PLACE-FUNCTION-PAIRS)
-
-Set each `place` to the result of calling `function` on its current value.
+ (DIS ARGLIST
+ &BODY
+ BODY)
- Examples:
+Disassemble the code generated for a `lambda` with `arglist` and `body`.
- (let ((x 10) (y 20))
- (callf x #'1-
- y #'1+)
- (list x y))
- =>
- (9 21)
+ It will also spew compiler notes so you can see why the garbage box isn't
+ doing what you think it should be doing.
+
-### `CLAMP` (function)
+### `PR` (function)
- (CLAMP FROM TO VALUE)
-
-Clamp `value` between `from` and `to`.
+ (PR &REST ARGS)
-### `CLAMPF` (macro)
+## Package `LOSH.DISTRIBUTIONS`
- (CLAMPF PLACE FROM TO &ENVIRONMENT ENV)
+Utilities for calculating statistical... things.
-Clamp `place` between `from` and `to` in-place.
+### `FREQUENCIES` (function)
-### `D` (function)
+ (FREQUENCIES SEQ &KEY (TEST 'EQL))
- (D N SIDES &OPTIONAL (PLUS 0))
+Return a hash table containing the feqeuencies of the items in `seq`.
-Roll some dice.
+ Uses `test` for the `:test` of the hash table.
- Examples:
+ Example:
- (d 1 4) ; rolls 1d4
- (d 2 8) ; rolls 2d8
- (d 1 10 -1) ; rolls 1d10-1
+ (frequencies '(foo foo bar))
+ => {foo 2
+ bar 1}
+### `PREFIX-SUMS` (function)
+
+ (PREFIX-SUMS LIST)
+
+Return a list of the prefix sums of the numbers in `list`.
+
+ Example:
+
+ (prefix-sums '(10 10 10 0 1))
+ => (10 20 30 30 31)
+
+
+
+## Package `LOSH.ELDRITCH-HORRORS`
+
+Abandon all hope, ye who enter here.
+
### `DEFINE-WITH-MACRO` (macro)
(DEFINE-WITH-MACRO TYPE &REST SLOTS)
@@ -97,107 +174,30 @@
-### `DEQUEUE` (function)
-
- (DEQUEUE Q)
-
-### `DIS` (macro)
-
- (DIS ARGLIST
- &BODY
- BODY)
-
-Disassemble the code generated for a `lambda` with `arglist` and `body`.
-
- It will also spew compiler notes so you can see why the garbage box isn't
- doing what you think it should be doing.
-
-
-
-### `DIVF` (macro)
-
- (DIVF PLACE &OPTIONAL DIVISOR &ENVIRONMENT ENV)
-
-Divide `place` by `divisor` in-place.
-
- If `divisor` is not given, `place` will be set to `(/ 1 place).
-
-
-
-### `DIVIDESP` (function)
-
- (DIVIDESP N DIVISOR)
-
-Return whether `n` is evenly divisible by `divisor`.
-
### `DLAMBDA` (macro)
(DLAMBDA &REST CLAUSES)
-### `DO-ARRAY` (macro)
-
- (DO-ARRAY (VALUE ARRAY)
- &BODY
- BODY)
+## Package `LOSH.FILE-IO`
-Perform `body` once for each element in `array` using `value` for the place.
-
- `array` can be multidimensional.
-
- `value` will be `symbol-macrolet`ed to the appropriate `aref`, so you can use
- it as a place if you want.
-
- Returns the array.
+Utilities for reading from and writing to files.
- Example:
-
- (let ((arr (vector 1 2 3)))
- (do-array (x arr)
- (setf x (1+ x))))
- => #(2 3 4)
+### `SLURP` (function)
-
-
-### `ENQUEUE` (function)
-
- (ENQUEUE ITEM Q)
-
-### `FREQUENCIES` (function)
-
- (FREQUENCIES SEQ &KEY (TEST 'EQL))
+ (SLURP PATH)
-Return a hash table containing the feqeuencies of the items in `seq`.
-
- Uses `test` for the `:test` of the hash table.
-
- Example:
+Sucks up an entire file from PATH into a freshly-allocated string,
+ returning two values: the string and the number of bytes read.
- (frequencies '(foo foo bar))
- => {foo 2
- bar 1}
-
-
-
-### `GETHASH-OR-INIT` (macro)
-
- (GETHASH-OR-INIT KEY HASH-TABLE DEFAULT-FORM)
+### `SPIT` (function)
-Get `key`'s value in `hash-table`, initializing if necessary.
+ (SPIT PATH STR)
- If `key` is in `hash-table`: return its value without evaluating
- `default-form` at all.
-
- If `key` is NOT in `hash-table`: evaluate `default-form` and insert it before
- returning it.
+Spit the string into a file at the given path.
-
-
-### `HASH-SET` (class)
+## Package `LOSH.FUNCTIONS`
-#### Slot `DATA`
-
-* Allocation: `:INSTANCE`
-* Initarg: `:DATA`
+Utilities for working with higher-order functions.
### `JUXT` (function)
@@ -216,6 +216,142 @@
+### `NULLARY` (function)
+
+ (NULLARY FUNCTION &OPTIONAL RESULT)
+
+Return a new function that acts as a nullary-patched version of `function`.
+
+ The new function will return `result` when called with zero arguments, and
+ delegate to `function` otherwise.
+
+ Examples:
+
+ (max 1 10 2) => 10
+ (max) => invalid number of arguments
+
+ (funcall (nullary #'max)) => nil
+ (funcall (nullary #'max 0)) => 0
+ (funcall (nullary #'max 0) 1 10 2) => 10
+
+ (reduce #'max nil) => invalid number of arguments
+ (reduce (nullary #'max) nil) => nil
+ (reduce (nullary #'max :empty) nil) => :empty
+ (reduce (nullary #'max) '(1 10 2)) => 10
+
+
+
+## Package `LOSH.HASH-SETS`
+
+A simple hash set implementation.
+
+### `HASH-SET` (class)
+
+#### Slot `DATA`
+
+* Allocation: `:INSTANCE`
+* Initarg: `:DATA`
+
+### `MAKE-SET` (function)
+
+ (MAKE-SET &KEY (TEST #'EQL) (INITIAL-DATA NIL))
+
+### `SET-ADD` (function)
+
+ (SET-ADD SET VALUE)
+
+### `SET-ADD-ALL` (function)
+
+ (SET-ADD-ALL SET SEQ)
+
+### `SET-CLEAR` (function)
+
+ (SET-CLEAR SET)
+
+### `SET-CONTAINS-P` (function)
+
+ (SET-CONTAINS-P SET VALUE)
+
+### `SET-EMPTY-P` (function)
+
+ (SET-EMPTY-P SET)
+
+### `SET-POP` (function)
+
+ (SET-POP SET)
+
+### `SET-RANDOM` (function)
+
+ (SET-RANDOM SET)
+
+### `SET-REMOVE` (function)
+
+ (SET-REMOVE SET VALUE)
+
+### `SET-REMOVE-ALL` (function)
+
+ (SET-REMOVE-ALL SET SEQ)
+
+## Package `LOSH.HASH-TABLES`
+
+Utilities related to hash tables.
+
+### `GETHASH-OR-INIT` (macro)
+
+ (GETHASH-OR-INIT KEY HASH-TABLE DEFAULT-FORM)
+
+Get `key`'s value in `hash-table`, initializing if necessary.
+
+ If `key` is in `hash-table`: return its value without evaluating
+ `default-form` at all.
+
+ If `key` is NOT in `hash-table`: evaluate `default-form` and insert it before
+ returning it.
+
+
+
+## Package `LOSH.ITERATE`
+
+Custom `iterate` drivers and clauses.
+
+## Package `LOSH.LISTS`
+
+Utilities related to lists.
+
+### `TAKE` (function)
+
+ (TAKE N LIST)
+
+Return a fresh list of the first `n` elements of `list`.
+
+ If `list` is shorter than `n` a shorter result will be returned.
+
+ Example:
+
+ (take 2 '(a b c))
+ => (a b)
+
+ (take 4 '(1))
+ => (1)
+
+
+
+## Package `LOSH.MATH`
+
+Utilities related to math and numbers.
+
+### `CLAMP` (function)
+
+ (CLAMP FROM TO VALUE)
+
+Clamp `value` between `from` and `to`.
+
+### `DIVIDESP` (function)
+
+ (DIVIDESP N DIVISOR)
+
+Return whether `n` is evenly divisible by `divisor`.
+
### `LERP` (function)
(LERP FROM TO N)
@@ -226,14 +362,6 @@
-### `MAKE-QUEUE` (function)
-
- (MAKE-QUEUE)
-
-### `MAKE-SET` (function)
-
- (MAKE-SET &KEY (TEST #'EQL) (INITIAL-DATA NIL))
-
### `MAP-RANGE` (function)
(MAP-RANGE SOURCE-FROM SOURCE-TO DEST-FROM DEST-TO SOURCE-VAL)
@@ -248,6 +376,62 @@
+### `NORM` (function)
+
+ (NORM MIN MAX VAL)
+
+Normalize `val` to a number between `0` and `1` (maybe).
+
+ If `val` is between `max` and `min`, the result will be a number between `0`
+ and `1`.
+
+ If `val` lies outside of the range, it'll be still be scaled and will end up
+ outside the 0/1 range.
+
+
+
+### `SQUARE` (function)
+
+ (SQUARE X)
+
+### `TAU` (variable)
+
+## Package `LOSH.MUTATION`
+
+Utilities for mutating places in-place.
+
+### `CALLF` (macro)
+
+ (CALLF &REST PLACE-FUNCTION-PAIRS)
+
+Set each `place` to the result of calling `function` on its current value.
+
+ Examples:
+
+ (let ((x 10) (y 20))
+ (callf x #'1-
+ y #'1+)
+ (list x y))
+ =>
+ (9 21)
+
+
+### `CLAMPF` (macro)
+
+ (CLAMPF PLACE FROM TO &ENVIRONMENT ENV)
+
+Clamp `place` between `from` and `to` in-place.
+
+### `DIVF` (macro)
+
+ (DIVF PLACE &OPTIONAL DIVISOR &ENVIRONMENT ENV)
+
+Divide `place` by `divisor` in-place.
+
+ If `divisor` is not given, `place` will be set to `(/ 1 place).
+
+
+
### `MODF` (macro)
(MODF PLACE DIVISOR &ENVIRONMENT ENV)
@@ -266,36 +450,43 @@
Negate the value of `place`.
-### `NORM` (function)
+### `REMAINDERF` (macro)
+
+ (REMAINDERF PLACE DIVISOR &ENVIRONMENT ENV)
- (NORM MIN MAX VAL)
+Remainder `place` by `divisor` in-place.
-Normalize `val` to a number between `0` and `1` (maybe).
+### `ZAPF` (macro)
+
+ (ZAPF &REST PLACE-EXPR-PAIRS &ENVIRONMENT ENV)
- If `val` is between `max` and `min`, the result will be a number between `0`
- and `1`.
+Update each `place` by evaluating `expr` with `%` bound to the current value.
+
+ `zapf` works like `setf`, but when evaluating the value expressions the symbol
+ `%` will be bound to the current value of the place.
- If `val` lies outside of the range, it'll be still be scaled and will end up
- outside the 0/1 range.
+ Examples:
+
+ (zapf foo (1+ %)
+ (car bar) (if (> % 10) :a :b))
-### `PR` (function)
+## Package `LOSH.QUEUES`
- (PR &REST ARGS)
+A simple queue implementation.
-### `PREFIX-SUMS` (function)
+### `DEQUEUE` (function)
- (PREFIX-SUMS LIST)
+ (DEQUEUE Q)
-Return a list of the prefix sums of the numbers in `list`.
+### `ENQUEUE` (function)
- Example:
+ (ENQUEUE ITEM Q)
- (prefix-sums '(10 10 10 0 1))
- => (10 20 30 30 31)
+### `MAKE-QUEUE` (function)
-
+ (MAKE-QUEUE)
### `QUEUE`
@@ -317,6 +508,24 @@
(QUEUE-SIZE VALUE INSTANCE)
+## Package `LOSH.RANDOM`
+
+Utilities related to randomness.
+
+### `D` (function)
+
+ (D N SIDES &OPTIONAL (PLUS 0))
+
+Roll some dice.
+
+ Examples:
+
+ (d 1 4) ; rolls 1d4
+ (d 2 8) ; rolls 2d8
+ (d 1 10 -1) ; rolls 1d10-1
+
+
+
### `RANDOM-AROUND` (function)
(RANDOM-AROUND VALUE SPREAD)
@@ -373,86 +582,9 @@
Return a random boolean with `chance` probability of `t`.
-### `RECURSIVELY` (macro)
-
- (RECURSIVELY BINDINGS
- &BODY
- BODY)
-
-Execute body recursively, like Clojure's `loop`/`recur`.
-
- `bindings` should contain a list of symbols and (optional) default values.
-
- In `body`, `recur` will be bound to the function for recurring.
-
- Example:
-
- (defun length (some-list)
- (recursively ((list some-list) (n 0))
- (if (null list)
- n
- (recur (cdr list) (1+ n)))))
-
-
-
-### `REMAINDERF` (macro)
-
- (REMAINDERF PLACE DIVISOR &ENVIRONMENT ENV)
-
-Remainder `place` by `divisor` in-place.
-
-### `SET-ADD` (function)
-
- (SET-ADD SET VALUE)
-
-### `SET-ADD-ALL` (function)
-
- (SET-ADD-ALL SET SEQ)
-
-### `SET-CLEAR` (function)
-
- (SET-CLEAR SET)
+## Package `LOSH.SYMBOLS`
-### `SET-CONTAINS-P` (function)
-
- (SET-CONTAINS-P SET VALUE)
-
-### `SET-EMPTY-P` (function)
-
- (SET-EMPTY-P SET)
-
-### `SET-POP` (function)
-
- (SET-POP SET)
-
-### `SET-RANDOM` (function)
-
- (SET-RANDOM SET)
-
-### `SET-REMOVE` (function)
-
- (SET-REMOVE SET VALUE)
-
-### `SET-REMOVE-ALL` (function)
-
- (SET-REMOVE-ALL SET SEQ)
-
-### `SLURP` (function)
-
- (SLURP PATH)
-
-Sucks up an entire file from PATH into a freshly-allocated string,
- returning two values: the string and the number of bytes read.
-
-### `SPIT` (function)
-
- (SPIT PATH STR)
-
-Spit the string into a file at the given path.
-
-### `SQUARE` (function)
-
- (SQUARE X)
+Utilities related to symbols.
### `SYMBOLIZE` (function)
@@ -467,39 +599,3 @@
-### `TAKE` (function)
-
- (TAKE N LIST)
-
-Return a fresh list of the first `n` elements of `list`.
-
- If `list` is shorter than `n` a shorter result will be returned.
-
- Example:
-
- (take 2 '(a b c))
- => (a b)
-
- (take 4 '(1))
- => (1)
-
-
-
-### `TAU` (variable)
-
-### `ZAPF` (macro)
-
- (ZAPF &REST PLACE-EXPR-PAIRS &ENVIRONMENT ENV)
-
-Update each `place` by evaluating `expr` with `%` bound to the current value.
-
- `zapf` works like `setf`, but when evaluating the value expressions the symbol
- `%` will be bound to the current value of the place.
-
- Examples:
-
- (zapf foo (1+ %)
- (car bar) (if (> % 10) :a :b))
-
-
-
--- a/losh.lisp Wed Aug 17 00:10:00 2016 +0000
+++ b/losh.lisp Wed Aug 17 00:46:28 2016 +0000
@@ -958,9 +958,9 @@
(format s "~A" str)))
-;;;; dlambda
-;;; From Let Over Lambda.
+;;;; Eldritch Horrors
(defmacro dlambda (&rest clauses)
+ ;;; From Let Over Lambda.
(with-gensyms (message arguments)
(flet ((parse-clause (clause)
(destructuring-bind (key arglist &rest body)
@@ -970,8 +970,6 @@
(ecase ,message
,@(mapcar #'parse-clause clauses))))))
-
-;;;; Eldritch Horrors
(defmacro define-with-macro (type &rest slots)
"Define a with-`type` macro for the given `type` and `slots`.
--- a/make-docs.lisp Wed Aug 17 00:10:00 2016 +0000
+++ b/make-docs.lisp Wed Aug 17 00:46:28 2016 +0000
@@ -1,7 +1,26 @@
(ql:quickload "cl-d-api")
(defparameter *document-packages*
- (list "LOSH"))
+ (list "LOSH"
+
+ "LOSH.ARRAYS"
+ "LOSH.CONTROL-FLOW"
+ "LOSH.DEBUGGING"
+ "LOSH.DISTRIBUTIONS"
+ "LOSH.ELDRITCH-HORRORS"
+ "LOSH.FILE-IO"
+ "LOSH.FUNCTIONS"
+ "LOSH.HASH-SETS"
+ "LOSH.HASH-TABLES"
+ "LOSH.ITERATE"
+ "LOSH.LISTS"
+ "LOSH.MATH"
+ "LOSH.MUTATION"
+ "LOSH.QUEUES"
+ "LOSH.RANDOM"
+ "LOSH.SYMBOLS"
+
+ ))
(defparameter *output-path*
#p"DOCUMENTATION.markdown" )
--- a/package.lisp Wed Aug 17 00:10:00 2016 +0000
+++ b/package.lisp Wed Aug 17 00:46:28 2016 +0000
@@ -1,11 +1,41 @@
+(defpackage #:losh.internal
+ (:use #:cl))
+
+(in-package #:losh.internal)
+
+(defun reexport (source-package &optional (target-package '#:losh))
+ (do-external-symbols (s (find-package source-package))
+ (import s (find-package target-package))
+ (export s (find-package target-package))))
+
+(defmacro defsubpackage (name &rest args)
+ `(progn
+ (defpackage ,name ,@args)
+ (reexport ',name)))
+
+
(defpackage #:losh
(:use
#:cl
#:iterate
#:losh.quickutils)
+ (:documentation
+ "This package exports all of the symbols in the other packages.
+
+ If you just want to get everything you can `:use` this one and be done with
+ it. Otherwise you can `:use` only the ones you need.
+
+ "))
+
+
+(defsubpackage #:losh.symbols
+ (:documentation "Utilities related to symbols.")
(:export
- #:symbolize
+ #:symbolize))
+(defsubpackage #:losh.math
+ (:documentation "Utilities related to math and numbers.")
+ (:export
#:tau
#:square
#:dividesp
@@ -13,8 +43,11 @@
#:lerp
#:precide-lerp
#:map-range
- #:clamp
+ #:clamp))
+(defsubpackage #:losh.random
+ (:documentation "Utilities related to randomness.")
+ (:export
#:randomp
#:random-elt
#:random-range
@@ -22,13 +55,23 @@
#:random-around
#:random-gaussian
#:random-gaussian-integer
- #:d
+ #:d))
+(defsubpackage #:losh.functions
+ (:documentation "Utilities for working with higher-order functions.")
+ (:export
#:juxt
+ #:nullary))
+(defsubpackage #:losh.control-flow
+ (:documentation "Utilities for managing control flow.")
+ (:export
#:recursively
- #:recur
+ #:recur))
+(defsubpackage #:losh.mutation
+ (:documentation "Utilities for mutating places in-place.")
+ (:export
#:zapf
#:%
#:mulf
@@ -37,14 +80,26 @@
#:remainderf
#:clampf
#:negatef
- #:callf
+ #:callf))
- #:take
+(defsubpackage #:losh.lists
+ (:documentation "Utilities related to lists.")
+ (:export
+ #:take))
- #:do-array
+(defsubpackage #:losh.arrays
+ (:documentation "Utilities related to arrays.")
+ (:export
+ #:do-array))
- #:gethash-or-init
+(defsubpackage #:losh.hash-tables
+ (:documentation "Utilities related to hash tables.")
+ (:export
+ #:gethash-or-init))
+(defsubpackage #:losh.queues
+ (:documentation "A simple queue implementation.")
+ (:export
#:queue
#:make-queue
#:queue-contents
@@ -52,8 +107,11 @@
#:queue-empty-p
#:enqueue
#:dequeue
- #:queue-append
+ #:queue-append))
+(defsubpackage #:losh.iterate
+ (:documentation "Custom `iterate` drivers and clauses.")
+ (:export
#:pairs-of-list
#:averaging
#:into
@@ -69,11 +127,17 @@
#:across-flat-array
#:index-of-flat-array
#:cycling
- #:for-nested
+ #:for-nested))
+(defsubpackage #:losh.distributions
+ (:documentation "Utilities for calculating statistical... things.")
+ (:export
#:prefix-sums
- #:frequencies
+ #:frequencies))
+(defsubpackage #:losh.hash-sets
+ (:documentation "A simple hash set implementation.")
+ (:export
#:hash-set
#:make-set
#:set-contains-p
@@ -84,17 +148,26 @@
#:set-remove-all
#:set-clear
#:set-random
- #:set-pop
+ #:set-pop))
+(defsubpackage #:losh.debugging
+ (:documentation "Utilities for figuring out what the hell is going on.")
+ (:export
#:pr
#:bits
- #:dis
+ #:dis))
+(defsubpackage #:losh.file-io
+ (:documentation "Utilities for reading from and writing to files.")
+ (:export
#:slurp
- #:spit
+ #:spit))
+(defsubpackage #:losh.eldritch-horrors
+ (:documentation "Abandon all hope, ye who enter here.")
+ (:export
#:dlambda
+ #:define-with-macro))
- #:define-with-macro
- ))
+;;;; Remember to add it to the docs!