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

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 encodeUrl(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.   Source Edit
proc decodeUrl(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.   Source Edit
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, OverflowError, ValueError], 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 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 setStackTraceNewLine() {.
deprecated, raises: [], tags: []
.}
Makes Nim output stacktraces to stdout, instead of server log. Depracated alias for setStackTraceStdout.   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, OverflowError, ValueError], 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