english
version "1.0"
identify "xyz"

#: Copyright (c) 1998 by Wayne C. Gramlich.
#, All rights reserved.
#, 
#, Permission to use, copy, modify, distribute, and sell this software
#, for any purpose is hereby granted without fee provided that the above
#, copyright notice and this permission are retained.  The author makes
#, no representations about the suitability of this software for any purpose.
#, It is provided "as is" without express or implied warranty.

module url

#: This module implements a mutable URL (Universal Resource Locator) object.

define url				#: Universal Resource Locator (URL) obj.
    record
	protocol_name string		#: Protocol name (or "")
	protocol_colon string		#: Colon following protocol (or "")
	host_slash_slash string		#: "//" (or "")
	host_name string		#: Host name (or "")
	port_colon string		#: Colon preceeding port number (or "")
	port_number string		#: Port number (or "")
	path_head_slash string		#: Preceeding slash for path (or "")
	path_twiddle string		#: Twiddle char. for user name (or "")
	path_user string		#: User name (or "")
	path_user_slash string		#: Slash following user name (or "")
	path string			#: Path preceeding document name (or "")
	path_tail_slash string		#: Slash following path (or "")
	document string			#: Name of doc. upto last period (or "")
	suffix_period string		#: Period preceeding suffix (or "")
	suffix_name string		#: Suffix name (or "")
	anchor_query_prefix string	#: Anchor/query char. ("#", "?", or "")
	anchor_query string		#: The anchor or query portion (or "")
    generate address_get, allocate, erase, identical



procedure replace@string
    takes
	to_string string
	from_string string
    returns_nothing

    #: This procedure will replace the contents of {to_string} with
    #, {from_string}.


procedure buffer_append@url
    takes
	url url
	buffer string
    returns_nothing

    #: This procedure will append {url} to {string}.


procedure clear@url
    takes
	url url
    returns_nothing

    #: This procedure will erase the contents of {url}.


procedure anchor_clear@url
    takes
	url url
    returns_nothing

    #: This procedure will clear the anchor portion of {url}.


procedure copy@url
    takes
	url url
    returns url

    #: This procedure will create and return a new {url} object that
    #, contains the contents of {url}.


procedure contents_copy@url
    takes
	to_url url
	from_url url
    returns url

    #: This procedure will copy the contents of {from_url} to {to_url}.


procedure compare@url
    takes
	url1 url
	url2 url
    returns integer

    #: This procedure will return -1, 0, or 1 depending upon whether
    #, {url1} is less than, equal to, or greater than {url2} on a field
    #, by field basis.


procedure create@url
    takes_nothing
    returns url

    #: This procedure will create and return an empty {url} object.


procedure equal@url
    takes
	url1 url
	url2 url
    returns logical

    #: This procedure will return {true}@{logical} if {url1} is equal to {url2}
    #, and {false} otherwise.


procedure format@url
    takes
	url url
	out_stream out_stream
	format string
	offset unsigned
    returns_nothing

    #: This procedure will cause {url} to be output to {out_stream}.


procedure full_path_buffer_append@url
    takes
	url url
	buffer string
    returns_nothing

    #: This routine append the full path portion of {url} to {buffer}.


procedure greater_than@url
    takes
	url1 url
	url2 url
    returns logical

    #: This procedure will return {true}@{logical} if {url1} is equal to {url2}
    #, and {false} otherwise.


procedure hash@out_stream
    takes
	url url
    returns unsigned

    #: This procedure will return a hash value for {url}.


procedure is_ftp@url
    takes
	url url
    returns logical

    #: This procedure will return {true}@{logical} if {url} uses the
    #, the FTP protocol and {false} otherwise.


procedure is_http@url
    takes
	url url
    returns logical

    #: This procedure will return {true}@{logical} if {url} uses the
    #, the HTTP protocol and {false} otherwise.


procedure less_than@url
    takes
	url1 url
	url2 url
    returns logical

    #: This procedure will return {true}@{logical} if {url1} is equal to {url2}
    #, and {false} otherwise.


procedure merge@url
    takes
	result_url url
	base_url url
	partial_url url
    returns url

    #: This procedure will merge {partial_url} with {base_url} and store
    #, the result into {result_url}.


procedure merge_create@url
    takes
	base_url url
	partial_url url
    returns url

    #: This procedure will create and return a new absolute URL from
    #, the combiniation of {partial_url} and {base_url}.


procedure parse_create@url
    takes
	url_string string
    returns url

    #: This procedure will parse {url_string} and create and return the
    #, the corresponding {url}.  If there are any parsing errors, or the
    #, string is not completely parsed, ??@{url} is returned.


procedure parse_into@url
    takes
	url url
	string string
	offset unsigned
    returns unsigned

    #: This procedure will parse a URL from {string} starting at
    #, {offset} and store the resulting URL into {url}.  The offset
    #, to the last character parsed is returned.  If there are any
    #, parsing errors, the size of {string} plus 1 is returned.

    #: Parse the "PROTOCOL:"

procedure path_normalize@url
    takes
	url url
    returns logical

    #: This procedure will attempt to remove extraneous information
    #, from {url}.  This involves removing "dir_name/..", "//", and
    #, "./" from the path.  If there is an attempt to apply too many
    #, "../" operattions, {true}@{logical} is returned; otherwise,
    #, {false} is returned.

    #, have to do a bounds check when we have a "/":

procedure print@url
    takes
	url url
	out_stream out_stream
    returns_nothing

    #: This procedure will print {url} to {out_stream}.


procedure show@url
    takes
	url url
	out_stream out_stream
    returns_nothing

    #: This procedure will print out each component of {url} to {out_stream}.


procedure size_get@url
    takes
	url url
    returns unsigned

    #: This procedure will return the total number of characters in {url}.