Rename README → README.orgHEADmaster

This makes it easier to know how to format it on the server side.

1 files changed, 0 insertions, 112 deletions

diff --git a/README b/README
deleted file mode 100644
index 0688a73..0000000
--- a/README
+++ /dev/null
@@ -1,112 +0,0 @@
-# -*- mode: org -*-
-
-* Overview
-A test consists of a config file, which specifies variables available
-during the execution of the test, a test plan file, which dictates the
-order of the test, and a series of templates, referenced by the test
-plan, which contain the data to be read and optionally matched. See
-the Testing section for an example of how to use it.
-
-This is intended to be used for request-response style interactions,
-where we send a request and wait for a matching response. However, not
-all requests stimulate a response, so response matching is optional.
-
-By default this program reads from standard input and writes to
-standard output, but if a command line is supplied as the final
-arguments, that will be used instead. This is useful with netcat for
-network server testing.
-
-* Config File
-The format of the config file is a list of arbitrary '$key=$value'
-pairs. Comments start with '#' and continue until the end of the line.
-
-Config keys are auto-interned as nullary functions for use in
-templates.
-
-* Test Plan
-The test plan file is a list of files to run within the templates
-directory (which defaults to 'xml'), suffixed by '.xml' for sending
-data, and, if it exists, suffixed by '.expected.xml' for matching
-responses. Thus a test plan line which consists of 'foo' would send
-data according to the template in 'xml/foo.xml' and would then wait
-for data matching the template in 'xml/foo.expected.xml' if that file
-exists.
-
-The XML stuff is not ideal, since this program doesn't care about the
-format of the data being read or written, but since it was developed
-for XMPP testing, that's what it got. This may change in the future.
-
-* Templates
-Templates are fundamentally a big regexp with thunks of Perl code
-contained within '{}' interpolated at run-time. While templates are
-used for both sending data and matching received data, the use of
-thunks changes depending on context.
-
-** Send context
-In send context (e.g., 'foo.xml'), the code called may return a string
-which will replace the thunk in the template. Assuming you have a
-function defined called bar:
-#+BEGIN
-sub bar() { "text" };
-#+END
-
-and a template:
-#+BEGIN
-Here is some {bar}!
-#+END
-
-The output would be:
-#+BEGIN
-Here is some text!
-#+END
-
-The code is arbitrary Perl 5, and doesn't have to return a string, but
-if it returns anything it should be something that can be converted to
-a string automatically, or you're likely to get an error.
-
-** Match context
-During matching, the template is processed as a regexp, where thunks
-are treated as captured wildcards (i.e., the pattern '(.*)'). After a
-successful match, the value of the capture is made available to the
-thunk in the $arg variable. This is so that the value can be compared
-with an expected value, or that more complex computation can be done
-(such as for challenge-response authentication).
-
-It is assumed that there will be cases where data that you're not
-interested in can be interleaved in data that you are interested in
-(e.g., keepalives) and match templates will ignore them.
-
-** Evaluation package
-Templates are evaluated in their own package, outside of main, to
-better isolate their side-effects. Some package-level globals are made
-available:
-  * $in - The filehandle we're reading match data from.
-  * $out - The filehandle we're sending data to.
-  * %env - The key-value pairs from the loaded config file.
-  * $arg - The value of the capture group for this thunk (in match
-           context)
-
-This package is never reinitialized during the test plan execution,
-allowing one template to modify data for subsequent templates.
-
-** XML
-In order to make XML processing easier any type of quote, throughout
-the text, is turned into the pattern ['"] during match
-context. Similarly, whitespace is condensed and replaced with the \s*
-pattern.
-
-Do note that while this program is intended to be used primarily with
-XML, it's almost totally ignorant of XML as a format besides the above
-substitutions. That means that things like attribute order within a
-tag matter, and we cannot normalize '<foo></foo>' to '<foo/>' (at
-least unless you write a big tangle of regexp in the template itself).
-
-* Testing
-The file 'testplan' contains a sample plan for a basic XMPP session
-given 'localhost.conf', using the files in the 'xml' directory. The
-corresponding server data is in 'input'. So to run a quick-and-dirty
-test, execute:
-
-#+BEGIN
-% xmpt -e t/fixtures/sample.env -p t/fixtures/sample.plan < t/fixtures/sample.input
-#+END