man(1) Manual page archive


     W3C-URIS(2)                                           W3C-URIS(2)

     NAME
          w3c-uris - uniform resource identifiers

     SYNOPSIS
          include "uris.m";

          uris := load URIs URIs->PATH;
          URI: import uris;

          URI: adt
          {
             scheme:     string;
             userinfo:   string;  # authority, part I
             host:       string;  # authority, part II
             port:       string;  # authority, part III
             path:       string;  # starts with / if absolute
             query:      string;  # includes ? if not nil
             fragment:   string;  # includes # if not nil

             parse:      fn(s: string): ref URI;
             text:       fn(u: self ref URI): string;
             addbase:    fn(base: self ref URI, rel: ref URI): ref URI;
             authority:  fn(u: self ref URI): string;
             copy:       fn(u: self ref URI): ref URI;
             eq:         fn(u: self ref URI, v: ref URI): int;
             hasauthority: fn(u: self ref URI): int;
             isabsolute: fn(u: self ref URI): int;
             nodots:     fn(u: self ref URI): ref URI;
             userpw:     fn(u: self ref URI): (string, string);
          };

          init: fn();
          dec:  fn(s: string): string;
          enc:  fn(s: string, safe: string): string;

     DESCRIPTION
          URIs supports the `generic syntax' for `Uniform' Resource
          Identifiers (URIs), defined by RFC3986.  Each URI can have
          up to five components in the general syntax:

               scheme: //authority/path ?query #fragment

          where each component is optional, and can have scheme-
          specific substructure.  For instance, in the ftp, http
          schemes, and perhaps others, the authority component has the
          further syntax:

               userinfo@host:port

          The set of characters allowed in most components is also

     W3C-URIS(2)                                           W3C-URIS(2)

          scheme-specific, as is their interpretation, and indeed the
          interpretation of the component itself.

          Init must be called before any other operation in the mod-
          ule.

          URI represents a parse of a URI into its components, where
          the authority has been further split into the scheme-
          specific but common triple of userinfo, host and port. (The
          function URI.authority will reproduce the original authority
          component if required.)  The query field starts with the `?'
          character that introduces the query component, so that an
          empty query is represented by the string "?", and the
          absence of a query component is represented by a nil value.
          The fragment field is handled in a similar way with its
          delimiting `#'.  The fields representing the other compo-
          nents do not include the delimiters in the syntax, and all
          but query have percent-encoded characters decoded.  (The
          query string is an exception because the set of characters
          to escape is application-specific.  See below for decoding
          and encoding functions.)  URI provides the following opera-
          tions:

          parse(s)
               Return a URI value representing the results of parsing
               string s as a URI.  There is no error return.  The com-
               ponent values have percent-escapes decoded as discussed
               above.  The scheme name is converted to lower case.

          u.text()
               Return the textual representation of u in the generic
               syntax, adding percent-encoding as required to prevent
               characters being misinterpreted as delimiters.

          u.addbase(b)
               Resolves URI reference u with respect to a base URI b,
               including resolving all `.'  and `..'  segments in the
               URI's path, and returns the resulting URI value.  If u
               is an absolute URI reference or b is nil, the result is
               the same as u except that all `.'  and `..'  segments
               have been resolved in the resulting path, and leading
               instances of them removed.

          u.authority()
               Returns the text of the authority component of u, in
               the generic syntax, created from its userinfo, host and
               port components.

          u.copy()
               Return a reference to an independent copy of u.

          u.eq(v)

     W3C-URIS(2)                                           W3C-URIS(2)

               Returns true if u and v are textually equal in all com-
               ponents except fragment.  Note that u and v are assumed
               to be in a canonical  form for the scheme and applica-
               tion.

          u.eqf(v)
               Returns true if u and v are textually equal in all com-
               ponents including fragment.

          u.hasauthority()
               Returns true if any of the authority subcomponents of u
               are not nil; returns false otherwise.

          u.isabsolute()
               Returns true if u has a scheme component; returns false
               otherwise.

          u.nodots()
               Returns a new URI value in which all `.'  and `..'
               segments have been resolved (equivalent to
               u.addbase(nil)).

          u.userpw()
               Returns a tuple (username, password) derived from pars-
               ing the userinfo subcomponent of authority using the
               deprecated but depressingly still common convention
               that userinfo has the syntax ``username:password''.

          A reserved or otherwise special character that appears in a
          URI component must be encoded using a sequence of one or
          more strings of the form %xx where xx is the hexadecimal
          value of one byte of the character.  A string s containing
          such encodings can be decoded by the function dec.  A string
          s can be encoded by enc, where the parameter safe lists the
          characters that need not be escaped (where safe may be nil
          or empty).  These functions are normally only needed to
          decode and encode the values of URI.query, because URI.parse
          and URI.text above decode and encode the other fields.

     SOURCE
          /appl/lib/w3c/uris.b

     SEE ALSO
          charon(1), httpd(8)