Provided by: afnix_3.8.0-1_amd64 bug

NAME

       nwg - standard network working group module

STANDARD NETWORK WORKING GROUP MODULE

       The   Standard   Network   Working  Group  module  is  an  original  implemtation  of  the
       recommendations proposed by the NWG and  currently  found  in  the  form  of  Request  for
       Comments  (RFC).  Most  of the objects are used with networking application, with the most
       common one beeing the Universal Resource Identifier (URI) object.

       The uri class
       The Uri class is a base class that parses a Uniform Resource Identifier or uri string  and
       provides  methods  to access individual component of that uri. The implementation conforms
       to RFC 3986. The URI components are the scheme, the authority, the path, the query and the
       fragment. The class also takes care of the character escaping.

       const uri (afnix:www:Uri "http://www.afnix.org")

       An  uri  can be broken into several components called the scheme, the authority, the path,
       optionally the query and the fragment. The Uri class provide a  method  to  retrieve  each
       component of the parsed uri.

       const uri (afnix:www:Uri "http://www.afnix.org/")
       println (uri:get-scheme)    # http
       println (uri:get-authority) # www.afnix.org
       println (uri:get-path)      # /

       Character conversion
       The  Uri  class  performs  automatically  the  character  conversion in the input uri. For
       example, the + character is  replaced  by  a  blank.  The  %  character  followed  by  two
       hexadecimal  values  is  replaced  by  the  corresponding  ASCII character. Note that this
       conversion does now apply to the query string.

       Query string
       The get-query method returns the query string of the uri. The query  string  starts  after
       the  ?  character.  The  query  string  is  a series of key-pair values separated by the &
       character.

       const uri (afnix:www:Uri
         "http://www.afnix.org?name=hello&value=world")
       println (uri:get-query) # name=hello&value=world

       The module also provides the UriQuery class that parses the query  string  and  store  the
       result  in the form of a property list. The query string parse is particularly useful when
       writing automated scripts.

       # create a query string object
       const qs (afnix:nwg:UriQuery (uri:get-query))
       # get the name value
       qs:get-value "name"

       Managing a cgi request
       Managing a cgi request involves primarily the parsing  of  the  requesting  uri.  The  uri
       generally  contains the http referrer as well as parameter which are stored in the form of
       a query string. However, depending on the cgi method which can be of type GET or POST, the
       treatment is somewhat different.

       Checking the protocol version
       In the presence of a cgi protocol, it is always a good idea to check the protocol version,
       or at least to put an assertion. The protocol version is normally CGI/1.1 and is stored in
       the GATEWAY_INTERFACE environment variable.

       # check the cgi protocol
       assert "CGI/1.1" (
         afnix:sys:get-env "GATEWAY_INTERFACE")

       Getting the query string
       If  the  request  method  is  GET,  then  the query string is available in the environment
       variable QUERY_STRING. If the request method is POST, the query string is available in the
       input  stream.  The  length of the query string is given by the CONTENT_LENGTH environment
       variable. The following example illustrates the extraction of the query string.

       # check the cgi protocol
       assert "CGI/.1" (
         afnix:sys:get-env "GATEWAY_INTERFACE")
       # initialize the query string
       const query (afnix:sys:get-env "QUERY_STRING")
       # get the request method
       const rqm (afnix:sys:get-env "REQUEST_METHOD")
       # check for a post request and update the query string
       if (== rqm "POST") {
         # create a buffer from the content length
         const len (
           Integer (afnix:sys:get-env "CONTENT_LENGTH"))
         # get the standard input stream and read content
         const is  (interp:get-input-stream)
         const buf (is:read len)
         # set the query string
         query:= (buf:to-string)
       }

       Parsing the query string
       The UriQuery class is designed to parse a cgi query  string.  Once  the  string  has  been
       parsed,  it is possible to perform a query by key since the class operates with a property
       list.

       const query (
         afnix:www:UriQuery "name=hello&value=world")
       query:length      # 2
       query:get-value "name"  # hello
       query:get-value "value" # world

       The UriQuery class is the foundation to build cgi script. When  the  library  is  combined
       with  the  web  application  management  (wam) service, powerful applications can be built
       easily.

       Special functions
       Several dedicated functions are available in the library as  a  way  to  ease  the  object
       manipulations. Theses functions operate mostly on uri and files as described below.

       Uri functions
       Several  functions  are designed to ease the uri manipulation. Most of them operate on the
       uri name or their associated system name. The  normalize-uri-name  function  normalizes  a
       string  argument by adding a uri scheme if missing in the original string. If the function
       detects that the name starts with a host name, the http scheme is added. If  the  function
       detects  that the string starts with a path, the file scheme is added. otherwise, the name
       argument is left untouched. The system-uri-name function normalizes the string argument by
       prioritizing  the  system  name. The function attempts to find a file that match the sring
       argument and  eventually  build  a  uri  file  scheme.  If  the  file  is  not  fond,  the
       normalization process occurs with the normalize-uri-name function.

       # normalize a uri name
       trans  unm "http://www.afnix.org"
       assert unm (
         afnix:nwg:normalize-uri-name unm)
       assert unm (
         afnix:nwg:normalize-uri-name "www.afnix.org")
       assert unm (
         afnix:nwg:normalize-uri-name "//www.afnix.org")

       Mime functions
       Mime  functions  are  dedicated  to easee the mainpulation of media types or mime. A media
       type is defined by a string in the form of a type and content value  such  as  text/plain.
       The mime-value-p predicate returns true if a string mime value is a valid media type. From
       a file perspective, the mime-extension-p predicate returns true if  the  string  extension
       has  a  valid  media type associated to it. Finally, the extension-to-mime function can be
       used to get the string mime value associated with a file extension.

       # check a media type
       assert true (afnix:nwg:mime-value-p "text/plain")
       # check the mime extension predicate
       assert true (afnix:nwg:mime-extension-p "txt")
       # check the extension to mime
       assert "text/plain" (
         afnix:nwg:extension-to-mime "txt")

       HTTP transaction objects
       The concept of HTTP transactions is defined in RFC 2616. In the client/server approach,  a
       client  issues  a request which is answered with a response. A special case arise when the
       server is asked to perform some extra works, such like executing a script. In  this  case,
       the  answer  is called a reply which is formatted into a response when the server does its
       job correctly.  The nature of the  HTTP  objects  determines  how  the  associated  stream
       behaves.  With  a  HTTP  request,  the  object  is  filled by reading an input stream when
       operating on the server side. On the other hand,  the  request  is  filled  by  data  when
       operating  on  the  client  side. With a HTTP response, the opposite situation occurs. The
       HTTP response is filled by reading an input stream when operating on the client  side  and
       filled by data when operating on the server side.

       HTTP protocol
       The HttpProto class is a base class designed to handle a HTTP header that is found in both
       HTTP request and response. The class is built around a property list that is filled either
       by  parsing  an input stream or by processing specific methods. The HttpProto defines also
       some methods which are often used with a HTTP request or response.

       HTTP response
       The HttpResponse class is a class designed to handle a HTTP response.  When  operating  on
       the  client  side, the response object is built by reading an input stream. When operating
       on the server side, the response object is built by calling specific methods.

       Creating a server response
       A server response is created by specifying the response status code. By  default,  a  HTTP
       response  is  created with the default media type text/html. If the media type needs to be
       changed, it can be passed as the second argument to the response constructor. By  default,
       the empty constructor creates an empty constructor with a valid status code.

       #create a valid response
       const hr (afnix:nwg:HttpResponse 200)

       Once  the  server  response  is  created,  it  can  be  augmented with some headed values.
       Typically, a server will add some information about the response, such  like  the  content
       length,  the  modification  time  or a tag. The HttpResponse provides several methods that
       ease the generation of these header values.

       Creating a client response
       A client response is created by binding an input stream to a response object.  During  the
       construction,  the input stream is read and the HTTP protocol header is filled. It is also
       during this phase that the status code is processed. It is therefore important  to  ensure
       that a response object is built correctly before attempting to access it.

       # create a client response by stream
       const hr (afnix:nwg:HttpResponse is)

       Reading a client response
       When  the response has been created, it is important to check its status code. Most of the
       time, the response is valid  and  its  content  can  be  read  directly.  The  status-ok-p
       predicate  returns  true  if  the status code is valid. In such case, a HTTP stream can be
       built in order to read the response.

       # check that a response is valid
       if (hr:status-ok-p) {
         # create a http stream
         const rs (afnix:nwg:HttpStream ht is)
         # read the response stream
         while (rs:eos-p) (rs:read)
       }

       Before reading a http stream, it is important to detect  and  verify  the  nature  of  the
       response content. The media-type-p predicate returns true if the media type is defined and
       the get-media-type method returns the response type in the form of a mime code  such  like
       text/html.  Eventually,  the  character  set  associated  with  the media type can also be
       detected. The encoding-mode-p predicate and the get-encoding-mode method can  be  used  to
       detect  the content encoding mode. However, it is worth to note that the HttpStream object
       is automatically sets with the proper encoding if it can be found in the response header.

       Special client response
       Certain response can sometime contains  special  status  codes  that  require  a  specific
       treatment.  This  is the case when the response corresponds to a http redirection. In this
       case, the new uri must be fetched to get the desired response.  The  location-p  predicate
       returns  true  if  the response corresponds to a http redirect and the get-location method
       can be used to get the new location uri. If  this  situation  arises,  it  is  up  to  the
       implementation to decide what to do with the new uri. In most cases, a new request will be
       sent to the server.

       Cookie object
       The Cookie object is a special object that can be used during a http session, to post data
       to  the  http client. The idea behind cookies is to be able to maintain some state, during
       the user session for some time. A cookie is a name/value pair and eventually an expiration
       time.  By  default,  the  cookie  object are defined for one http client session, but this
       behavior can be changed.

       Managing cookies
       A cookie is created with a  name/value  pair  and  eventually  an  expiration  time.  Such
       expiration  time  is  called the maximum-age and is automatically formatted by the object.
       With two arguments a session cookie is created. With a third argument as an  integer,  the
       constructor set the maximum age in seconds.

       # create a cookie with name/value
       const cookie (afnix:nwg:Cookie "cartid" "123456789")

       The  cookie  implementation  follows  the  recommendation  of  the RFC-2965 for http state
       management. The most important point to remember is the interpretation of the maximum  age
       that differs from one cookie version to another. With version 1, which is the default, the
       maximum age is defined relatively in seconds, while it  is  absolute  with  version  0.The
       maximum  age is set either at construction or with the set-max-age method. The set-max-age
       method sets the cookie life time in seconds, in reference to the current time. A  negative
       value  is always reset to -1 and defined a session cookie. A 0 value tells the http client
       to remove the cookie. The set-path method defines the path for which this cookie apply.

       Adding a cookie
       Once the cookie is defined, the set-cookie method of the HttpResponse object can  be  used
       to  install the cookie. Combined with the write method, the cookie can be send to the http
       client.

STANDARD NETWORK WORKING GROUP REFERENCE

       Uri
       The Uri class is a base object used to parse or build a  uniform  resource  identifier  as
       defined  by  RFC  3986.  The URI can be built by specifying each component or by parsing a
       string. When a string is given in the constructor, the class parses the string and extract
       all  components. The uri components are the scheme, the authority, the path, the query and
       the fragment. The class also takes care of the character escaping.

       Predicate

              uri-p

       Inheritance

              Object

       Constructors

              Uri (none)
              The Uri constructor creates an empty uri object.

              Uri (String)
              The Uri constructor create a uri object by value. The string argument is the uri to
              parse at the object construction.

              Uri (String String Integer)
              The Uri constructor create a uri object by scheme host and port. The first argument
              is the uri scheme. The second argument is the uri host name. The third argument  is
              the uri port. The uri base name can be reconstructed from this information.

       Methods

              parse -> none (String)
              The  parse  method reset the uri object, parse the string argument and fill the uri
              object with the result.

              get-scheme -> String (none)
              The get-scheme method returns the scheme of the parsed uri object.

              get-authority -> String (none)
              The get-authority method returns the authority part of the parsed uri.

              get-path -> String (none)
              The get-path method returns the path of the parsed uri.

              get-path-target -> String (none)
              The get-path-target method returns the path target of  the  parsed  uri.  The  path
              target is the last element of the uri path.

              get-query -> String (none)
              The get-query method returns the complete query string of the parsed uri. Note that
              characters are not escaped when getting the string.

              get-fragment -> String (none)
              The get-fragment method returns the complete query string of the parsed uri.

              get-base -> String (none)
              The get-base method returns the combined uri scheme and authority.

              get-rname -> String (none)
              The get-rname method returns the reference uri name with the combined  uri  scheme,
              authority and path all percent encoded.

              get-hname -> String (none)
              The get-hname method returns the combined uri scheme, authority and path.

              get-aname -> String (none)
              The  get-aname  method  returns  the  almost  combined  uri  name  with the scheme,
              authority, path and query.

              add-path -> Uri (String)
              The add-path method adds a path to the calling uri and returns a new uri  with  the
              new path added to the old one.

              get-href -> Uri (String)
              The  get-href method returns a new uri by eventually combining the string argument.
              If the string argument correspond to  an  uri,  the  corresponding  uri  is  built.
              Otherwise,  the  string argument is considered as a path to be added to the current
              uri in order to build a new uri.

              get-system-path -> String (none)
              The get-system-path method returns the system path representation of the uri  path.
              This function works only if the scheme if a file scheme.

              get-path-encoded -> String (none)
              The  get-path-encoded method returns the uri in the encoded form. Normally the get-
              path removes the percent-encoded characters which might  not  be  appropriate  with
              some  protocol  such  like  the  http  protocol.  The  get-path-encoded returns the
              original path. Note that getting the path with getpath and doing a  percent  coding
              might  result  in  a  different  result  since  the  internal  representation  uses
              normalized string.

              get-host -> String (none)
              The get-host method returns the authority or path host name if  any  can  be  found
              with respect to the scheme. With a ftp, http or https scheme, the host is extracted
              from the authority. With a mailto scheme, the host is extracted from the path.

              get-port -> Integer (none)
              The get-port method returns the authority port if any can be found with respect  to
              the scheme.

       UriQuery
       The  UriQuery  class  is  a simple class that parses a uri query string and build property
       list. during the parsing process, a special transliteration process is done  as  specified
       by  RFC 3986. This class is primarily used with cgi scripts. Note that the string to parse
       is exactly the one produced by the get-query method of the Uri class.

       Predicate

              uri-query-p

       Inheritance

              Plist

       Constructors

              UriQuery (none)
              The UriQuery constructor creates an empty uri query object.

              UriQuery (String)
              The UriQuery constructor create a uri object by value. The string argument  is  the
              uri  query  string to parse at the object construction. The query string is the one
              obtained from the get-query method of the Uri class.

       Methods

              parse -> none (String)
              The parse method reset the uri query object, parses the string  argument  and  fill
              the property list object with the result.

              get-query -> String (none)
              The get-query method returns the original query string.

       UriPath
       The  UriPath  class  is a class designed for the management of file system path associated
       with a uri. Typically, this class will be used with  a  http  server  or  client  when  an
       association  between  a  uri  and  a  file  name  needs  to be made. The general operation
       principle is to associate a path with a uri authority. The uri path is  then  concatanated
       to  produce  a new path. If the uri path is empty, it can be eventually replaced by a file
       name, known as the diretory index in the http terminology.

       Predicate

              uri-path-p

       Inheritance

              Object

       Constructors

              UriPath (none)
              The UriPath constructor creates an empty uri path object.

              UriPath (String)
              The UriPath constructor create a uri object by root path. The  string  argument  is
              the uri root path.

              UriPath (String String)
              The  UriPath  constructor  create  a uri object by root and index. The first string
              argument is the uri root path and the second string argument is the directory index
              path.

              UriPath (String String String)
              The UriPath constructor create a uri object by root, index and authority. The first
              string argument is the uri root path, the second string argument is  the  directory
              index path and the third argument is the authority.

       Methods

              get-root -> String (none)
              The get-root method returns the root path.

              get-index -> String (none)
              The get-index method returns the index path.

              get-authority -> String (none)
              The get-authority method returns the uri authority.

              map-request-uri -> String (none)
              The  map-request-uri  map  a request uri into a system path. The string argument is
              the request uri. The request uri must be an absolute path. The result string is the
              system path build with the root path.

              normalize -> String (none)
              The  normalize  method  build  a  system  from  a request path. The request path is
              associated with the root path and then normalized  to  produce  a  complete  system
              path.

       HttpProto
       The  HttpProto  class  is  a base class that ease the deployment of the http protocol. The
       base class is built with a property list which is used to define the message  header.  The
       class also defines the write methods which are used to write a message either on an output
       stream or into a buffer.

       Predicate

              http-proto-p

       Inheritance

              Object

       Methods

              reset -> none (none)
              The reset method resets the http protocol object by clearing the  protocol  version
              and header.

              parse -> none (none)
              The  parse  method  parse  the input stream bound to the http protocol. In order to
              operate, an input stream  must  be  associated  with  the  protocol  object  or  an
              exception  is  raised. After a stream has been parsed, the protocol version and the
              header are set.

              write -> none (none|OutputStream|Buffer)
              The write method formats and writes the http protocol object to an output stream or
              a buffer. Without argument, the default output stream is used. With an argument, an
              output stream or a buffer object can be used.

              header-length -> Integer (none)
              The header-length method returns the number of properties in the header.

              header-exists-p -> Boolean (String)
              The header-exists-p predicate returns true if the property exists  in  the  header.
              The string argument is the property name.

              header-set -> none (String Literal)
              The header-set method sets a new property to the http header. The first argument is
              the property name. The second argument is a  literal  object  which  is  internally
              converted to a string.

              header-get -> Property (Integer)
              The header-get method returns a property object by index.

              header-map -> String (String)
              The  header-map method returns a property value by name. The string argument is the
              property name.

              header-find -> Property (String)
              The header-find method returns a property object by name. The  string  argument  is
              the property name. If the property is not found, the nil object is returned.

              header-lookup -> Property (String)
              The  header-lookup method returns a property object by name. The string argument is
              the property name. If the property is not found, an exception is raised.

              header-plist -> Plist (none)
              The header-plist method returns the header in the form of a property list.

              content-length-p -> Boolean (none)
              The content-length-p predicate returns true if the content length is defined in the
              protocol header.

              get-content-length -> Integer (none)
              The  get-content-length  method  returns the content length defined in the protocol
              header. If the content length is not defined in  the  header,  the  null  value  is
              returned.

              media-type-p -> Boolean (none)
              The  media-type-p  predicate  returns  true  if  the content type is defined in the
              protocol header.

              get-media-type -> String (none)
              The get-media-type method returns the media type defined in the protocol header. If
              the media type is not defined in the header, the default media type is returned.

              encoding-mode-p -> Boolean (none)
              The  encoding-mode-p  predicate returns true if the encoding mode is defined in the
              protocol header.

              get-encoding-mode -> String (none)
              The get-encoding-mode method returns the protocol encoding mode.  If  the  encoding
              mode is not defined in the protocol header, the default encoding mode is returned.

       HttpRequest
       The  HttpRequest  class  is  a  base  class  designed  to handle a http request. The class
       operates with the protocol version 1.1 as defined by RFC 2616. For a server  request,  the
       request  is  built  by  reading  an  input stream and setting the request command with its
       associated header. For a client request, the request is formatted with a  request  command
       and a eventually a uri. In both cases, the header is filled automatically depending on the
       request side.

       Predicate

              http-request-p

       Inheritance

              HttpProto

       Constructors

              HttpRequest (none)
              The HttpRequest constructor creates a default http request. By default, the request
              object is built with the GET method and the request uri set to the root value.

              HttpRequest (String)
              The  HttpRequest constructor creates a http request object with a specific command.
              By default, the request uri is set to root, except for the OPTIONS method

              HttpRequest (Uri)
              The HttpRequest constructor creates a http request object with a uri.  The  default
              request method is GET.

              HttpRequest (InputStream)
              The  HttpRequest  constructor  creates  a http request object with a specific input
              stream. At construction, the request header is cleared  and  the  input  stream  is
              bound to the object.

              HttpRequest (String String)
              The  HttpRequest  constructor  creates a http request object with a specific method
              and a uri name. The first string argument is the request method to use. The  second
              string  argument  is the uri attached to the command. Note that the term uri should
              be understood as a request uri.

              HttpRequest (String Uri)
              The HttpRequest constructor creates a http request object with  a  specific  method
              and  a  uri.  The  first  string  argument is the request method to use. The second
              argument is the uri attached to the method.

       Methods

              set-method -> none (String)
              The set-method method sets the request method. This method does not check that  the
              command  is  a  valid  HTTP  method  and  thus  leaves  plenty  of  room for server
              development. As a matter of fact, RFC 2616 does not prohibit the existence of  such
              extension.

              get-method -> String (none)
              The get-method method returns the request method string.

              set-uri -> none (String)
              The  set-uri method sets the request uri. The argument string does not have to be a
              valid uri string since some commands might accept special string such like  "*"  to
              indicate all applicable uri.

              get-uri -> String (none)
              The get-uri method returns the request uri string.

       HttpResponse
       The  HttpResponse  class  is  a  base  class designed to handle a http response. The class
       operates with the protocol version 1.1 as defined by RFC 2616. For a client response,  the
       response is built by reading an input stream and setting the response status code with its
       associated header. For a server response, the response is formatted with a response status
       and  additional  header  information.  In  both  cases, the header is filled automatically
       depending on the response side. On the other hand, trying to set some header with an input
       stream bound to the response object might render the response object unusable.

       Predicate

              http-response-p

       Inheritance

              HttpProto

       Constructors

              HttpResponse (none)
              The  HttpResponse  constructor creates a default http response object. The response
              is marked valid with a default text/plain media type.

              HttpResponse (Integer)
              The HttpResponse constructor creates a http response object with a status code. The
              response code is associated with the default text/plain media type.

              HttpResponse (InputStream)
              The  HttpResponse  constructor creates a http response object with a specific input
              stream. At construction, the response header is cleared and  the  input  stream  is
              bound to the object.

              HttpResponse (Integer String)
              The  HttpResponse constructor creates a http response object with a status code and
              a media type. The first argument is the status code. The  second  argument  is  the
              associated media type.

       Methods

              set-status-code -> none (Integer)
              The set-status-code method sets the response status code.

              get-status-code -> Integer (none)
              The get-status-code method returns the response status code.

              map-status-code -> String (none)
              The  map-status-code  method returns a string representation of the response status
              code.

              status-ok-p -> Boolean (none)
              The status-ok-p predicate returns true if the response status code  is  valid  (aka
              status 200).

              status-error-p -> Boolean (none)
              The  status-error-p  predicate returns true if the response status code is an error
              code.

              location-p -> Boolean (none)
              The location-p predicate returns true is the response status code indicates that  a
              request should be made at another location. The location can be found with the get-
              location method.

              get-location -> String (none)
              The get-location method returns the location uri found in the response header. This
              method is equivalent to a header query.

              set-location -> none (String)
              The  set-location  method  set  the  redirect  location in the response header. The
              string argument is the location uri.

              set-cookie -> none (Cookie)
              The set-cookie method sets a cookie object to the http header. The  cookie  version
              is properly handled by the method.

       Cookie
       The  Cookie  class  is  a  special  class  designed to handle cookie setting within a http
       transaction. A cookie is name/value pair that is set by the server and stored by the  http
       client.  Further  connection with the client will result with the cookie value transmitted
       by the client to the server. A cookie has various parameters that controls  its  existence
       and behavior. The most important one is the cookie maximum age that is defined in seconds.
       A null value tells the client to discard the cookie. A cookie without maximum age is valid
       only  during  the  http client session. A cookie can be added to the HttpReply object with
       the set-cookie method. A cookie can be constructed with a  name/value  pair.  An  optional
       third  argument  is  the  maximum age. The default cookie version is 1 as specified by RFC
       2965. With a version 1, the maximum age is interpreted as the number of seconds before the
       cookie expires. With version 0, the maximum age is the absolute time.

       Predicate

              cookie-p

       Inheritance

              Object

       Constructors

              Cookie (String String)
              The  Cookie constructor creates a cookie with a name value pair. The first argument
              is the cookie name. The second argument is the cookie value.

              Cookie (String String Integer)
              The Cookie constructor creates a cookie with a name value pair and a  maximum  age.
              The first argument is the cookie name. The second argument is the cookie value. The
              third argument is the cookie maximum age.

       Methods

              get-version -> Integer (none)
              The get-version method returns the cookie version.

              set-version -> none (Integer)
              The set-version method sets the cookie version. The version number can only be 0 or
              1.

              get-name -> String (none)
              The  get-name  method  returns  the cookie name. This is the name store on the http
              client.

              set-name -> none (String)
              The set-name method sets the cookie name. This  is  the  name  store  on  the  http
              client.

              get-value -> String (none)
              The get-value method returns the cookie value. This is the value stored on the http
              client bounded by the cookie name.

              set-value -> none (String)
              The set-value method sets the cookie value. This is the value  store  on  the  http
              client bounded by the cookie name.

              get-maximum-age -> Integer (none)
              The get-maximum-age method returns the cookie maximum age. The default value is -1,
              that is, no maximum age is set and the cookie is valid only  for  the  http  client
              session.

              set-maximum-age -> none (Integer)
              The  set-maximum-age  method sets the cookie maximum age. A negative value is reset
              to -1. A 0 value tells the http client to discard  the  cookie.  A  positive  value
              tells the http client to store the cookie for the remaining seconds.

              get-path -> String (none)
              The  get-path  method  returns the cookie path value. The path determines for which
              http request the cookie is valid.

              set-path -> none (String)
              The set-path method sets the cookie path value. The path determines for which  http
              request the cookie is valid.

              get-domain -> String (none)
              The get-domain method returns the cookie domain value.

              set-domain -> none (String)
              The set-domain method sets the cookie domain value. It is string recommended to use
              the originator domain name since many http client can reject  cookie  those  domain
              name does not match the originator name.

              get-port -> Integer (none)
              The get-port method returns the cookie port number.

              set-port -> none (Integer)
              The  set-port  method  sets  the  cookie port number. This value is not used with a
              cookie version 0.

              get-comment -> String (none)
              The get-comment method returns the cookie comment value.

              set-comment -> none (String)
              The set-comment method sets the cookie comment value.

              get-comment-url -> String (none)
              The get-comment-url method returns the cookie comment url value.

              set-comment-url -> none (String)
              The set-comment-url method sets the cookie comment url value.  This  value  is  not
              used with cookie version 0.

              get-discard -> Boolean (none)
              The get-discard method returns the cookie discard flag.

              set-discard -> none (Boolean)
              The set-discard method sets the cookie discard flag. The discard flag the tells the
              user agent to destroy the cookie when it terminates. This value is  not  used  with
              cookie version 0.

              get-secure -> Boolean (none)
              The get-secure method returns the cookie secure flag.

              set-secure -> none (Boolean)
              The  set-secure method sets the cookie secure flag. When a cookie is secured, it is
              only returned by the http client if a connection has been secured (i.e use https).

              to-string -> String (none)
              The to-string method returns a string formatted for the http reply header. Normally
              this method should not be called since the set-cookie method of the httpReply takes
              care of such thing.

       Session
       The Session class is a class that defines a session to be associated with  a  transaction.
       The  session  object  is  designed  to  be  persistent so that its data information can be
       retreived at any time. A session object has also  the  particularity  to  have  a  limited
       lifetime.  A  session  object is created by name with an identifier. The session object is
       designed to hold a variety of parameters that are suitable for both the authentication and
       the  session lifetime. A session is primarily defined by name with an optional information
       string. The session is generally associated an  authentication  visa  which  contains  the
       session  identity.  The  visa provides a secure mechanism compatible with a single sign on
       session. A session key is automatically generated when the session is created. Such key is
       used to generate a session hash id which can be used as a cookie value. The cookie name is
       also stored in the session object. When a cookie is generated, the session  hash  name  is
       combined with the session hash id for the cookie production.

       Predicate

              session-p

       Inheritance

              Taggable

       Constructors

              Session (String)
              The  Session  constructor  creates  a  session  by name. The string argument is the
              session name.

              Session (String String)
              The Session constructor creates a session  with  a  name  and  a  user.  The  first
              argument is the session name. The second argument is the session information..

              Session (String String Integer)
              The  Session  constructor  creates a session with a name, a user and a maximum age.
              The first argument is  the  session  name.  The  second  argument  is  the  session
              informartion. The third argument is the session maximum age expressed in seconds.

       Methods

              expire-p -> Boolean (none)
              The expire-p predicate returns true if the session has expired.

              set-hash-id -> none (String)
              The  set-hash-id  method sets the session hash identifier. The session hash id must
              be unique and secured enough so that the session name cannot be derived from it.

              get-hash-id -> String (none)
              The get-hash-id method returns the session hash identifier.

              set-path -> none (String)
              The set-path method sets the session path.

              get-path -> String (none)
              The get-path method returns the session path.

              get-max-age -> Integer (none)
              The get-max-age method returns the session maximum age.

              set-max-age -> none (Integer)
              The set-max-age method sets the session maximum age. The maximum age is an  integer
              in  seconds  relative  to  the  current  time.  If the maximum age is set to 0, the
              session is closed.

              get-remaining-time -> Integer (none)
              The get-remaining-time method returns the remaining valid session time.

              get-expire-time -> Integer (none)
              The get-expire-time method returns the session  expiration  time  in  seconds.  The
              expiration time is an absolute time.

              set-expire-time -> none (Integer)
              The set-expire-time method sets the session expiration time. The expiration time is
              an absolute time in seconds.

              get-creation-time -> Integer (none)
              The get-creation-time method returns the session creation time. The  creation  time
              is an absolute time in seconds.

              get-modification-time -> Integer (none)
              The   get-modification-time   method   returns   the  session  creation  time.  The
              modification time is an absolute time in seconds.

              get-cookie -> Cookie (name)
              The get-cookie method bakes a session cookie. The string  argument  is  the  cookie
              name those value is the session hash id value.

              close -> Cookie (name)
              The  close  method  close  a  session by reseting the session maximum age to 0. The
              method returns a cookie that can be used for closing the session on the peer  side.
              The string argument is the cookie name those value is the session hash id value.

       Functions

              mime-extension-p -> Boolean (String)
              The  mime-extension-p  predicates  returns  true  if  a media type extension - mime
              extension - is defined. Most of the time, media type extension can  be  seen  as  a
              file extension.

              mime-value-p -> Boolean (String)
              The mime-value-p predicates returns true if a media type - mime value - is defined.

              extension-to-mime -> String (String [Boolean])
              The  extension-to-mime  function converts a media type extension into a media type.
              In the first form, without a second argument, if the media type extension does  not
              exist,  an exception is raised. In the second form, with the second argument set to
              true, if the media type extension  does  not  exist,  the  default  media  type  is
              returned. If the flag is set to false, an exception is raised like the first form.

              string-uri-p -> Boolean (String)
              The string-uri-p predicates returns true if the string argument is a uri.

              normalize-uri-name -> String (String)
              The  normalize-uri-name  function  normalizes  the  string argument by adding a uri
              scheme if missing in the original string. If the function  detects  that  the  name
              starts  with  a host name, the "http" scheme is added. If the function detects that
              the string starts with a path, the "file" scheme  is  added.  otherwise,  the  name
              argument is left untouched.

              system-uri-name -> String (String)
              The  system-uri-name  function  normalizes  the string argument by prioritizing the
              system name. The function attempts to find a file that match  the  string  argument
              and  eventually build a uri file scheme. If the file is not fond, the normalization
              process occurs with the normalize-uri-name function.

              path-uri-name -> String (String)
              The path-uri-name function normalizes the string  argument  by  extracting  a  path
              associated  with  the  uri string. If the string is a valid uri string, the path is
              the uri path component. If the uri path is empty, it is normalized to a /.  If  the
              string  argument is not a uri string, the string is assumed to be a partial uri and
              both query and fragment parts are removed if present.

              normalize-uri-host -> String (String)
              The normalize-uri-host function normalizes the string argument uri host name.  This
              function  is  useful  with  certain  class  of host representation which uses extra
              characters.

              normalize-uri-port -> String (String)
              The normalize-uri-port function normalizes the string argument uri port value. This
              function  is  useful  with  certain  class  of host representation which uses extra
              characters.