projects
/
cl-mock.git
/ commitdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
| commitdiff |
tree
raw
|
patch
|
inline
| side by side (parent:
f6b59f2
)
Add introduction paragraph.
author
Olof-Joachim Frahm
<olof@macrolet.net>
Wed, 17 Dec 2014 20:42:43 +0000
(20:42 +0000)
committer
Olof-Joachim Frahm
<olof@macrolet.net>
Wed, 17 Dec 2014 20:44:52 +0000
(20:44 +0000)
README.md
patch
|
blob
|
history
diff --git
a/README.md
b/README.md
index
ad9bcb6
..
d453b5a
100644
(file)
--- a/
README.md
+++ b/
README.md
@@
-2,7
+2,7
@@
CL-MOCK - Mocking (generic) functions.
CL-MOCK - Mocking (generic) functions.
-Copyright (C) 2013 Olof-Joachim Frahm
+Copyright (C) 2013-14 Olof-Joachim Frahm
Release under a Simplified BSD license.
Release under a Simplified BSD license.
@@
-10,22
+10,43
@@
Working, but unfinished.
Should be portable thanks to [`CLOSER-MOP`][1].
Should be portable thanks to [`CLOSER-MOP`][1].
+
+# INTRODUCTION
+
+This small library provides a way to replace the actual implementation
+of either regular or generic functions with mocks. How to integrate
+this facility with a testing library is up to the user; the tests for
+the library are written in [`FIVEAM`][2] though, so most examples will
+take that into account.
+
Since it is pretty easy to just roll something like this on your own,
Since it is pretty easy to just roll something like this on your own,
-the main purpose is to develop a nice syntax (lispy, declarative) to
-keep tests readable and maintainable.
+the main purpose is to develop a nice (lispy, declarative) syntax to
+keep your tests readable and maintainable.
Some parts may be used independently of the testing facilities,
e.g. dynamic `FLET` and method bindings with `PROGM` may be of general
interest.
Some parts may be used independently of the testing facilities,
e.g. dynamic `FLET` and method bindings with `PROGM` may be of general
interest.
+# MOCKING CONTEXT
+
+In addition to having macros and functions to install bindings into the
+mocking context, the actual context object may be retrieved and passed
+around as well. This might be useful for further analysis or other
+helpers.
+
+
# GENERIC FUNCTIONS
Since behaviour isn't bound to classes, but to generic functions,
# GENERIC FUNCTIONS
Since behaviour isn't bound to classes, but to generic functions,
-creating new classes on the fly isn't particularly interesting.
+creating new classes on the fly isn't particularly interesting. If
+necessary, additional shortcuts will be added, but until then I don't
+see the need for this. On the contrary, providing a way to temporarily
+supersede generic function bindings sounds like a more viable approach,
+especially with regards to (custom) method combinations.
-We provide the form `PROGM` to bind a number of methods during the
-execution of its contained body:
+Thus, the form `PROGM` is provided to bind a number of methods during
+the execution of its body:
> (progm
> '((baz NIL (list)))
> (progm
> '((baz NIL (list)))
@@
-44,6
+65,9
@@
For example:
> => 42
> => (1 2 3)
> => 42
> => (1 2 3)
+This is implemented via [`CLOSER-MOP`][1], so compatiblity with that
+library is required.
+
# UTILITIES
# UTILITIES
@@
-58,11
+82,14
@@
For example:
> => 23
> (OR) => 42, if FOO was inlined
> => 23
> (OR) => 42, if FOO was inlined
-The caveat is that this might not work on certain optimization settings,
-including inlining.
+The caveat is that this might not work on certain optimisation settings,
+including inlining. That trade-off seems acceptable; it would be nice
+if a warning could be issued depending on the current optimisation
+settings, however that is particularly implementation dependent, so lack
+of a warning won't indicate a working environment.
-The underlying function `PROGF` may be used as well similarly to standard
-`PROG`:
+The underlying function `PROGF` may be used as well similarly to the
+standard `PROG`:
> (progf '(foo) (list (lambda () 23))
> (bar))
> (progf '(foo) (list (lambda () 23))
> (bar))