From ead1bffcbb443b339cd65488994cde6d271781c3 Mon Sep 17 00:00:00 2001 From: Olof-Joachim Frahm Date: Wed, 17 Dec 2014 20:42:43 +0000 Subject: [PATCH] Add introduction paragraph. --- README.md | 47 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ad9bcb6..d453b5a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ CL-MOCK - Mocking (generic) functions. -Copyright (C) 2013 Olof-Joachim Frahm +Copyright (C) 2013-14 Olof-Joachim Frahm Release under a Simplified BSD license. @@ -10,22 +10,43 @@ Working, but unfinished. 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, -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. +# 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, -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))) @@ -44,6 +65,9 @@ For example: > => 42 > => (1 2 3) +This is implemented via [`CLOSER-MOP`][1], so compatiblity with that +library is required. + # UTILITIES @@ -58,11 +82,14 @@ For example: > => 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)) -- 1.7.10.4