W3cubDocs

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

Exports

encodeUrl, decodeUrl

Imports

strutils, os, strtabs, cookies, uri

Types

CgiError = object of IOError: exception that is raised if a CGI error occurs
RequestMethod = 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 xmlEncode(s: string): string {...}{.raises: [], tags: [].}

Encodes a value to be XML safe:

" is replaced by "
< is replaced by <
> is replaced by >
& is replaced by &
every other character is carried over.

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

raises an ECgi exception with message msg.

proc readData(allowedMethods: set[RequestMethod] = {methodNone, methodPost, methodGet}): StringTableRef {...}{. raises: [CgiError, OverflowError, 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.

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.

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

returns contents of the CONTENT_LENGTH environment variable

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

returns contents of the CONTENT_TYPE environment variable

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

returns contents of the DOCUMENT_ROOT environment variable

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

returns contents of the GATEWAY_INTERFACE environment variable

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

returns contents of the HTTP_ACCEPT environment variable

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

returns contents of the HTTP_ACCEPT_CHARSET environment variable

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

returns contents of the HTTP_ACCEPT_ENCODING environment variable

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

returns contents of the HTTP_ACCEPT_LANGUAGE environment variable

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

returns contents of the HTTP_CONNECTION environment variable

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

returns contents of the HTTP_COOKIE environment variable

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

returns contents of the HTTP_HOST environment variable

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

returns contents of the HTTP_REFERER environment variable

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

returns contents of the HTTP_USER_AGENT environment variable

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

returns contents of the PATH_INFO environment variable

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

returns contents of the PATH_TRANSLATED environment variable

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

returns contents of the QUERY_STRING environment variable

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

returns contents of the REMOTE_ADDR environment variable

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

returns contents of the REMOTE_HOST environment variable

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

returns contents of the REMOTE_IDENT environment variable

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

returns contents of the REMOTE_PORT environment variable

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

returns contents of the REMOTE_USER environment variable

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

returns contents of the REQUEST_METHOD environment variable

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

returns contents of the REQUEST_URI environment variable

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

returns contents of the SCRIPT_FILENAME environment variable

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

returns contents of the SCRIPT_NAME environment variable

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

returns contents of the SERVER_ADDR environment variable

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

returns contents of the SERVER_ADMIN environment variable

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

returns contents of the SERVER_NAME environment variable

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

returns contents of the SERVER_PORT environment variable

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

returns contents of the SERVER_PROTOCOL environment variable

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

returns contents of the SERVER_SIGNATURE environment variable

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

returns contents of the SERVER_SOFTWARE environment variable

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

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

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

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

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

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

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

Makes Nim output stacktraces to stdout, instead of server log. Depracated alias for setStackTraceStdout.

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

Sets a cookie.

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

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

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

Checks if a cookie of name exists.

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.
iterator decodeData(allowedMethods: set[RequestMethod] = {methodNone, methodPost, methodGet}): tuple[key, value: TaintedString] {...}{. raises: [CgiError, OverflowError, 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.