# cgi

Dark Mode

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs

Search:

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")
    writeLine(stdout, "your name: " & myData["name"])
    writeLine(stdout, "your password: " & myData["password"])
    writeLine(stdout, "</body></html>")

# Imports

strutils, os, strtabs, cookies, uri

# Types

    CgiError = object of IOError

  exception that is raised if a CGI error occurs Source Edit

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

  the used request method Source Edit

# Procs

    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.
  Source Edit

    proc cgiError(msg: string) {...}{.noreturn, raises: [CgiError], tags: [].}

  raises an ECgi exception with message `msg`. Source Edit

    proc readData(allowedMethods: set[RequestMethod] = {methodNone, methodPost,
        methodGet}): StringTableRef {...}{.raises: [CgiError, ValueError, IOError],
                                      tags: [ReadEnvEffect, ReadIOEffect].}

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

    proc readData(data: string): StringTableRef {...}{.raises: [CgiError], tags: [].}

  Read CGI data from a string. Source Edit

    proc validateData(data: StringTableRef; validKeys: varargs[string]) {...}{.
        raises: [CgiError], tags: [].}

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

    proc getContentLength(): string {...}{.raises: [], tags: [ReadEnvEffect].}

  returns contents of the `CONTENT_LENGTH` environment variable Source Edit

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

  returns contents of the `CONTENT_TYPE` environment variable Source Edit

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

  returns contents of the `DOCUMENT_ROOT` environment variable Source Edit

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

  returns contents of the `GATEWAY_INTERFACE` environment variable Source Edit

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

  returns contents of the `HTTP_ACCEPT` environment variable Source Edit

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

  returns contents of the `HTTP_ACCEPT_CHARSET` environment variable Source Edit

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

  returns contents of the `HTTP_ACCEPT_ENCODING` environment variable Source Edit

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

  returns contents of the `HTTP_ACCEPT_LANGUAGE` environment variable Source Edit

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

  returns contents of the `HTTP_CONNECTION` environment variable Source Edit

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

  returns contents of the `HTTP_COOKIE` environment variable Source Edit

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

  returns contents of the `HTTP_HOST` environment variable Source Edit

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

  returns contents of the `HTTP_REFERER` environment variable Source Edit

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

  returns contents of the `HTTP_USER_AGENT` environment variable Source Edit

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

  returns contents of the `PATH_INFO` environment variable Source Edit

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

  returns contents of the `PATH_TRANSLATED` environment variable Source Edit

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

  returns contents of the `QUERY_STRING` environment variable Source Edit

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

  returns contents of the `REMOTE_ADDR` environment variable Source Edit

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

  returns contents of the `REMOTE_HOST` environment variable Source Edit

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

  returns contents of the `REMOTE_IDENT` environment variable Source Edit

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

  returns contents of the `REMOTE_PORT` environment variable Source Edit

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

  returns contents of the `REMOTE_USER` environment variable Source Edit

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

  returns contents of the `REQUEST_METHOD` environment variable Source Edit

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

  returns contents of the `REQUEST_URI` environment variable Source Edit

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

  returns contents of the `SCRIPT_FILENAME` environment variable Source Edit

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

  returns contents of the `SCRIPT_NAME` environment variable Source Edit

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

  returns contents of the `SERVER_ADDR` environment variable Source Edit

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

  returns contents of the `SERVER_ADMIN` environment variable Source Edit

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

  returns contents of the `SERVER_NAME` environment variable Source Edit

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

  returns contents of the `SERVER_PORT` environment variable Source Edit

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

  returns contents of the `SERVER_PROTOCOL` environment variable Source Edit

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

  returns contents of the `SERVER_SIGNATURE` environment variable Source Edit

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

  returns contents of the `SERVER_SOFTWARE` environment variable Source Edit

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

  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")

  Source Edit

    proc writeContentType() {...}{.raises: [IOError], tags: [WriteIOEffect].}

  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")

  Source Edit

    proc writeErrorMessage(data: string) {...}{.raises: [IOError], tags: [WriteIOEffect].}

  Tries to reset browser state and writes `data` to stdout in <plaintext> tag. Source Edit

    proc setStackTraceStdout() {...}{.raises: [], tags: [].}

  Makes Nim output stacktraces to stdout, instead of server log. Source Edit

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

  Sets a cookie. Source Edit

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

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

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

  Checks if a cookie of `name` exists. Source Edit

# Iterators

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

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

    iterator decodeData(allowedMethods: set[RequestMethod] = {methodNone,
        methodPost, methodGet}): tuple[key, value: TaintedString] {...}{.
        raises: [CgiError, ValueError, IOError], tags: [ReadEnvEffect, ReadIOEffect].}

  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. Source Edit

# Exports

encodeUrl, decodeUrl