From 33208b87205e08b97af07ed6a55c999990a1b8dc Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Sun, 22 Jul 2012 22:24:16 +1200 Subject: Doc reorg. --- libpathod/app.py | 5 + libpathod/templates/docs_lang.html | 220 +++++++++++++++++++++++++++++++++++ libpathod/templates/docs_pathod.html | 195 +------------------------------ libpathod/templates/frame.html | 1 + 4 files changed, 232 insertions(+), 189 deletions(-) create mode 100644 libpathod/templates/docs_lang.html (limited to 'libpathod') diff --git a/libpathod/app.py b/libpathod/app.py index fd742ce7..21ae9e0d 100644 --- a/libpathod/app.py +++ b/libpathod/app.py @@ -36,6 +36,11 @@ def docs_pathod(): return render_template("docs_pathod.html", section="docs") +@app.route('/docs/language') +def docs_language(): + return render_template("docs_lang.html", section="docs") + + @app.route('/docs/pathoc') def docs_pathoc(): return render_template("docs_pathoc.html", section="docs") diff --git a/libpathod/templates/docs_lang.html b/libpathod/templates/docs_lang.html new file mode 100644 index 00000000..11a489b0 --- /dev/null +++ b/libpathod/templates/docs_lang.html @@ -0,0 +1,220 @@ +{% extends "frame.html" %} +{% block body %} + +
+

+ Language Spec + The mini-language at the heart of pathoc and pathod. +

+
+ + +
+

Responses

+
+ +

The general form of a response is as follows:

+ + 
code[MESSAGE]:[colon-separated list of features]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ hKEY=VALUE + + Set a header. Both KEY and VALUE are full Value Specifiers. +
+ bVALUE + + Set the body. VALUE is a Value + Specifier. When the body is set, pathod will + automatically set the appropriate Content-Length header. +
+ cVALUE + + A shortcut for setting the Content-Type header. Equivalent to: + + 
h"Content-Type"=VALUE
+ +
+ iOFFSET,VALUE + + Inject the specified value at the offset. OFFSET can be an + integer, or "r" to generate a random offset or "a" for an + offset just after all data has been sent. +
+ lVALUE + + A shortcut for setting the Location header. Equivalent to: + + 
h"Location"=VALUE
+ +
+ dOFFSET + + Disconnect after OFFSET bytes. The offset can also be "r", in which case pathod + will disconnect at a random point in the response. +
+ pSECONDS,OFFSET + + Pause for SECONDS seconds after OFFSET bytes. SECONDS can also be "f" to pause + forever. OFFSET can also be "r" to generate a random offset, or "a" for an + offset just after all data has been sent. +
+ + +
+

Requests

+
+ + +
+

Executing specs from file

+
+ + 
=./path/to/spec
+ + +
+

Components

+
+ + +

VALUEs

+ +

Literals

+ +

Literal values are specified as a quoted strings:

+ + 
"foo"
+ +

Either single or double quotes are accepted, and quotes can be escaped with + backslashes within the string:

+ + 
'fo\'o'
+ +

Literal values can contain Python-style backslash escape sequences:

+ + 
'foo\r\nbar'
+ + +

Files

+ +

You can load a value from a specified file path. To do so, you have to specify + a _staticdir_ option to pathod on the command-line, like so:

+ + 
pathod -d ~/myassets
+ +

All paths are relative paths under this directory. File loads are indicated by + starting the value specifier with the left angle bracket: + + 

<my/path

+ +

The path value can also be a quoted string, with the same syntax as literals:

+ + 
<"my/path"
+ + +

Generated values

+ +

An @-symbol lead-in specifies that generated data should be used. There are two + components to a generator specification - a size, and a data type. By default + pathod assumes a data type of "bytes".

+ +

Here's a value specifier for generating 100 bytes: + + 

@100

+ +

You can use standard suffixes to indicate larger values. Here, for instance, is + a specifier for generating 100 megabytes:

+ + 
@100m
+ +

Data is generated and served efficiently - if you really want to send a + terabyte of data to a client, pathod can do it. The supported suffixes are:

+ + + + + + + + + + + + + + + + + + + + +
b 1024**0 (bytes)
k 1024**1 (kilobytes)
m 1024**2 (megabytes)
g 1024**3 (gigabytes)
t 1024**4 (terabytes)
+ +

Data types are separated from the size specification by a comma. This + specification generates 100mb of ASCII:

+ + 
@100m,ascii
+ +

Supported data types are:

+ + + + + +{% endblock %} diff --git a/libpathod/templates/docs_pathod.html b/libpathod/templates/docs_pathod.html index 3b10b212..96866579 100644 --- a/libpathod/templates/docs_pathod.html +++ b/libpathod/templates/docs_pathod.html @@ -60,7 +60,7 @@ various other goodies. Try it by visiting the server root:

literal string, but there are many other fun things we can do. For example, we can tell pathod to generate 100k of random ASCII letters instead:

- 
200@100k,ascii_letters
+ 
200:@100k,ascii_letters

Full documentation on the value specification syntax can be found in the next section. @@ -121,190 +121,6 @@ various other goodies. Try it by visiting the server root:

200:b@1m:p10,10:p20,10:d5000
-

Response Features

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- hKEY=VALUE - - Set a header. Both KEY and VALUE are full Value Specifiers. -
- bVALUE - - Set the body. VALUE is a Value - Specifier. When the body is set, pathod will - automatically set the appropriate Content-Length header. -
- cVALUE - - A shortcut for setting the Content-Type header. Equivalent to: - - 
h"Content-Type"=VALUE
- -
- iOFFSET,VALUE - - Inject the specified value at the offset. OFFSET can be an - integer, or "r" to generate a random offset or "a" for an - offset just after all data has been sent. -
- lVALUE - - A shortcut for setting the Location header. Equivalent to: - - 
h"Location"=VALUE
- -
- dOFFSET - - Disconnect after OFFSET bytes. The offset can also be "r", in which case pathod - will disconnect at a random point in the response. -
- pSECONDS,OFFSET - - Pause for SECONDS seconds after OFFSET bytes. SECONDS can also be "f" to pause - forever. OFFSET can also be "r" to generate a random offset, or "a" for an - offset just after all data has been sent. -
- - -

VALUE Specifiers

- -

Literals

- -

Literal values are specified as a quoted strings:

- - 
"foo"
- -

Either single or double quotes are accepted, and quotes can be escaped with - backslashes within the string:

- - 
'fo\'o'
- -

Literal values can contain Python-style backslash escape sequences:

- - 
'foo\r\nbar'
- - -

Files

- -

You can load a value from a specified file path. To do so, you have to specify - a _staticdir_ option to pathod on the command-line, like so:

- - 
pathod -d ~/myassets
- -

All paths are relative paths under this directory. File loads are indicated by - starting the value specifier with the left angle bracket: - - 

<my/path

- -

The path value can also be a quoted string, with the same syntax as literals:

- - 
<"my/path"
- - -

Generated values

- -

An @-symbol lead-in specifies that generated data should be used. There are two - components to a generator specification - a size, and a data type. By default - pathod assumes a data type of "bytes".

- -

Here's a value specifier for generating 100 bytes: - - 

@100

- -

You can use standard suffixes to indicate larger values. Here, for instance, is - a specifier for generating 100 megabytes:

- - 
@100m
- -

Data is generated and served efficiently - if you really want to send a - terabyte of data to a client, pathod can do it. The supported suffixes are:

- - - - - - - - - - - - - - - - - - - - -
b 1024**0 (bytes)
k 1024**1 (kilobytes)
m 1024**2 (megabytes)
g 1024**3 (gigabytes)
t 1024**4 (terabytes)
- -

Data types are separated from the size specification by a comma. This - specification generates 100mb of ASCII:

- - 
@100m,ascii
- -

Supported data types are:

- - - - -
@@ -358,13 +174,14 @@ various other goodies. Try it by visiting the server root:

Error Responses

-

To let users distinguish crafted responses from internal pathod responses, - pathod uses the non-standard 800 response code to indicate errors. For example, - a request to:

+

Pathod uses the non-standard 800 response code to indicate internal + errors, to distinguish them from crafted responses. For example, a request + to:

http://localhost:9999/p/foo
-

... will return an 800 response, because "foo" is not a valid page specifier.

+

... will return an 800 response because "foo" is not a valid page + specifier.

diff --git a/libpathod/templates/frame.html b/libpathod/templates/frame.html index daf3e2ae..9c437eba 100644 --- a/libpathod/templates/frame.html +++ b/libpathod/templates/frame.html @@ -45,6 +45,7 @@ -- cgit v1.2.3