Wapp

Check-in [271766c541]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Further documentation refinements.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 271766c541a09c526ae7a4b4c7066a691f7504049375690915d7ba8e855bdb92
User & Date: drh 2019-03-07 14:37:48
Context
2019-03-07
14:49
More documentation improvements. check-in: 984d973c34 user: drh tags: trunk
14:37
Further documentation refinements. check-in: 271766c541 user: drh tags: trunk
13:34
Documentation updates: improvements to the description of URL mapping and CGI variables. check-in: 2eac47dda7 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to README.md.

     1      1   Wapp - A Web-Application Framework for TCL
     2      2   ==========================================
     3      3   
     4         -1.0 Introduction
     5         -----------------
     6         -
     7      4   Wapp is a framework for writing web applications in TCL,
     8      5   with the following advantages:
     9      6   
    10         -  *   Very small API → easy to learn and use
    11         -  *   A complete application is contained in a single file
            7  +  *   Small and simple API → easy to learn and use
            8  +  *   A complete application is contained in a single file of TCL
    12      9     *   Resistant to attacks and exploits
    13     10     *   Cross-platform → CGI, SCGI, or a built-in web server
           11  +  *   The Wapp framework itself is a single-file TCL script
           12  +  *   Easy to embedded in a larger application
           13  +      to provide a web-based monitoring capability
    14     14     *   The MVC design pattern is supported but not required
    15         -  *   The Wapp framework itself is a  single-file TCL script
    16         -      that is "source"-ed, "package require"-ed, 
    17         -      or even copy/pasted into the application TCL script
    18         -  *   The framework can easily be embedded within a larger application
    19         -      to provide a web-based monitoring capability to an existing
    20         -      code base
    21     15     *   2-clause BSD license
    22     16   
    23         -
    24         -2.0 Hello World
    25         ----------------
           17  +Documentation
           18  +-------------
    26     19   
    27         -Here is a minimal web application written using Wapp:
    28         -
    29         ->
    30         -    #!/usr/bin/tclsh
    31         -    package require wapp
    32         -    proc wapp-default {} {
    33         -      wapp-subst {<h1>Hello, World!</h1>\n}
    34         -    }
    35         -    wapp-start $argv
    36         -
    37         -To run this application using the built-in web-server, store the code above
    38         -in a file (here we use the name "hello.tcl") and do:
    39         -
    40         ->
    41         -    tclsh hello.tcl
    42         -
    43         -To run the app using the built-in web-server bound to all TCP addresses
    44         -and listening on port 8080, use:
    45         -
    46         ->
    47         -    tclsh hello.tcl --server 8080
    48         -
    49         -To run the app as an SCGI server listening on port 9001:
    50         -
    51         ->
    52         -    tclsh hello.tcl --scgi 9001
    53         -
    54         -To run the application as CGI, make the hello.tcl file executable and
    55         -move it into the appropriate directory of the web server.
    56         -
    57         -3.0 Further information
    58         ------------------------
    59         -
           20  +  *  ["Hello World!" App (6 lines of code)](/doc/trunk/docs/helloworld.md)
    60     21     *  [Introduction To Writing Wapp Applications](/doc/trunk/docs/intro.md)
    61     22     *  [Quick Reference](/doc/trunk/docs/quickref.md)
    62     23     *  [Wapp Parameters](/doc/trunk/docs/params.md)
    63     24     *  [Wapp Commands](/doc/trunk/docs/commands.md)
    64     25     *  [URL Mapping](/doc/trunk/docs/urlmapping.md)
    65     26     *  [Security Features](/doc/trunk/docs/security.md)
    66     27     *  [How To Compile wapptclsh - Or Not](/doc/trunk/docs/compiling.md)
    67     28     *  [Limitations of Wapp](/doc/trunk/docs/limitations.md)
    68     29     *  [Example Applications](/file/examples)
    69     30     *  [Real-World Uses Of Wapp](/doc/trunk/docs/usageexamples.md)
    70     31     *  [Debugging Hints](/doc/trunk/docs/debughints.md)

Changes to docs/params.md.

   188    188        other than CGI, this is exactly the URL pathname, though with the
   189    189        query parameters removed.  PATH_INFO begins with a "/".
   190    190   
   191    191     +  **REMOTE\_ADDR**  
   192    192        The IP address from which the HTTP request originated.
   193    193   
   194    194     +  **REMOTE\_PORT**  
   195         -     The TCP port from which teh HTTP request originated.
          195  +     The TCP port from which the HTTP request originated.
   196    196   
   197    197     +  **REQUEST\_METHOD**  
   198    198        "GET" or "HEAD" or "POST"
   199    199   
   200    200     +  **REQUEST\_URI**  
   201    201        The URL for the inbound request, without the initial "http://" or
   202    202        "https://" and without the HTTP\_HOST.  This variable is the same as
................................................................................
   266    266     +  **BASE\_URL** &rarr; "http://example.com/cgi-bin/script"
   267    267     +  **SELF\_URL** &rarr; "http://example.com/cgi-bin/script/method"
   268    268     +  **PATH\_HEAD** &rarr; "method"
   269    269     +  **PATH\_TAIL** &rarr; "extra/path"
   270    270   
   271    271   The first five elements of the example above, HTTP\_HOST through
   272    272   QUERY\_STRING, are standard CGI.  The final four elements are Wapp
   273         -extensions.
          273  +extensions.  The following is the same information show in a diagram:
          274  +
          275  +>
          276  +    http://example.com/cgi-bin/script/method/extra/path?q1=5
          277  +           \_________/\_____________/\________________/ \__/
          278  +                |            |               |           |
          279  +            HTTP_HOST   SCRIPT_NAME      PATH_INFO       `-- QUERY_STRING
          280  +
          281  +>
          282  +    http://example.com/cgi-bin/script/method/extra/path?q1=5
          283  +    \_______________________________/ \____/ \________/
          284  +                    |                    |        | 
          285  +                BASE_URL           PATH_HEAD   PATH_TAIL
          286  +
          287  +
          288  +>
          289  +    http://example.com/cgi-bin/script/method/extra/path?q1=5
          290  +    \______________________________________/
          291  +                       |
          292  +                    SELF_URL
   274    293   
   275    294   ### 3.2 Undefined Parameters When Using SCGI on Nginx
   276    295   
   277    296   Some of the CGI parameters are undefined by default when using CGI mode
   278    297   with Nginx.  If these CGI parameters are needed by the application, then
   279    298   values must be assigned in the Nginx configuration file.  For example:
   280    299   

Changes to docs/quickref.md.

    40     40   |**wapp-cache-control** _CONTROL_|&rarr;|Set caching behavior of current page|
    41     41   |**wapp-content-security-policy** _POLICY_|&rarr;|Set the CSP for the current page|
    42     42   |**wapp-debug-env**|&rarr;|Return a text description of the Wapp environment|
    43     43   |**wapp** {_TEXT_}|&rarr;|Append _TEXT_ without substitution|
    44     44   |**wapp-unsafe** _TEXT_|&rarr;|Append _TEXT_ that contains nothing that needs to be escaped|
    45     45   
    46     46   
    47         -3.0 Parameters
    48         ---------------
           47  +<a name="cgiparams"></a>
           48  +3.0 CGI Parameters
           49  +------------------
    49     50   
    50     51   >
    51     52   |BASE\_URL|&rarr;|URL for the Wapp script without a method|
    52     53   |CONTENT|&rarr;|Raw (unparsed) POST content|
    53     54   |CONTENT\_LENGTH|&rarr;|Number of bytes of raw, unparsed POST content|
    54     55   |CONTENT\_TYPE|&rarr;|Mimetype of the POST content|
    55     56   |DOCUMENT\_ROOT|&rarr;|Directory that is the root of the webserver content tree|
    56     57   |HTTP\_COOKIE|&rarr;|Raw, unparsed cookies|
    57     58   |HTTP\_HOST|&rarr;|Hostname to which this request was sent|
    58     59   |HTTP\_USER\_AGENT|&rarr;|Name of client program that sent current request|
    59         -|HTTPS|&rarr;|Exists and has value "on" if the request is encrypted|
           60  +|HTTPS|&rarr;|Exists and has value "on" if the request is TLS encrypted|
    60     61   |PATH\_HEAD|&rarr;|First element of PATH\_INFO. Determines request handler|
    61     62   |PATH\_INFO|&rarr;|URL path beyond the application script name|
    62     63   |PATH\_TAIL|&rarr;|Part of PATH\_INFO beyond PATH\_HEAD|
    63     64   |REMOTE\_ADDR|&rarr;|IP address of the client|
    64     65   |REMOTE\_PORT|&rarr;|TCP port of the client|
    65     66   |REQUEST\_METHOD|&rarr;|"GET" or "POST" or "HEAD"|
    66     67   |SAME\_ORIGIN|&rarr;|True if this request is from the same origin|
................................................................................
    72     73   4.0 URL Parsing
    73     74   ---------------
    74     75   
    75     76   Assuming "env.tcl" is the name of the Wapp application script:
    76     77   
    77     78   >
    78     79       https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    79         -            \_________/ \__________/\__________/
           80  +            \_________/\___________/\__________/
    80     81                    |           |          |
    81     82                HTTP_HOST  SCRIPT_NAME  PATH_INFO
    82     83   
    83         ->
    84         -    SCRIPT_FILENAME := DOCUMENT_ROOT + SCRIPT_NAME
    85         -
    86     84   >
    87     85       https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    88     86       \______________________________/ \_/ \_____/
    89     87                      |                  |     |
    90         -                BASE_URL         PATH_HEAD  '-- PATH_TAIL     
    91         -
    92         ->
           88  +                BASE_URL         PATH_HEAD  |-- PATH_TAIL
           89  +                                      |   __|__
           90  +                                     / \ /     \
    93     91       https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    94     92       \__________________________________/         \__________/
    95     93                      |                                  |
    96     94                   SELF_URL                         QUERY_STRING
           95  +
           96  +>
           97  +    SCRIPT_FILENAME := DOCUMENT_ROOT + SCRIPT_NAME

Changes to docs/urlmapping.md.

     4      4   1.0 Anatomy Of A URL
     5      5   --------------------
     6      6   
     7      7   A Uniform Resource Locator (URL) is divided into parts as follows:
     8      8   
     9      9   >
    10     10       https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    11         -    \___/   \_________/ \______________________/ \__________/ \_____/
           11  +    \___/   \_________/\_______________________/ \__________/ \_____/
    12     12         |          |              |                     |          |
    13     13       scheme   authority        path                  query      fragment
    14     14   
    15     15   
    16     16   Assuming that /demo/env.tcl is the script that implements the application,
    17     17   traditional CGI and SCGI provide the following breakdown:
    18     18   
    19     19   >
    20     20       https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    21         -            \_________/ \__________/\__________/ \__________/
           21  +            \_________/\___________/\__________/ \__________/
    22     22                    |           |          |             |
    23     23                HTTP_HOST  SCRIPT_NAME  PATH_INFO   QUERY_STRING
    24     24   
    25     25   Wapp provides additional variables not found in traditional CGI:
    26     26   
    27     27   >
    28     28                   SELF_URL