PageRenderTime 54ms CodeModel.GetById 23ms RepoModel.GetById 0ms app.codeStats 0ms

/0.8-beta/uri.html

https://github.com/cpp-netlib/cpp-netlib.github.com
HTML | 284 lines | 259 code | 25 blank | 0 comment | 0 complexity | 4630bd1facacea0b5ba316cabac8a376 MD5 | raw file
    

  1. 

  2. 

  3. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    4. 

  4.   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    5. 

  5. 

  6. <html xmlns="http://www.w3.org/1999/xhtml">
    7. 

  7.   <head>
    8. 

  8.     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    9. 

  9.     
    10. 

  10.     <title>The URI template &mdash; cpp-netlib v0.8 documentation</title>
    11. 

  11.     <link rel="stylesheet" href="_static/cpp-netlib.css" type="text/css" />
    12. 

  12.     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    13. 

  13.     <script type="text/javascript">
    14. 

  14.       var DOCUMENTATION_OPTIONS = {
    15. 

  15.         URL_ROOT:    '',
    16. 

  16.         VERSION:     '0.8',
    17. 

  17.         COLLAPSE_INDEX: false,
    18. 

  18.         FILE_SUFFIX: '.html',
    19. 

  19.         HAS_SOURCE:  true
    20. 

  20.       };
    21. 

  21.     </script>
    22. 

  22.     <script type="text/javascript" src="_static/jquery.js"></script>
    23. 

  23.     <script type="text/javascript" src="_static/underscore.js"></script>
    24. 

  24.     <script type="text/javascript" src="_static/doctools.js"></script>
    25. 

  25.     <link rel="top" title="cpp-netlib v0.8 documentation" href="index.html" />
    26. 

  26.     <link rel="up" title="An in-depth look at the cpp-netlib" href="in_depth.html" />
    27. 

  27.     <link rel="next" title="HTTP implementation" href="http.html" />
    28. 

  28.     <link rel="prev" title="The message template" href="message.html" /> 
    29. 

  29.   </head>
    30. 

  30.   <body>
    31. 

  31. 

  32.     <div class="document">
    33. 

  33.   <div id="custom-doc" class="yui-t4">
    34. 

  34.     <div id="hd">
    35. 

  35.       <h1><a href="index.html">cpp-netlib v0.8 documentation</a></h1>
    36. 

  36.       <div class="nav">
    37. 

  37.     &laquo; <a href="message.html" title="The message template">previous</a>
    38. 

  38.      |
    39. 

  39.     <a href="in_depth.html" title="An in-depth look at the &lt;tt class=&#34;docutils literal docutils literal docutils literal docutils literal docutils literal&#34;&gt;&lt;span class=&#34;pre&#34;&gt;cpp-netlib&lt;/span&gt;&lt;/tt&gt;" accesskey="U">up</a>
    40. 

  40.    |
    41. 

  41.     <a href="http.html" title="HTTP implementation">next</a> &raquo;</div>
    42. 

  42.     </div>
    43. 

  43. 

  44.     <div id="bd">
    45. 

  45.       <div id="yui-main">
    46. 

  46.         <div class="yui-b">
    47. 

  47.           <div class="yui-g" id="uri">
    48. 

  48.             
    49. 

  49.   <div class="section" id="the-uri-template">
    50. 

  50. <h1>The URI template<a class="headerlink" href="#the-uri-template" title="Permalink to this headline"></a></h1>
    51. 

  51. <p>In addition to protocol implementations, the <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>
    52. 

  52. provides a powerful URI template.  The URI template implements a
    53. 

  53. parser based on <a class="reference external" href="http://tools.ietf.org/html/rfc3986">RFC 3986</a>.</p>
    54. 

  54. <div class="section" id="generic-uri-syntax-overview">
    55. 

  55. <h2>Generic URI Syntax Overview<a class="headerlink" href="#generic-uri-syntax-overview" title="Permalink to this headline"></a></h2>
    56. 

  56. <p>A generic URI will take the form:</p>
    57. 

  57. <div class="highlight-python"><pre>[scheme:]scheme-specific-part[#fragment]</pre>
    58. 

  58. </div>
    59. 

  59. <p>A URI is known as <cite>absolute</cite> if it specifies the scheme.  Otherwise,
    60. 

  60. it is known as a relative URI.  Currently, <tt class="docutils literal"><span class="pre">basic_uri</span></tt> supports
    61. 

  61. only absolute URIs.</p>
    62. 

  62. <p>URIs can be further classified according to whether they&#8217;re
    63. 

  63. hierarchical or opaque (non-hierarchical).</p>
    64. 

  64. <p>Some examples of non-hierarchical URIs include:</p>
    65. 

  65. <div class="highlight-python"><pre>mailto:john.doe@example.com
    66. 

  66. news:comp.infosystems.www.servers.unix
    67. 

  67. tel:+1-816-555-1212</pre>
    68. 

  68. </div>
    69. 

  69. <p>The data following the first <tt class="docutils literal"><span class="pre">&quot;:&quot;</span></tt> is said to be opaque to the URI
    70. 

  70. parser and requires no further parsing.  By way of example, the
    71. 

  71. following shows how a non-hierarchical URI is processed by the parser
    72. 

  72. by defining everything after the <tt class="docutils literal"><span class="pre">&quot;:&quot;</span></tt> to be a part of the path:</p>
    73. 

  73. <img alt="_images/mailto_uri.png" src="_images/mailto_uri.png" />
    74. 

  74. <p>A hierarchical URI is identified by a double slash (<tt class="docutils literal"><span class="pre">&quot;//&quot;</span></tt>) after
    75. 

  75. the scheme and a scheme-specific component, which <a class="reference external" href="http://tools.ietf.org/html/rfc3986">RFC 3986</a> defines
    76. 

  76. to be:</p>
    77. 

  77. <div class="highlight-python"><pre>[scheme:][//authority][path][?query][#fragment]</pre>
    78. 

  78. </div>
    79. 

  79. <p>The authority component can be further broken down to:</p>
    80. 

  80. <div class="highlight-python"><pre>[user_info@]host[:port]</pre>
    81. 

  81. </div>
    82. 

  82. <p>Examples of hierarchical URIs include:</p>
    83. 

  83. <div class="highlight-python"><pre>http://www.boost.org/
    84. 

  84. file:///bin/bash</pre>
    85. 

  85. </div>
    86. 

  86. <p>The following example, describing a complex URI using FTP, shows how
    87. 

  87. a URI is broken down by the parser:</p>
    88. 

  88. <img alt="_images/ftp_uri.png" src="_images/ftp_uri.png" />
    89. 

  89. <p>Note that the <tt class="docutils literal"><span class="pre">authority</span></tt> is further subdivided into different
    90. 

  90. elements.  Another example, using HTTP is given below:</p>
    91. 

  91. <img alt="_images/http_uri.png" src="_images/http_uri.png" />
    92. 

  92. <p>The difference here between the path in a hierarchical URI and that in
    93. 

  93. the example above for the non-hierarchical URI.</p>
    94. 

  94. </div>
    95. 

  95. <div class="section" id="basic-uri">
    96. 

  96. <h2><tt class="docutils literal"><span class="pre">basic_uri</span></tt><a class="headerlink" href="#basic-uri" title="Permalink to this headline"></a></h2>
    97. 

  97. <p>The <tt class="docutils literal"><span class="pre">basic_uri</span></tt> definition is consistent with that of
    98. 

  98. <tt class="docutils literal"><span class="pre">basic_message</span></tt>:</p>
    99. 

  99. <div class="highlight-python"><pre>template &lt;class Tag&gt;
    100. 

  100. class basic_uri;</pre>
    101. 

  101. </div>
    102. 

  102. <p>As it stands, the template only supplies a URI parser and no builder.
    103. 

  103. To use the parser, it&#8217;s as simple as supplying a string to the
    104. 

  104. constructor:</p>
    105. 

  105. <div class="highlight-python"><pre>boost::network::uri::uri instance("http://cpp-netlib.github.com/");
    106. 

  106. assert(boost::is_valid(instance));
    107. 

  107. std::cout &lt;&lt; "scheme: " &lt;&lt; boost::network::uri::scheme(instance) &lt;&lt; std::endl
    108. 

  108.           &lt;&lt; "host: " &lt;&lt; boost::network::uri::host(instance) &lt;&lt; std::endl;</pre>
    109. 

  109. </div>
    110. 

  110. <p>The command-line output of this program will be:</p>
    111. 

  111. <div class="highlight-python"><pre>scheme: http
    112. 

  112. host: cpp-netlib.github.com</pre>
    113. 

  113. </div>
    114. 

  114. <p>A future version of <tt class="docutils literal"><span class="pre">basic_uri</span></tt> will provide a full builder API.</p>
    115. 

  115. </div>
    116. 

  116. <div class="section" id="uri-concept">
    117. 

  117. <h2><tt class="docutils literal"><span class="pre">URI</span> <span class="pre">Concept</span></tt><a class="headerlink" href="#uri-concept" title="Permalink to this headline"></a></h2>
    118. 

  118. <p><strong>Legend</strong></p>
    119. 

  119. <table class="docutils field-list" frame="void" rules="none">
    120. 

  120. <col class="field-name" />
    121. 

  121. <col class="field-body" />
    122. 

  122. <tbody valign="top">
    123. 

  123. <tr class="field"><th class="field-name">U:</th><td class="field-body">The URI type.</td>
    124. 

  124. </tr>
    125. 

  125. <tr class="field"><th class="field-name">u,u_:</th><td class="field-body">An instance of <strong>M</strong>.</td>
    126. 

  126. </tr>
    127. 

  127. <tr class="field"><th class="field-name">S:</th><td class="field-body">A string type.</td>
    128. 

  128. </tr>
    129. 

  129. <tr class="field"><th class="field-name">s,v:</th><td class="field-body">An instance of <strong>S</strong>.</td>
    130. 

  130. </tr>
    131. 

  131. <tr class="field"><th class="field-name">T:</th><td class="field-body">The Tag type.</td>
    132. 

  132. </tr>
    133. 

  133. </tbody>
    134. 

  134. </table>
    135. 

  135. <table border="1" class="docutils">
    136. 

  136. <colgroup>
    137. 

  137. <col width="31%" />
    138. 

  138. <col width="24%" />
    139. 

  139. <col width="45%" />
    140. 

  140. </colgroup>
    141. 

  141. <thead valign="bottom">
    142. 

  142. <tr><th class="head">Construct</th>
    143. 

  143. <th class="head">Result</th>
    144. 

  144. <th class="head">Description</th>
    145. 

  145. </tr>
    146. 

  146. </thead>
    147. 

  147. <tbody valign="top">
    148. 

  148. <tr><td><tt class="docutils literal"><span class="pre">U(u)</span></tt></td>
    149. 

  149. <td>Instance of U</td>
    150. 

  150. <td>Copy constructible.</td>
    151. 

  151. </tr>
    152. 

  152. <tr><td><tt class="docutils literal"><span class="pre">U(s)</span></tt></td>
    153. 

  153. <td>Instance of U</td>
    154. 

  154. <td>Constructible from string.</td>
    155. 

  155. </tr>
    156. 

  156. <tr><td><tt class="docutils literal"><span class="pre">u</span> <span class="pre">=</span> <span class="pre">u_;</span></tt></td>
    157. 

  157. <td>Reference to u</td>
    158. 

  158. <td>Assignable.</td>
    159. 

  159. </tr>
    160. 

  160. <tr><td><tt class="docutils literal"><span class="pre">u</span> <span class="pre">=</span> <span class="pre">s;</span></tt></td>
    161. 

  161. <td>Reference to u</td>
    162. 

  162. <td>Assignable from string.</td>
    163. 

  163. </tr>
    164. 

  164. <tr><td><tt class="docutils literal"><span class="pre">swap(u,</span> <span class="pre">u_);</span></tt></td>
    165. 

  165. <td><tt class="docutils literal"><span class="pre">void</span></tt></td>
    166. 

  166. <td>Swappable.</td>
    167. 

  167. </tr>
    168. 

  168. <tr><td><tt class="docutils literal"><span class="pre">scheme(u);</span></tt></td>
    169. 

  169. <td>Convertible to S</td>
    170. 

  170. <td>Retrieve the URI scheme of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    171. 

  171. </tr>
    172. 

  172. <tr><td><tt class="docutils literal"><span class="pre">user_info(u);</span></tt></td>
    173. 

  173. <td>Convertible to S</td>
    174. 

  174. <td>Retrieve the user info of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    175. 

  175. </tr>
    176. 

  176. <tr><td><tt class="docutils literal"><span class="pre">host(u);</span></tt></td>
    177. 

  177. <td>Convertible to S</td>
    178. 

  178. <td>Retrieve the host of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    179. 

  179. </tr>
    180. 

  180. <tr><td><tt class="docutils literal"><span class="pre">port(u);</span></tt></td>
    181. 

  181. <td>Convertible to H</td>
    182. 

  182. <td>Retrieve the port of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    183. 

  183. </tr>
    184. 

  184. <tr><td><tt class="docutils literal"><span class="pre">path(u);</span></tt></td>
    185. 

  185. <td>Convertible to S</td>
    186. 

  186. <td>Retrieve the path of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    187. 

  187. </tr>
    188. 

  188. <tr><td><tt class="docutils literal"><span class="pre">query(u);</span></tt></td>
    189. 

  189. <td>Convertible to S</td>
    190. 

  190. <td>Retrieve the query string of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    191. 

  191. </tr>
    192. 

  192. <tr><td><tt class="docutils literal"><span class="pre">fragment(u);</span></tt></td>
    193. 

  193. <td>Convertible to S</td>
    194. 

  194. <td>Retrieve the fragment of <tt class="docutils literal"><span class="pre">u</span></tt>.</td>
    195. 

  195. </tr>
    196. 

  196. </tbody>
    197. 

  197. </table>
    198. 

  198. </div>
    199. 

  199. </div>
    200. 

  200. 

  201. 

  202.           </div>
    203. 

  203.         </div>
    204. 

  204.       </div>
    205. 

  205.       
    206. 

  206.         
    207. 

  207.           <div class="yui-b" id="sidebar">
    208. 

  208.             
    209. 

  209.       <div class="sphinxsidebar">
    210. 

  210.         <div class="sphinxsidebarwrapper">
    211. 

  211.   <h3><a href="index.html">Table Of Contents</a></h3>
    212. 

  212.   <ul>
    213. 

  213. <li><a class="reference internal" href="#">The URI template</a><ul>
    214. 

  214. <li><a class="reference internal" href="#generic-uri-syntax-overview">Generic URI Syntax Overview</a></li>
    215. 

  215. <li><a class="reference internal" href="#basic-uri"><tt class="docutils literal"><span class="pre">basic_uri</span></tt></a></li>
    216. 

  216. <li><a class="reference internal" href="#uri-concept"><tt class="docutils literal"><span class="pre">URI</span> <span class="pre">Concept</span></tt></a></li>
    217. 

  217. </ul>
    218. 

  218. </li>
    219. 

  219. </ul>
    220. 

  220. 

  221.   <h3>Browse</h3>
    222. 

  222.   <ul>
    223. 

  223.     
    224. 

  224.       <li>Prev: <a href="message.html">The message template</a></li>
    225. 

  225.     
    226. 

  226.     
    227. 

  227.       <li>Next: <a href="http.html">HTTP implementation</a></li>
    228. 

  228.     
    229. 

  229.   </ul>
    230. 

  230.   <h3>You are here:</h3>
    231. 

  231.   <ul>
    232. 

  232.       <li>
    233. 

  233.         <a href="index.html">cpp-netlib v0.8 documentation</a>
    234. 

  234.         
    235. 

  235.           <ul><li><a href="in_depth.html">An in-depth look at the <tt class="docutils literal docutils literal docutils literal docutils literal docutils literal"><span class="pre">cpp-netlib</span></tt></a>
    236. 

  236.         
    237. 

  237.         <ul><li>The URI template</li></ul>
    238. 

  238.         </li></ul>
    239. 

  239.       </li>
    240. 

  240.   </ul>
    241. 

  241. 

  242.   <h3>This Page</h3>
    243. 

  243.   <ul class="this-page-menu">
    244. 

  244.     <li><a href="_sources/uri.txt"
    245. 

  245.            rel="nofollow">Show Source</a></li>
    246. 

  246.   </ul>
    247. 

  247. <div id="searchbox" style="display: none">
    248. 

  248.   <h3>Quick search</h3>
    249. 

  249.     <form class="search" action="search.html" method="get">
    250. 

  250.       <input type="text" name="q" size="18" />
    251. 

  251.       <input type="submit" value="Go" />
    252. 

  252.       <input type="hidden" name="check_keywords" value="yes" />
    253. 

  253.       <input type="hidden" name="area" value="default" />
    254. 

  254.     </form>
    255. 

  255.     <p class="searchtip" style="font-size: 90%">
    256. 

  256.     Enter search terms or a module, class or function name.
    257. 

  257.     </p>
    258. 

  258. </div>
    259. 

  259. <script type="text/javascript">$('#searchbox').show(0);</script>
    260. 

  260.         </div>
    261. 

  261.       </div>
    262. 

  262.           </div>
    263. 

  263.         
    264. 

  264.       
    265. 

  265.     </div>
    266. 

  266. 

  267.     <div id="ft">
    268. 

  268.       <div class="nav">
    269. 

  269.     &laquo; <a href="message.html" title="The message template">previous</a>
    270. 

  270.      |
    271. 

  271.     <a href="in_depth.html" title="An in-depth look at the &lt;tt class=&#34;docutils literal docutils literal docutils literal docutils literal docutils literal&#34;&gt;&lt;span class=&#34;pre&#34;&gt;cpp-netlib&lt;/span&gt;&lt;/tt&gt;" accesskey="U">up</a>
    272. 

  272.    |
    273. 

  273.     <a href="http.html" title="HTTP implementation">next</a> &raquo;</div>
    274. 

  274.     </div>
    275. 

  275.   </div>
    276. 

  276. 

  277.       <div class="clearer"></div>
    278. 

  278.     </div>
    279. 

  279.   <div class="footer">
    280. 

  280.       documentation automatically generated by <a href="http://sphinx.pocoo.org">Sphinx</a> | style mostly stolen from <a href="http://lettuce.it">lettuce.it</a>
    281. 

  281.   </div>
    282. 

  282. 

  283.   </body>
    284. 

  284. </html>
    285.