mycgi.lsp: Function and Context Index

Documentation for Module: mycgi.lsp || Module Index

module: mycgi.lsp
author: Tim Johnson, tim@johnsons-web.com
version: 0.1

description: Handles cgi, cky, and session interface
This module defines:
1)Advanced CGI processing tools. (cgi)
2)Advanced Cookie processing tools. (cky)
--- Handle cookies as RFC per 2109 with embedded name/value pairs
3)Session handling (session)
syntax: CGI Handling. Control Variables are described next:

Context Index
cgi Functions: ==>
Context Variables	off	query-string	rget-name	url-decode
cgi	on	rget	rget-val	url-encode
dbg	put	rget-all	show	workstation?
encode-url-pair	put-page
cky Functions: ==>
cky	del	more	put
session Functions: ==>
Control Variables	Overview	off	session

Context: cgi

In General: Context Variables

    syntax: (Context Variables)
    Set Variable to nil to ignore case for get
    syntax: (placeholder - see cgi:on)
    Set Variable to non-nil to return a nil value if a match in a multiple
    search is not made
    syntax: (cgi:script-name)
      name of the cgi script
    syntax: (cgi:domain)
     domain of the URL
    syntax: (cgi:path-to)
      Path to and not including the script name
    syntax: (cgi:path-thru)
     Path to and including the script name
    syntax: (cgi:path-with-info)
      path thru script plus reconstructed path-info
    syntax: (cgi:path-with-all)
     Entire state of CGI script with path info and query or posted
     data reconstructed as a full URL
    syntax: (cgi:on workstations ("m1.johnson.com" "m1.johnson.com"))
     Machines used as workstations. Send as params to (cgi:on)
    tring representation of symbols reserved as allowed for resetting

Function: cgi:cgi

Previous Function

    syntax: (cgi:cgi <list-of-keys-or-indexes>)
      If a string or symbol, return matching value(s), if integer an indexed path part.<br>
      Should only one value be returned, it will be an atom, otherwise a list is return.<br>
      If place-holder is true, nil will be returned for a non-existing match.
    return: Any number of values for any number of strings or symbol keys OR index of path part
    example:
      (cgi "name") => "Tim" (cgi:get name) => "Tim" (cgi 0) => "firspathpart"
      (cgi "name" 0) => ("Tim" "firstpathpart") (cgi "IDs") => ("one" "two")

Function: cgi:dbg

Previous Function

syntax: (cgi:dbg) use with the inspect function
usage: - Outputs path part and form (either "GET" or "POST") data

Function: cgi:encode-url-pair

Previous Function

syntax: (encode-url-pair <key> <val>)
encode a key/value pair

Function: cgi:off

Previous Function

syntax: (cgi:off)
Usage: Shut down the cgi object, close output file

Function: cgi:on

Previous Function

    syntax: (cgi:on <args>)
    Usage: - Initializes the cgi object
    <args> is an optional list of alternating symbols and values.
    Any symbol must first be included in the context symbol list
    and secondly must be registered in the <resetable> list.
    example:
    (cgi:on cs nil place-holder 1)
    Ignore case for get (cs) and insure that a nil is returned for
    unmatched keys (place-holder)

Function: cgi:put

Previous Function

    syntax: (cgi:put <args>)
    Usage: Append any text to the debug-stubs structure.
      Will be written to file when (cgi:off) is called

Function: cgi:put-page

Previous Function

syntax: (put-page <str-file-name>)
usage: Output a file with embedded newlisp code evaluated

Function: cgi:query-string

Previous Function

    syntax: (cgi:query-string <optional:lst>)
    Usage: - compose a query string. If lst is nil, use the internal params list
    return: encoded string
    example:
      (cgi:query-string (("First_name" "Tim")("Last_name" "Johnson") ("extra" "not a problem")))
      => "First_name=Tim&Last_name=Johnson&extra=not%20a%20problem"

Function: cgi:rget

Previous Function

    syntax: (cgi:rget <str-key> <getval: optional>)
       Without optional arg just test to see if any key matches <str-key>
    return: Any number of values for any number of strings or symbol keys OR index of path part
    example:
    (cgi:rget "^keypart") => where key starts with "keypart"
    (cgi:rget "*keypart") => where key has "keypart" at any position
    (cgi:rget "$keypart") => where key ends with "keypart"
    given the following URL:
      http://bart.johnson.com/cgi-bin/newlisp/testcgi.lsp?ID=one&ID=two&name=tim&teD=val
      (cgi:rget "$D") => "ID", (cgi:rget "$D" 1) => ("one" "two")
      (cgi:rget "$D" "all") => (("ID" "one" "two") ("teD" "val"))

Function: cgi:rget-all

Previous Function

    syntax: (cgi:rget-all <key>)
     Fetch all search results for a key
     See rget documentation

Function: cgi:rget-name

Previous Function

    syntax: (cgi:rget-name <key>)
     Test for the existence of a key matching a simple regex
     See rget documentation

Function: cgi:rget-val

Previous Function

    syntax: (rget-val <key>)
     Fetch a value matching a single regex value
     See rget documentation

Function: cgi:show

Previous Function

    syntax: (cgi:show) Dump the cgi environment
     to the screen or by passing the logger object, to a logfile
    This is the internal write-log function duplicated to stdout or logfile

Function: cgi:url-decode

Previous Function

    syntax: (cgi:url-decode <str-url-format>)

    Translates all URL formatted characters to ASCII. Translates + into spaces
    and %nn hexdigits into characters. nn is a 2-nibble hex number.

    return: An ASCII formatted string.
    example:
    (cgi:url-encode "What+time+is+it%3f") => "What time is it?"

Function: cgi:url-encode

Previous Function

    syntax: (cgi:url-encode <human-readable-string>)
    return: Properly encode query string

    Translates reserved characters into %nn hexdigits format
    where nn is a 2-nibble hex number.

    example:
    (cgi:url-encode "What time is it?" => "What%32time%32is%32it%3f")

Function: cgi:workstation?

Previous Function

syntax: (cgi:workstation?) am I running this script on my workstation?

Context: cky

Function: cky:cky

Previous Context

    syntax: (cky <cookie-name> <key-name>)
    param: <cookie-name> The string for the cookie variable name.
           <key-name> Optional. The string for the embedded value variable name
    return: Options follow
    example:
      If <key-name> is given
        The string for the embedded value.
      If not
        If a complex cookie with embedded key/value pairs
          The list of key/values and the extra data
        If not
          A string equivalent to the entire value of the cookie
    cookie "mycookie" looks like this: "testcgi.lsp(pwd|palmer)(log|tim042849)"
    (cky "mycookie") => ((("pwd" "palmer") ("log" "tim042849")) ("testcgi.lsp"))
    (cky "mycookie" "pwd") => palmer
    cookie "mycookie" looks like this: "just a simple cookie"
    (cky "mycookie") => "just a simple cookie" (key is ignored)

Function: cky:del

Previous Function

Previous Context

    syntax: (cky:del <cookie-name>)
    param: <cookie-name> The string for the cookie variable name
    Usage: Deletes the cookie by setting expiration date in the far past

Function: cky:more

Previous Function

Previous Context

syntax: (cky:more <name>)
return: extra data from complex cookie or all data if simple cookie

Function: cky:put

Previous Function

Previous Context

    syntax: (cky:put <cookie-name> <cookie-data> <domain> <path>)
    Cookies will be set in the following fashion:
    According to the RFC (2109), a name followed by a value and
    seperated by semicolons, other attributes specified by the RFC
    The value may have a complex structure defined by the following
    pattern: "(arg1|val1)(arg2|val2)", with any text preceding the first
    "(" used as the programmer sees fit.
    Example: "login=set by script.lsp (login|tim)(password|mypaswd)"
    parses to ("login"(("login" "tim")("password" "mypaswd"))("extra" "set by script.lsp"))
    syntax: (cky:put <cookie-name> <cookie-data> <domain> <path>)
    param: <cookie-name> The string for the cookie variable name
    param: <cookie-data> List begins with extra data ("" if not any)
                  followed by alternating names and values (not nested)
    param: <domain> Domain for which cookie is valid. Default: current domain
    param: <path> Path for which domain is valid. Default: "/cgi-bin/"

Context: session

In General: Control Variables

Previous Context

    syntax: (Control Variables)
    description: All are default values
    Limit Number of hours before an unchanged sessions expires. Default: 1
    dir Directory for session files. Default: "sessions". IMPORTANT: chmod 755
    extension File extension for session files. Default: ".sess.lsp"
    cky-name Name of cookie. Default: "mysession"
    gpassword Password. Change, of course!
    glogin Login. Change, of course!
    userkey Key to search for user name match, both CGI and cookie interfaces
    pswdkey Key to seach for password on, both CGI and cookie interfaces
    break Token to parse HTML content on.
    content Outer html content that "wraps" the login screen.
    syntax: (session:config ...<quoted-var1> <val1> <quoted-var1> <val2> ...)
    description: Sets control variables. Throws error if var isn't "registered" in control-vars

In General: Overview

Previous Function

Previous Context

    syntax: (Overview) - Session Handling.
    Default function: Check for a login and a password.
      First from cookies based on cky-name.
      If login and password are obtained from the cookie, then
        a session ID is fetched and used to compose the name of a session file.
      If not found in the cookie, then the CGI interface is tested for the same, presuming
        that the previous instance of the script was a login screen.
        Session ID is composed from a random string.
    If the login is not successful, then present a login screen.

Function: session:off

Previous Function

Previous Context

syntax: (session:off)
description: Close session.

Function: session:session

Previous Function

Previous Context

    syntax: (session:session) Default function. Handles logging in, checking both the
    cky and cgi contexts for password and login. Clears any session files that are out<br>
    of date, and either loads the session file that matches the session ID, or removes<br>
    the session file (if expired), signaling the system to prompt for a new login.