manweb: A CGI script to display man pages

This function checks the protocol, retrieves the arguments, and checks them for validity.

# - - -   p r o c e s s A r g u m e n t s

def processArguments():
    """Retrieve and validate the arguments.

      [ if (this script is being executed by the CGI protocol) and
        (its arguments are valid) ->
          return (page name argument, section number argument
          defaulting to "1", suffix defaulting to "")
        else ->
          sys.stdout  +:=  an error message as HTML
          stop execution ]
    """

First we check to see if the CGI protocol is in effect. If so, the environmental variable GATEWAY will have the value CGI_VERSION; see Section 4.4.5, “GATEWAY” and Section 4.4.6, “CGI_VERSION”.

    #-- 1 --
    # [ if environmental variable GATEWAY is defined has the value
    #   CGI_VERSION ->
    #     I
    #   else ->
    #     sys.stdout  +:=  an HTML error message
    #     stop execution ]
    try:
        gateway  =  os.environ [ GATEWAY ]
        if  gateway != CGI_VERSION:
            errorPage ( "Incorrect CGI protocol version." )
    except KeyError:
        errorPage ( "This script must be executed using the CGI "
                    "protocol." )

Next we use Python's cgi module to extract the arguments following the “?” in the URL, converting them into a cgi.FieldStorage instance. For details of this module, see the online documentation.

    #-- 2 --
    # [ form  :=  a cgi.FieldStorage instance representing the
    #       arguments from the URL used to invoke this script ]
    form  =  cgi.FieldStorage()

The PAGE_NAME_ARG argument is required; the SECTION_ARG is optional and defaults to DEFAULT_SECTION; and the SUFFIX_ARG is optional and defaults to an empty string.

The form instance acts like a dictionary; if an argument was not supplied, attempting to extract it will raise a KeyError exception. See Section 4.4.7, “PAGE_NAME_ARG”.

    #-- 3 --
    # [ if (form[PAGE_NAME_ARG] does not exist) or
    #   (it exists but is not valid) ->
    #     sys.stdout  +:=  an error message as HTML
    #     stop execution
    #   else ->
    #     pageName  :=  the corresponding value
    try:
        pageName  =  form[PAGE_NAME_ARG].value
    except KeyError:
        errorPage ( "The 'p=PAGENAME' argument is required." )

For security reasons, we need to make sure that the page name does not contain any unusual characters that might cause security holes. See Section 4.4.2, “PAGENAME_RE” for the regular expression used to check its syntax.

    #-- 4 --
    # [ if pageName matches PAGENAME_RE ->
    #     I
    #   else ->
    #     sys.stdout  +:=  an error message as HTML
    #     stop execution ]
    m  =  PAGENAME_RE.match ( pageName )
    if  m is None:
        errorPage ( "The 'p=PAGENAME' argument is not valid." )

Retrieval and checking of the section name proceeds similarly, except that we have to supply a default value if the section name wasn't specified. See Section 4.4.8, “SECTION_ARG” and Section 4.4.9, “DEFAULT_SECTION”. For the regular expression used to validate the section name, see Section 4.4.3, “SECTION_RE”.

    #-- 5 --
    # [ if form[SECTION_ARG] does not exist ->
    #     sectionName  :=  DEFAULT_SECTION
    #   else if it exists and is valid ->
    #     sectionName  :=  the corresponding value
    #   else ->
    #     sys.stdout  +:=  an error message as HTML
    #     stop execution
    try:
        section  =  form[SECTION_ARG].value
        m  =  SECTION_RE.match ( section )
        if  m is None:
            errorPage ( "The 's=SECTION' argument is not valid." )
    except KeyError:
        section  =  DEFAULT_SECTION

Also check for the optional suffix argument, which defaults to the empty string. See Section 4.4.10, “SUFFIX_ARG” and Section 4.4.4, “SUFFIX_RE”.

    #-- 7 --
    # [ if form[SUFFIX_ARG] does not exist ->
    #     suffix  :=  ""
    #   else if form[SUFFIX_ARG] exists and is valid ->
    #     suffix  :=  the corresponding value
    #   else ->
    #     sys.stdout  +:=  an error message as HTML
    #     stop execution
    try:
        suffix  =  form[SUFFIX_ARG].value
        m  =  SUFFIX_RE.match ( suffix )
        if  m is None:
            errorPage ( "The 'x=SUFFIX' argument is not valid." )
    except KeyError:
        suffix  =  ""

Finally, return the three variable parts of the file name.

    #-- 8 --
    return (pageName, section, suffix)