PageRenderTime 73ms CodeModel.GetById 20ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/index.html

https://github.com/xach/zcdb
HTML | 245 lines | 190 code | 55 blank | 0 comment | 0 complexity | 29301dc92b02f7b7ffe775d6f186239b MD5 | raw file
    

  1. <html>
    2. 

  2.   <head>
    3. 

  3.     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    4. 

  4.     <link rel='stylesheet' type='text/css' href='style.css'>
    5. 

  5.     <title>ZCDB - Read and write cdb files from Common Lisp</title>
    6. 

  6.     </head>
    7. 

  7.   <body>
    8. 

  8. 

  9. <div id='content'>
    10. 

  10.  <h2>ZCDB - Read and write cdb files from Common Lisp</h2>
    11. 

  11. 

  12.  <p>ZCDB is a Common Lisp library for reading and writing
    13. 

  13.  D. J. Bernstein's fast and simple
    14. 

  14.    <a href="http://cr.yp.to/cdb.html">cdb database file format</a>. It
    15. 

  15.    is available under a BSD-style <a href='#license'>license</a>. 
    16. 

  16. 

  17. The latest version is 1.0.4, released on March 12th, 2015.
    18. 

  18. 

  19.  <p>Download shortcut: <a href='http://www.xach.com/lisp/zcdb.tgz'>http://www.xach.com/lisp/zcdb.tgz</a>
    20. 

  20. 

  21.  <h2>Contents</h2>
    22. 

  22. 

  23.  <ul>
    24. 

  24.    <li> <a href='#overview'>Overview</a>
    25. 

  25.    <li> <a href='#example'>Example Use</a>
    26. 

  26.    <li> <a href='#limitations'>Limitations</a>
    27. 

  27.    <li> <a href='#dictionary'>The ZCDB Dictionary</a>
    28. 

  28.      <ul>
    29. 

  29.        <li> <a href='#with-output-to-cdb'><code>with-output-to-cdb</code></a>
    30. 

  30.        <li> <a href='#add-record'><code>add-record</code></a>
    31. 

  31.        <li> <a href='#lookup'><code>lookup</code></a>
    32. 

  32.        <li> <a href='#map-cdb'><code>map-cdb</code></a>
    33. 

  33.      </ul>
    34. 

  34.    <li> <a href='#feedback'>Feedback</a>
    35. 

  35.  </ul>
    36. 

  36. 

  37.  <a name='overview'><h2>Overview</h2></a>
    38. 

  38. 

  39.  <p>ZCDB is for reading and writing from CDB files. CDB files are
    40. 

  40.  described in more detail on
    41. 

  41.  D.J. Bernstein's <a href="http://cr.yp.to/cdb.html">CDB information
    42. 

  42.  page</a>. The CDB file format makes it easy to quickly retrieve
    43. 

  43.  data associated with an arbitrary binary key.
    44. 

  44. 

  45.  <p>Once written, CDB files cannot be updated with new records. In
    46. 

  46.  ZCDB, a CDB file is written out
    47. 

  47.  with <a href='#with-output-to-cdb'><tt>WITH-OUTPUT-TO-CDB</tt></a>
    48. 

  48.  and <a href='#add-record'><tt>ADD-RECORD</tt></a>, then read
    49. 

  49.  with <a href='#lookup'><tt>LOOKUP</tt></a>.
    50. 

  50. 

  51.  <a name='example'><h2>Example Use</h2></a>
    52. 

  52. 

  53. <p>Here is a simple way to convert a Unix system password file to a
    54. 

  54.   CDB file:
    55. 

  55. 

  56. <pre class='code'>
    57. 

  57. (defpackage #:pwdb
    58. 

  58.   (:use #:cl #:zcdb))
    59. 

  59. 

  60. (defun username (password-line)
    61. 

  61.   (let ((end (position #\: password-line)))
    62. 

  62.     (subseq password-line 0 end)))
    63. 

  63. 

  64. (defun string-octets (string)
    65. 

  65.   (babel:string-to-octets string :encoding :utf-8))
    66. 

  66. 

  67. (defun octets-string (octets)
    68. 

  68.   (babel:octets-to-string octets :encoding :utf-8))
    69. 

  69. 

  70. (defun make-password-cdb (password-file cdb-file temp-file)
    71. 

  71.   (with-open-file (stream password-file)
    72. 

  72.     (<a href='#with-output-to-cdb'>with-output-to-cdb</a> (cdb cdb-file temp-file)
    73. 

  73.       (loop for line = (read-line stream nil)
    74. 

  74.             while line do
    75. 

  75.             (let ((username (username line)))
    76. 

  76.               (<a href='#add-record'>add-record</a> (string-octets username)
    77. 

  77.                           (string-octets line)
    78. 

  78.                           cdb))))))
    79. 

  79. 

  80. (defun user-info (username cdb-file)
    81. 

  81.   (let ((entry (<a href='#lookup'>lookup</a> (string-octets username) cdb-file)))
    82. 

  82.     (when entry
    83. 

  83.       (octets-string entry))))
    84. 

  84. </pre>
    85. 

  85. 

  86. <p>Then the database can be created and queried:
    87. 

  87. 

  88. <pre class='code'>
    89. 

  89. * <b>(make-password-cdb "/etc/passwd" "/tmp/pwdb.cdb" "/tmp/pwdb.cdb.tmp")</b>
    90. 

  90. #P"/tmp/pwdb.cdb"
    91. 

  91. 

  92. * <b>(user-info "root" "/tmp/pwdb.cdb")</b>
    93. 

  93. "root:*:0:0:System Administrator:/var/root:/bin/sh"
    94. 

  94. </pre>
    95. 

  95. 

  96. 

  97.  <a name='limitations'><h2>Limitations</h2></a>
    98. 

  98. 

  99.  <p>The CDB file format offers many opportunities for low-level
    100. 

  100.  interaction, including writing and reading records that don't fit in
    101. 

  101.  memory by writing or reading them incrementally. ZCDB currently only
    102. 

  102.  offers a simplified interface that works with keys and values that
    103. 

  103.  are fully loaded in memory as <tt>(unsigned-byte&nbsp;8)</tt>
    104. 

  104.  vectors.
    105. 

  105. 

  106.  <p>ZCDB does not provide any functions for serializing various data
    107. 

  107.  types (such as strings) to vectors. There are many other third-party
    108. 

  108.  libraries for that purpose.
    109. 

  109. 

  110.  <a name='dictionary'><h2>The ZCDB Dictionary</h2></a>
    111. 

  111. 

  112.  <p>ZCDB exports the following symbols.
    113. 

  113. 

  114.  <div class='item'>
    115. 

  115.    <div class='type'><a name='with-output-to-cdb'>[Macro]</a></div>
    116. 

  116.    <div class='signature'>
    117. 

  117.      <code class='name'>with-output-to-cdb</code>
    118. 

  118.      <span class='args'>(<var>cdb</var> <var>cdb-pathname</var> 
    119. 

  119.        <var>temporary-pathname</var>) 
    120. 

  120.        <code class='llkw'>&amp;body</code> <var>body</var>
    121. 

  121.      </span>
    122. 

  122.      <span class='result'>=> |</span>
    123. 

  123.    </div>
    124. 

  124. 

  125.    <blockquote class='description'>
    126. 

  126.      <p>Evaluates <var>body</var> with <var>cdb</var> bound to a cdb
    127. 

  127.      writer object. <var>cdb</var> may be used as the target
    128. 

  128.      of <a href='#add-record'><tt>ADD-RECORD</tt></a> operations.
    129. 

  129. 

  130.        
    131. 

  131.      <p>The cdb in progress is written
    132. 

  132.      to <var>temporary-pathname</var>. Any existing file with that
    133. 

  133.      pathname is overwritten. When writing completes
    134. 

  134.      successfully, <var>temporary-pathname</var> is renamed
    135. 

  135.      to <var>cdb-pathname</var>
    136. 

  136.      with <a href='http://l1sp.org/cl/rename-file'><tt>CL:RENAME-FILE</tt></a>. For
    137. 

  137.      atomic operation, both files should be on the same filesystem.
    138. 

  138.    </blockquote>
    139. 

  139. 

  140. 

  141.    <div class='item'>
    142. 

  142.      <div class='type'><a name='add-record'>[Function]</a></div>
    143. 

  143.      <div class='signature'>
    144. 

  144.        <code class='name'>add-record</code>
    145. 

  145.        <span class='args'>
    146. 

  146. 	 <var>key</var> <var>value</var> <var>cdb</var>
    147. 

  147.        </span>
    148. 

  148.        <span class='result'>=> |</span>
    149. 

  149.      </div>
    150. 

  150. 

  151.      <blockquote class='description'>
    152. 

  152.        <p>Adds a record for <var>key</var> and <var>value</var>
    153. 

  153. 	 to <var>cdb</var>, which should be a cdb writer object created in
    154. 

  154. 	 the dynamic scope
    155. 

  155. 	 of <a href='#with-output-to-cdb'><tt>WITH-OUTPUT-TO-CDB</tt></a>.
    156. 

  156. 

  157.        <p><var>key</var> and <var>value</var> must both be vectors
    158. 

  158. 	 specialized to hold
    159. 

  159. 	 <tt>(unsigned-byte 8)</tt> data.
    160. 

  160.      </blockquote>
    161. 

  161.    </div>
    162. 

  162. 

  163.    <div class='item'>
    164. 

  164.      <div class='type'><a name='lookup'>[Function]</a></div>
    165. 

  165.      <div class='signature'>
    166. 

  166.        <code class='name'>lookup</code>
    167. 

  167.        <span class='args'>
    168. 

  168. 	 <var>key</var> <var>cdb</var>
    169. 

  169.        </span>
    170. 

  170.        <span class='result'>=> value</span>
    171. 

  171.      </div>
    172. 

  172. 

  173.      <blockquote class='description'>
    174. 

  174.        <p>Looks up <var>key</var> in <var>cdb</var> and returns its
    175. 

  175. 	 value, or nil if no record in <var>cdb</var> has the given key.
    176. 

  176. 

  177.        <p><var>key</var> must be a specialized <tt>(unsigned-byte&nbsp;8)</tt>
    178. 

  178. 	 vector. If the value is not null, it will also be a
    179. 

  179. 	 specialized <tt>(unsigned-byte&nbsp;8)</tt> vector.
    180. 

  180. 

  181.        <p><var>cdb</var> must be either a pathname, or an input stream
    182. 

  182.        of element-type <tt>(unsigned-byte&nbsp;8)</tt> that can be
    183. 

  183.        repositioned
    184. 

  184.        with <a href='http://l1sp.org/cl/file-position'><tt>CL:FILE-POSITION</tt></a>.
    185. 

  185.      </blockquote>
    186. 

  186.    </div>
    187. 

  187. 

  188.    <div class='item'>
    189. 

  189.      <div class='type'><a name='map-cdb'>[Function]</a></div>
    190. 

  190.      <div class='signature'>
    191. 

  191.        <code class='name'>map-cdb</code>
    192. 

  192.        <span class='args'>
    193. 

  193. 	 <var>function</var> <var>cdb</var>
    194. 

  194.        </span>
    195. 

  195.        <span class='result'>=> |</span>
    196. 

  196.      </div>
    197. 

  197. 

  198.      <blockquote class='description'>
    199. 

  199.        <p>For each record in <var>cdb</var>, <var>function</var> is called with
    200. 

  200.        two arguments, the key vector and the value vector,
    201. 

  201.        respectively.
    202. 

  202. 

  203.        <p><var>cdb</var> must be either a pathname, or an input stream
    204. 

  204.        of element-type <tt>(unsigned-byte&nbsp;8)</tt> that can be
    205. 

  205.        repositioned
    206. 

  206.        with <a href='http://l1sp.org/cl/file-position'><tt>CL:FILE-POSITION</tt></a>.
    207. 

  207.      </blockquote>
    208. 

  208.    </div>
    209. 

  209. 

  210. 

  211. <a name='feedback'><h2>Feedback</h2></a>
    212. 

  212. 

  213.   <p>If you have any questions or comments about ZCDB, please email
    214. 

  214.   me, <a href='mailto:xach@xach.com'>Zach Beane</a>.
    215. 

  215. 

  216. <a name='license'><h2>License</h2></a>
    217. 

  217. 

  218. <p>Copyright &copy; 2010 Zachary Beane
    219. 

  219. 

  220. <p>Permission is hereby granted, free of charge, to any person obtaining a copy
    221. 

  221. of this software and associated documentation files (the "Software"), to deal
    222. 

  222. in the Software without restriction, including without limitation the rights
    223. 

  223. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    224. 

  224. copies of the Software, and to permit persons to whom the Software is
    225. 

  225. furnished to do so, subject to the following conditions:
    226. 

  226. 

  227. <p>The above copyright notice and this permission notice shall be included in
    228. 

  228. all copies or substantial portions of the Software.
    229. 

  229. 

  230. <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    231. 

  231. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    232. 

  232. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    233. 

  233. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    234. 

  234. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    235. 

  235. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    236. 

  236. THE SOFTWARE.
    237. 

  237. 

  238.   <p><i>2010-09-21</i>
    239. 

  239.   
    240. 

  240.  <p class='copyright'>Copyright &copy; 2010 Zachary Beane, All Rights Reserved
    241. 

  241. 

  242.  </div>
    243. 

  243.  
    244. 

  244. 

  245.  
    246. 

  246.