url/README.md

   1 # Chrome's URL library
   2
   3 ## Layers
   4
   5 There are several conceptual layers in this directory. Going from the lowest
   6 level up, they are:
   7
   8 ### Parsing
   9
  10 The `url_parse.*` files are the parser. This code does no string
  11 transformations. Its only job is to take an input string and split out the
  12 components of the URL as best as it can deduce them, for a given type of URL.
  13 Parsing can never fail, it will take its best guess. This layer does not
  14 have logic for determining the type of URL parsing to apply, that needs to
  15 be applied at a higher layer (the "util" layer below).
  16
  17 Because the parser code is derived (_very_ distantly) from some code in
  18 Mozilla, some of the parser files are in `url/third_party/mozilla/`.
  19
  20 The main header to include for calling the parser is
  21 `url/third_party/mozilla/url_parse.h`.
  22
  23 ### Canonicalization
  24
  25 The `url_canon*` files are the canonicalizer. This code will transform specific
  26 URL components or specific types of URLs into a standard form. For some
  27 dangerous or invalid data, the canonicalizer will report that a URL is invalid,
  28 although it will always try its best to produce output (so the calling code
  29 can, for example, show the user an error that the URL is invalid). The
  30 canonicalizer attempts to provide as consistent a representation as possible
  31 without changing the meaning of a URL.
  32
  33 The canonicalizer layer is designed to be independent of the string type of
  34 the embedder, so all string output is done through a `CanonOutput` wrapper
  35 object. An implementation for `std::string` output is provided in
  36 `url_canon_stdstring.h`.
  37
  38 The main header to include for calling the canonicalizer is
  39 `url/url_canon.h`.
  40
  41 ### Utility
  42
  43 The `url_util*` files provide a higher-level wrapper around the parser and
  44 canonicalizer. While it can be called directly, it is designed to be the
  45 foundation for writing URL wrapper objects (The GURL later and Blink's KURL
  46 object use the Utility layer to implement the low-level logic).
  47
  48 The Utility code makes decisions about URL types and calls the correct parsing
  49 and canonicalzation functions for those types. It provides an interface to
  50 register application-specific schemes that have specific requirements.
  51 Sharing this loigic between KURL and GURL is important so that URLs are
  52 handled consistently across the application.
  53
  54 The main header to include is `url/url_util.h`.
  55
  56 ### Google URL (GURL) and Origin
  57
  58 At the highest layer, a C++ object for representing URLs is provided. This
  59 object uses STL. Most uses need only this layer. Include `url/gurl.h`.
  60
  61 Also at this layer is also the Origin object which exists to make security
  62 decisions on the web. Include `url/origin.h`.
  63
  64 ## Historical background
  65
  66 This code was originally a separate library that was designed to be embedded
  67 into both Chrome (which uses STL) and WebKit (which didn't use any STL at the
  68 time). As a result, the parsing, canonicalization, and utility code could
  69 not use STL, or any other common code in Chromium like base.
  70
  71 When WebKit was forked into the Chromium repo and renamed Blink, this
  72 restriction has been relaxed somewhat. Blink still provides its own URL object
  73 using its own string type, so the insulation that the Utility layer provides is
  74 still useful. But some STL strings and calls to base functions have gradually
  75 been added in places where doing so is possible.