☰

# std/cgi

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

This module implements helper procs for CGI applications. Example:

    import std/[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, syncio

# 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 cgiError(msg: string) {.noreturn, ...raises: [CgiError], tags: [], forbids: [].}

  Raises a `CgiError` exception with message `msg`. Source Edit

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

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

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

  Returns contents of the `CONTENT_LENGTH` environment variable. Source Edit

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

  Returns contents of the `CONTENT_TYPE` environment variable. Source Edit

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

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

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

  Returns contents of the `DOCUMENT_ROOT` environment variable. Source Edit

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

  Returns contents of the `GATEWAY_INTERFACE` environment variable. Source Edit

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

  Returns contents of the `HTTP_ACCEPT` environment variable. Source Edit

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

  Returns contents of the `HTTP_ACCEPT_CHARSET` environment variable. Source Edit

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

  Returns contents of the `HTTP_ACCEPT_ENCODING` environment variable. Source Edit

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

  Returns contents of the `HTTP_ACCEPT_LANGUAGE` environment variable. Source Edit

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

  Returns contents of the `HTTP_CONNECTION` environment variable. Source Edit

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

  Returns contents of the `HTTP_COOKIE` environment variable. Source Edit

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

  Returns contents of the `HTTP_HOST` environment variable. Source Edit

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

  Returns contents of the `HTTP_REFERER` environment variable. Source Edit

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

  Returns contents of the `HTTP_USER_AGENT` environment variable. Source Edit

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

  Returns contents of the `PATH_INFO` environment variable. Source Edit

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

  Returns contents of the `PATH_TRANSLATED` environment variable. Source Edit

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

  Returns contents of the `QUERY_STRING` environment variable. Source Edit

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

  Returns contents of the `REMOTE_ADDR` environment variable. Source Edit

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

  Returns contents of the `REMOTE_HOST` environment variable. Source Edit

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

  Returns contents of the `REMOTE_IDENT` environment variable. Source Edit

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

  Returns contents of the `REMOTE_PORT` environment variable. Source Edit

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

  Returns contents of the `REMOTE_USER` environment variable. Source Edit

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

  Returns contents of the `REQUEST_METHOD` environment variable. Source Edit

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

  Returns contents of the `REQUEST_URI` environment variable. Source Edit

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

  Returns contents of the `SCRIPT_FILENAME` environment variable. Source Edit

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

  Returns contents of the `SCRIPT_NAME` environment variable. Source Edit

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

  Returns contents of the `SERVER_ADDR` environment variable. Source Edit

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

  Returns contents of the `SERVER_ADMIN` environment variable. Source Edit

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

  Returns contents of the `SERVER_NAME` environment variable. Source Edit

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

  Returns contents of the `SERVER_PORT` environment variable. Source Edit

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

  Returns contents of the `SERVER_PROTOCOL` environment variable. Source Edit

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

  Returns contents of the `SERVER_SIGNATURE` environment variable. Source Edit

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

  Returns contents of the `SERVER_SOFTWARE` environment variable. Source Edit

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

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

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

  Reads CGI data from a string. Source Edit

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

  Sets a cookie. Source Edit

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

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

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

  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 validateData(data: StringTableRef; validKeys: varargs[string]) {.
        ...raises: [CgiError], tags: [], forbids: [].}

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

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

  Calls 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: [], tags: [WriteIOEffect],
                                           forbids: [].}

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

    proc xmlEncode(s: string): string {....raises: [], tags: [], forbids: [].}

  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

# Iterators

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

  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, a `CgiError` exception is raised. Source Edit

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

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

# Exports

encodeUrl, decodeUrl