# 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 {.raises: [], tags: [].}

  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 {.raises: [], tags: [].}

  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 {.raises: [], tags: [].}

  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: [ECgi], tags: [].}

  raises an ECgi exception with message msg.

    proc readData(allowedMethods: set[TRequestMethod] = {methodNone, methodPost,
        methodGet}): PStringTable {.raises: [ECgi, EOverflow, EInvalidValue],
                                    tags: [FReadEnv, FReadIO].}

  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]) {.
        raises: [ECgi], tags: [].}

  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 {.raises: [], tags: [FReadEnv].}

  returns contents of the `CONTENT_LENGTH` environment variable

    proc getContentType(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `CONTENT_TYPE` environment variable

    proc getDocumentRoot(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `DOCUMENT_ROOT` environment variable

    proc getGatewayInterface(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `GATEWAY_INTERFACE` environment variable

    proc getHttpAccept(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_ACCEPT` environment variable

    proc getHttpAcceptCharset(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_ACCEPT_CHARSET` environment variable

    proc getHttpAcceptEncoding(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_ACCEPT_ENCODING` environment variable

    proc getHttpAcceptLanguage(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_ACCEPT_LANGUAGE` environment variable

    proc getHttpConnection(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_CONNECTION` environment variable

    proc getHttpCookie(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_COOKIE` environment variable

    proc getHttpHost(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_HOST` environment variable

    proc getHttpReferer(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_REFERER` environment variable

    proc getHttpUserAgent(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `HTTP_USER_AGENT` environment variable

    proc getPathInfo(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `PATH_INFO` environment variable

    proc getPathTranslated(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `PATH_TRANSLATED` environment variable

    proc getQueryString(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `QUERY_STRING` environment variable

    proc getRemoteAddr(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REMOTE_ADDR` environment variable

    proc getRemoteHost(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REMOTE_HOST` environment variable

    proc getRemoteIdent(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REMOTE_IDENT` environment variable

    proc getRemotePort(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REMOTE_PORT` environment variable

    proc getRemoteUser(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REMOTE_USER` environment variable

    proc getRequestMethod(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REQUEST_METHOD` environment variable

    proc getRequestURI(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `REQUEST_URI` environment variable

    proc getScriptFilename(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SCRIPT_FILENAME` environment variable

    proc getScriptName(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SCRIPT_NAME` environment variable

    proc getServerAddr(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_ADDR` environment variable

    proc getServerAdmin(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_ADMIN` environment variable

    proc getServerName(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_NAME` environment variable

    proc getServerPort(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_PORT` environment variable

    proc getServerProtocol(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_PROTOCOL` environment variable

    proc getServerSignature(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_SIGNATURE` environment variable

    proc getServerSoftware(): string {.raises: [], tags: [FReadEnv].}

  returns contents of the `SERVER_SOFTWARE` environment variable

    proc setTestData(keysvalues: varargs[string]) {.raises: [EOS], tags: [FWriteEnv].}

  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() {.raises: [EIO], tags: [FWriteIO].}

  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() {.raises: [], tags: [].}

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

    proc setCookie(name, value: string) {.raises: [E_Base], tags: [FWriteIO].}

  Sets a cookie.

    proc getCookie(name: string): TaintedString {.raises: [], tags: [FReadEnv].}

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

    proc existsCookie(name: string): bool {.raises: [], tags: [FReadEnv].}

  Checks if a cookie of name exists.

# Iterators

    iterator decodeData(data: string): tuple[key, value: TaintedString] {.
        raises: [ECgi], tags: [].}

  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] {.
        raises: [ECgi, EOverflow, EInvalidValue], tags: [FReadEnv, FReadIO].}

  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: 2013-05-21 09:55:12 UTC