Simplified the API and updated the README

README.md

@@ -1,3 +1,9 @@
 # url.c
+This is a small library to parse and manipulate URLs in conformance to RFC 3986 and WHATWG.
 
-Small library to parse URLs.
+It features
+* No allocations
+* No dependencies
+* The ability to switch between RFC 3986 and WHATWG with a flag
+* Relative reference parsing and resolution
+* URL normalization

url.c

@@ -211,7 +211,12 @@ int url_parse_ipv4(char *src, int len, int *pcur, URL_IPv4 *out)
         out->data |= byte;
     }
 
-    if (pcur) *pcur = cur;
+    if (pcur) {
+        *pcur = cur;
+    } else {
+        if (cur != len)
+            return -1;
+    }
     return 0;
 }
 
@@ -318,10 +323,16 @@ int url_parse_ipv6(char *src, int len, int *pcur, URL_IPv6 *out)
 	for (int i = 0; i < tail_len; i++)
 		out->data[8 - tail_len + i] = tail[i];
 
-	return 0;
+	if (pcur) {
+        *pcur = cur;
+    } else {
+        if (cur != len)
+            return -1;
+    }
+    return 0;
 }
 
-static int parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
+int url_parse(char *src, int len, int *pcur, URL *out, int flags)
 {
     int cur = pcur ? *pcur : 0;
 
@@ -349,6 +360,11 @@ static int parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
         }
     }
 
+    // If the user doesn't allow references and we didn't
+    // find a scheme, we fail.
+    if ((flags & URL_FLAG_ALLOWREF) == 0 && out->scheme.len == 0)
+        return -1;
+
     // If the following characters are // we expect an
     // authority. An authority consists of some optional
     // userinfo, a domain name, and a port.
@@ -501,7 +517,7 @@ static int parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
 
             // The WHATWG standard forbids port numbers with the
             // "file" protocol.
-            if (!strict) {
+            if ((flags & URL_FLAG_RFC3986) == 0) {
                 if (streq(out->scheme, S("file")))
                     return -1;
             }
@@ -523,7 +539,7 @@ static int parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
         // The WHATWG standard considers the sequence "//"
         // part of the path and not the authority if userinfo,
         // host, and port are missing
-        if (!strict) {
+        if ((flags & URL_FLAG_RFC3986) == 0) {
             if ((streq(out->scheme, S("http")) || streq(out->scheme, S("https")))
                 && out->username.len == 0
                 && out->password.len == 0
@@ -573,7 +589,7 @@ static int parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
 
     // For a subset of protocols, WHATWG sets the default
     // path to "/"
-    if (!strict) {
+    if ((flags & URL_FLAG_RFC3986) == 0) {
         if (out->path.len == 0 && (
             streq(out->scheme, S("ftp")) ||
             streq(out->scheme, S("file")) ||
@@ -645,17 +661,6 @@ static int parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
     return 0;
 }
 
-int url_parse(char *src, int len, int *pcur, URL_b32 strict, URL *out)
-{
-    int ret = parse(src, len, pcur, strict, out);
-    if (ret < 0)
-        return ret;
-
-    if (out->scheme.len == 0)
-        return -1;
-    return 0;
-}
-
 #define PATH_COMPONENT_LIMIT 32
 
 typedef struct {
@@ -770,77 +775,76 @@ static void append_authority(Builder *b, URL url)
     }
 }
 
-int url_resolve_reference(char *src, int len, int *pcur,
+static void append_scheme(Builder *b, URL_String scheme)
-    URL *base, URL_b32 strict, char *dst, int cap)
+{
+    ASSERT(scheme.len > 0);
+    append(b, scheme); // TODO: normalize
+    append(b, S(":"));
+}
+
+static void append_query(Builder *b, URL_String query)
+{
+    if (query.len > 0) {
+        append(b, S("?"));
+        append(b, query);
+    }
+}
+
+static void append_fragment(Builder *b, URL_String fragment)
+{
+    if (fragment.len > 0) {
+        append(b, S("#"));
+        append(b, fragment);
+    }
+}
+
+int url_serialize(URL *url, URL *base, char *dst, int cap)
 {
     if (base != NULL && base->scheme.len == 0)
         return -1; // Base is not an absolute URL
 
-    URL ref;
-    int ret = parse(src, len, pcur, strict, &ref);
-    if (ret < 0)
-        return ret;
-
     Builder b = { dst, cap, 0 };
-    if (ref.scheme.len > 0) {
+    if (url->scheme.len > 0) {
-        append(&b, ref.scheme);
+        append_scheme(&b, url->scheme);
-        append(&b, S(":"));
+        append_authority(&b, url);
-        append_authority(&b, ref);
+        append(&b, url->path);
-        append(&b, ref.path);
+        append_query(&b, url->query);
-        if (ref.query.len > 0) {
-            append(&b, S("?"));
-            append(&b, ref.query);
-        }
     } else {
-
         if (base == NULL) {
             // No base URL provided, which means the
             // source is required to be an absolute URL
             return -1;
         }
-
         ASSERT(base->scheme.len > 0);
-        append(&b, base->scheme);
+        append_scheme(&b, base->scheme);
-        append(&b, S(":"));
+        if (!url->no_authority) {
-        if (!ref.no_authority) {
+            append_authority(&b, url);
-
-            append_authority(&b, ref);
-
             PathComps comps = {0};
-            if (resolve_dots_and_append_comps(&comps, ref.path) < 0)
+            if (resolve_dots_and_append_comps(&comps, url->path) < 0)
                     return -1;
             for (int i = 0; i < comps.count; i++) {
                 append(&b, S("/"));
                 append(&b, comps.stack[i]);
             }
-
+            append_query(&b, url->query);
-            if (ref.query.len > 0) {
-                append(&b, S("?"));
-                append(&b, ref.query);
-            }
-
         } else {
-
             append_authority(&b, *base);
-
+            if (url->path.len == 0) {
-            if (ref.path.len == 0) {
                 append(&b, base->path);
-                if (ref.query.len > 0) {
+                if (url->query.len > 0) {
-                    append(&b, S("?"));
+                    append_query(&b, url->query);
-                    append(&b, ref.query);
+                } else {
-                } else if (base->query.len > 0) {
+                    append_query(&b, base->query);
-                    append(&b, S("?"));
-                    append(&b, base->query);
                 }
             } else {
-                ASSERT(ref.path.len > 0);
+                ASSERT(url->path.len > 0);
                 PathComps comps = {0};
-                if (ref.path.ptr[0] == '/') {
+                if (url->path.ptr[0] == '/') {
-                    if (resolve_dots_and_append_comps(&comps, ref.path) < 0)
+                    if (resolve_dots_and_append_comps(&comps, url->path) < 0)
                         return -1;
                 } else {
                     if (!base->no_authority && base->path.len == 0) {
-                        if (resolve_dots_and_append_comps(&comps, ref.path) < 0)
+                        if (resolve_dots_and_append_comps(&comps, url->path) < 0)
                             return -1;
                     } else {
                         if (resolve_dots_and_append_comps(&comps, base->path) < 0)
@@ -848,7 +852,7 @@ int url_resolve_reference(char *src, int len, int *pcur,
                         if (comps.count > 0) {
                             comps.count--;
                         }
-                        if (resolve_dots_and_append_comps(&comps, ref.path) < 0)
+                        if (resolve_dots_and_append_comps(&comps, url->path) < 0)
                             return -1;
                     }
                 }
@@ -856,18 +860,11 @@ int url_resolve_reference(char *src, int len, int *pcur,
                     append(&b, S("/"));
                     append(&b, comps.stack[i]);
                 }
-                if (ref.query.len > 0) {
+                append_query(&b, url->query);
-                    append(&b, S("?"));
-                    append(&b, ref.query);
-                }
             }
         }
     }
-
+    append_fragment(&b, url->fragment);
-    if (ref.fragment.len > 0) {
-        append(&b, S("#"));
-        append(&b, ref.fragment);
-    }
 
     return b.len;
 }
@@ -902,10 +899,10 @@ int url_remove_white_space(char *src, int len, char *dst, int cap)
     return copied;
 }
 
-int url_decode_field(URL_String field, char *dst, int cap)
+int url_percent_decode(URL_String str, char *dst, int cap)
 {
-    char *src = field.ptr;
+    char *src = str.ptr;
-    int   len = field.len;
+    int   len = str.len;
     int   rd  = 0;
     int   wr  = 0;
 

url.h

@@ -62,10 +62,20 @@ URL_STATIC_ASSERT(sizeof(URL_IPv6) == 16, "");
 
 typedef struct {
 
+    // These flags are used to differentiate between
+    // an empty userinfo/authority and an undefined one.
+    // For instance:
+    //     http:index.html      URL with no authority
+    //     http:///index.html   URL with an empty authority
+    //     http://example.com   URL with no userinfo
+    //     http://:@example.com URL with an empty userinfo
+    // We keep track of this in case we want to encode
+    // back the parsed URL.
     URL_b32 no_authority;
     URL_b32 no_userinfo;
 
-    // May be empty
+    // Can only be empty when URL_FLAG_ALLOWREF is passed
+    // to url_parse.
     URL_String scheme;
 
     // Both may be empty
@@ -100,16 +110,75 @@ typedef struct {
 
 } URL;
 
+// Parse an IPv4 in dotted-decimal notation (127.0.0.1)
+// If pcur is not NULL, parsing starts at offset *pcur
+// and the final cursor state is written back into pcur.
+// If pcur is NULL, the string is assumed to only contain
+// the IPv4 address, so the function fails if the string
+// contains anything else after it.
 int url_parse_ipv4(char *src, int len, int *pcur, URL_IPv4 *out);
+
+// Like url_parse_ipv4, but for IPv6 addresses.
 int url_parse_ipv6(char *src, int len, int *pcur, URL_IPv6 *out);
 
-int url_parse(char *src, int len, int *pcur, URL_b32 strict, URL *out);
+enum {
+    URL_FLAG_ALLOWREF = 1<<0,
+    URL_FLAG_RFC3986  = 1<<1,
+};
 
-int url_resolve_reference(char *src, int len, int *pcur,
+// Parses the URL contained in the string "src" of length "len"
-    URL *base, URL_b32 strict, char *dst, int cap);
+// into the structure "out". The output structure will hold
+// references to the input buffer. Any percent-encoded components
+// are validated but not converted. The percent-decoded version
+// of a component can be obtained by calling url_percent_decode.
+//
+// If "pcur" is not null, the parsing will start at offset *pcur
+// and the final position of the cursor will be stored back in
+// pcur. If pcur is NULL, the string is expected to only contain
+// the URL, so the function fails if the string contains something
+// other than the URL.
+//
+// If "flags" is zero, the function will parse URLs according
+// to the WHATWG specification (which is what browsers actually
+// do). Strictly speaking, to adhere to WHATWG the parser needs
+// to strip whitespace from the URL before processing it, which
+// this function doesn't do. If you want this behavior, you must
+// preprocess the input with url_remove_white_space.
+//
+// If the flag URL_FLAG_RFC3986 is passed, the parser will strictly
+// adhere to RFC 3986.
+//
+// If the flag URL_FLAG_ALLOWREF is passed, then relative
+// references may also be parsed. These include things like
+// "../index.html", which are not URLs but may be evaluated as
+// such in relation to one. Relative references may be resolved
+// using url_serialize.
+int url_parse(char *src, int len, int *pcur, URL *out, int flags);
 
+// Remove whitespace from the string "src" of length "len"
+// according to the WHATWG specification. Using this function
+// alongside url_parse has the same behavior to what browsers
+// do.
+// The result string is written to the buffer "dst" of capacity
+// "cap". If the buffer isn't large enough, the number of bytes
+// that would have been written is returned.
 int url_remove_white_space(char *src, int len, char *dst, int cap);
 
-int url_decode_field(URL_String field, char *dst, int cap);
+// Percent-decodes the string "str" into the buffer "dst" of
+// capacity "cap". If the buffer's capacity wasn't enough, the
+// number of bytes that would have been written is returned.
+// If the string wasn't percent-encoded (% characters not followed
+// by valid hex digits), -1 is returned.
+int url_percent_decode(URL_String str, char *dst, int cap);
+
+// Serializes "url" into the buffer "dst" of capacity "cap".
+// If the capacity wasn't enough, the number of bytes that
+// would have been written is returned.
+// If "url" is a relative reference, then it is resolved
+// against the absolute URL "base", which can otherwite be
+// set to NULL.
+// Note that this can be used to normalize an URL, even
+// though it's just a best-effor normalization for now.
+int url_serialize(URL *url, URL *base, char *dst, int cap);
 
 #endif // URL_INCLUDED