# Module cgi

This module implements helper procs for CGI applications. Example:

    import strtabs, cgi

    # Fill the values when debugging:
    when debug:
      setTestData("name", "Klaus", "password", "123456")
    # read the data into `myData`
    var myData = readData()
    # check that the data's variable names are "name" or "password"
    validateData(myData, "name", "password")
    # start generating content:
    writeContentType()
    # generate content:
    write(stdout, "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\">\n")
    write(stdout, "<html><head><title>Test</title></head><body>\n")
    writeln(stdout, "your name: " & myData["name"])
    writeln(stdout, "your password: " & myData["password"])
    writeln(stdout, "</body></html>")

# Imports

strutils, os, strtabs, cookies

# Types

    ECgi* = object of EIO

  the exception that is raised, if a CGI error occurs

    TRequestMethod* = enum
      methodNone,                 ## no REQUEST_METHOD environment variable
      methodPost,                 ## query uses the POST method
      methodGet                   ## query uses the GET method

  the used request method

# Procs

    proc URLencode*(s: string): string

  Encodes a value to be HTTP safe: This means that characters in the set `{'A'..'Z', 'a'..'z', '0'..'9', '_'}` are carried over to the result, a space is converted to `'+'` and every other character is encoded as `'%xx'` where `xx` denotes its hexadecimal value.

    proc URLdecode*(s: string): string

  Decodes a value from its HTTP representation: This means that a `'+'` is converted to a space, `'%xx'` (where `xx` denotes a hexadecimal value) is converted to the character with ordinal number `xx`, and and every other character is carried over.

    proc XMLencode*(s: string): string

  Encodes a value to be XML safe:
  - `"` is replaced by `&quot;`
  - `<` is replaced by `&lt;`
  - `>` is replaced by `&gt;`
  - `&` is replaced by `&amp;`
  - every other character is carried over.

    proc cgiError*(msg: string) {.noreturn.}

  raises an ECgi exception with message msg.

    proc readData*(allowedMethods: set[TRequestMethod] = {methodNone, methodPost,
        methodGet}): PStringTable

  Read CGI data. If the client does not use a method listed in the allowedMethods set, an ECgi exception is raised.

    proc validateData*(data: PStringTable; validKeys: varargs[string])

  validates data; raises ECgi if this fails. This checks that each variable name of the CGI data occurs in the validKeys array.

    proc getContentLength*(): string

  returns contents of the `CONTENT_LENGTH` environment variable

    proc getContentType*(): string

  returns contents of the `CONTENT_TYPE` environment variable

    proc getDocumentRoot*(): string

  returns contents of the `DOCUMENT_ROOT` environment variable

    proc getGatewayInterface*(): string

  returns contents of the `GATEWAY_INTERFACE` environment variable

    proc getHttpAccept*(): string

  returns contents of the `HTTP_ACCEPT` environment variable

    proc getHttpAcceptCharset*(): string

  returns contents of the `HTTP_ACCEPT_CHARSET` environment variable

    proc getHttpAcceptEncoding*(): string

  returns contents of the `HTTP_ACCEPT_ENCODING` environment variable

    proc getHttpAcceptLanguage*(): string

  returns contents of the `HTTP_ACCEPT_LANGUAGE` environment variable

    proc getHttpConnection*(): string

  returns contents of the `HTTP_CONNECTION` environment variable

    proc getHttpCookie*(): string

  returns contents of the `HTTP_COOKIE` environment variable

    proc getHttpHost*(): string

  returns contents of the `HTTP_HOST` environment variable

    proc getHttpReferer*(): string

  returns contents of the `HTTP_REFERER` environment variable

    proc getHttpUserAgent*(): string

  returns contents of the `HTTP_USER_AGENT` environment variable

    proc getPathInfo*(): string

  returns contents of the `PATH_INFO` environment variable

    proc getPathTranslated*(): string

  returns contents of the `PATH_TRANSLATED` environment variable

    proc getQueryString*(): string

  returns contents of the `QUERY_STRING` environment variable

    proc getRemoteAddr*(): string

  returns contents of the `REMOTE_ADDR` environment variable

    proc getRemoteHost*(): string

  returns contents of the `REMOTE_HOST` environment variable

    proc getRemoteIdent*(): string

  returns contents of the `REMOTE_IDENT` environment variable

    proc getRemotePort*(): string

  returns contents of the `REMOTE_PORT` environment variable

    proc getRemoteUser*(): string

  returns contents of the `REMOTE_USER` environment variable

    proc getRequestMethod*(): string

  returns contents of the `REQUEST_METHOD` environment variable

    proc getRequestURI*(): string

  returns contents of the `REQUEST_URI` environment variable

    proc getScriptFilename*(): string

  returns contents of the `SCRIPT_FILENAME` environment variable

    proc getScriptName*(): string

  returns contents of the `SCRIPT_NAME` environment variable

    proc getServerAddr*(): string

  returns contents of the `SERVER_ADDR` environment variable

    proc getServerAdmin*(): string

  returns contents of the `SERVER_ADMIN` environment variable

    proc getServerName*(): string

  returns contents of the `SERVER_NAME` environment variable

    proc getServerPort*(): string

  returns contents of the `SERVER_PORT` environment variable

    proc getServerProtocol*(): string

  returns contents of the `SERVER_PROTOCOL` environment variable

    proc getServerSignature*(): string

  returns contents of the `SERVER_SIGNATURE` environment variable

    proc getServerSoftware*(): string

  returns contents of the `SERVER_SOFTWARE` environment variable

    proc setTestData*(keysvalues: varargs[string])

  fills the appropriate environment variables to test your CGI application. This can only simulate the 'GET' request method. keysvalues should provide embedded (name, value)-pairs. Example:

      setTestData("name", "Hanz", "password", "12345")

    proc writeContentType*()

  call this before starting to send your HTML data to stdout. This implements this part of the CGI protocol:

      write(stdout, "Content-type: text/html\n\n")

  It also modifies the debug stack traces so that they contain `<br />` and are easily readable in a browser.

    proc setStackTraceNewLine*()

  Modifies the debug stack traces so that they contain `<br />` and are easily readable in a browser.

    proc setCookie*(name, value: string)

  Sets a cookie.

    proc getCookie*(name: string): TaintedString

  Gets a cookie. If no cookie of name exists, "" is returned.

    proc existsCookie*(name: string): bool

  Checks if a cookie of name exists.

# Iterators

    iterator decodeData*(data: string): tuple[key, value: TaintedString]

  Reads and decodes CGI data and yields the (name, value) pairs the data consists of.

    iterator decodeData*(allowedMethods: set[TRequestMethod] = {methodNone,
        methodPost, methodGet}): tuple[key, value: TaintedString]

  Reads and decodes CGI data and yields the (name, value) pairs the data consists of. If the client does not use a method listed in the allowedMethods set, an ECgi exception is raised.

Generated: 2012-09-23 21:47:54 UTC