--****

-- == URL handling

--

namespace url

include std/get.e

include std/map.e

--****

-- === Parsing

--

--**

-- Parse a query string into a map

--

-- Parameters:

-- # ##query_string##: Query string to parse

--

-- Returns:

-- [[:map]] containing the key/value pairs

--

-- Example 1:

--

-- map qs = parse_querystring("name=John&age=18")

-- printf(1, "%s is %s years old\n", { map:get(qs, "name"), map:get(qs, "age) })

--

--

atom i, char

object tmp

end if

else

end if

end if

end function

--**

-- Parse a URL returning its various elements.

--

-- Parameters:

-- # ##url##: URL to parse

-- # ##querystring_also##: Parse the query string into a map also?

--

-- Returns:

-- A multi-element sequence containing:

-- # protocol

-- # host name

-- # port

-- # path

-- # user name

-- # password

-- # query string

--

-- Or, zero if the URL could not be parsed.

--

-- Notes:

-- If the host name, port, path, username, password or query string are not part of the

-- URL they will be returned as an integer value of zero.

--

-- Example 1:

--

-- sequence parsed = parse("http://user:pass@www.debian.org:80/index.html?name=John&age=39")

-- -- parsed is

-- -- {

-- -- "http",

-- -- "www.debian.org",

-- -- 80,

-- -- "/index.html",

-- -- "user",

-- -- "pass",

-- -- "name=John&age=39"

-- -- }

--

--

object host_name, path, user_name, password, query_string

integer port

-- Set the defaults for some optional values

end if

-- Can have a maximum of 2 // before we move into the hostname or possibly

-- the path (http://john.com) or (file:///home/jeremy/hello.txt)

end if

end if

-- We do not have a username, password, host or port, we have moved right into

-- the path area of the URL. Let's jump ahead

end if

-- We do not have a user or password, skip ahead to parsing the domain

end if

-- We have a password too!

else

-- Just a user name

end if

label "parse_domain"

-- We can easily read the host until the port colon

else

-- Gotta go through a bit more complex way of getting the path

-- there is no path, thus we must parse to either the query string begin

-- or the string end

else

end if

else

-- Ok, we can read up to the first slash

end if

end if

else

end if

end if

-- Increment the position to the next element to parse

else

-- Nothing more to parse

end if

label "parse_path"

end if

-- Avoid getting a path when there is none.

end if

label "parse_query_string"

end if

label "parse_done"

end function

--****

-- === URL encoding and decoding

--

-- TODO: This is causing a creole parsing problem

-- HTML form data is usually URL-encoded to package it into a GET or POST submission.

-- In a nutshell, here's how you URL-encode the name-value pairs of the form data:

-- # Convert all "unsafe" characters in the names and values to "%xx", where "xx" is the ascii

-- value of the character, in hex. "Unsafe" characters include =, &, %, +, non-printable

-- characters, and any others you want to encode-- there's no danger in encoding too many

-- characters. For simplicity, you might encode all non-alphanumeric characters.

-- A big nono is \n and \r chars in POST data.

-- # Change all spaces to pluses.

-- # String the names and values together with = and &, like

-- name1=value1&name2=value2&name3=value3

-- # This string is your message body for POST submissions, or the query string for GET submissions.

--

-- For example, if a form has a field called "name" that's set to "Lucy", and a field called "neighbors"

-- that's set to "Fred & Ethel", the URL-encoded form data would be:

--

-- name=Lucy&neighbors=Fred+%26+Ethel <<== note no \n or \r

--

-- with a length of 34.

constant

--**

-- Converts all non-alphanumeric characters in a string to their

-- percent-sign hexadecimal representation, or plus sign for

-- spaces.

--

-- Parameters:

-- # ##what## : the string to encode

-- # ##spacecode## : what to insert in place of a space

--

-- Returns:

-- A **sequence**, the encoded string.

--

-- Comments:

-- ##spacecode## defaults to ##+## as it is more correct, however, some sites

-- want ##%20## as the space encoding.

--

-- Example 1:

--

-- puts(1, encode("Fred & Ethel"))

-- -- Prints "Fred+%26+Ethel"

--

--

-- See Also:

-- [[:decode]]

--

end if

end function

--**

-- Convert all encoded entities to their decoded counter parts

--

-- Parameters:

-- # ##what##: what value to decode

--

-- Returns:

-- A decoded sequence

--

-- Example 1:

--

-- puts(1, decode("Fred+%26+Ethel"))

-- -- Prints "Fred & Ethel"

--

--

-- See Also:

-- [[:encode]]

--

-- strip empty percent sign

else

end if

else

-- do nothing if it is a regular char ('0' or 'A' or etc)

end if

end function