core/checksums/checksums-docs.factor

   1 USING: byte-arrays help.markup help.syntax sequences strings ;
   2 IN: checksums
   3
   4 HELP: checksum
   5 { $class-description "The class of checksum algorithms." } ;
   6
   7 HELP: hex-string
   8 { $values { "seq" sequence } { "str" string } }
   9 { $description "Converts a sequence of values from 0-255 to a string of hex numbers from 0-ff." }
  10 { $examples
  11     { $example "USING: checksums io ;" "B{ 1 2 3 4 } hex-string print" "01020304" }
  12 }
  13 { $notes "Numbers are zero-padded on the left." } ;
  14
  15 HELP: checksum-stream
  16 { $values { "stream" "an input stream" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  17 { $contract "Computes the checksum of all data read from the stream." }
  18 { $side-effects "stream" } ;
  19
  20 HELP: checksum-bytes
  21 { $values { "bytes" "a sequence of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  22 { $contract "Computes the checksum of all data in a sequence." }
  23 { $examples
  24     { $example
  25         "USING: checksums checksums.crc32 prettyprint ;"
  26         "B{ 1 10 100 } crc32 checksum-bytes ."
  27         "B{ 78 179 254 238 }"
  28     }
  29 } ;
  30
  31 HELP: checksum-lines
  32 { $values { "lines" "a sequence of sequences of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  33 { $contract "Computes the checksum of all data in a sequence." }
  34 { $examples
  35     { $example
  36         "USING: checksums checksums.crc32 prettyprint ;"
  37 """{
  38     "Take me out to the ball game"
  39     "Take me out with the crowd"
  40 } crc32 checksum-lines ."""
  41         "B{ 111 205 9 27 }"
  42     }
  43 } ;
  44
  45 HELP: checksum-file
  46 { $values { "path" "a pathname specifier" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  47 { $contract "Computes the checksum of all data in a file." }
  48 { $examples
  49     { $example
  50         "USING: checksums checksums.crc32 prettyprint ;"
  51         """"resource:license.txt" crc32 checksum-file ."""
  52         "B{ 100 139 199 92 }"
  53     }
  54 } ;
  55
  56 ARTICLE: "checksums" "Checksums"
  57 "A " { $emphasis "checksum" } " is a function mapping sequences of bytes to fixed-length strings. While checksums are not one-to-one, a good checksum should have a low probability of collision. Additionally, some checksum algorithms are designed to be hard to reverse, in the sense that finding an input string which hashes to a given checksum string requires a brute-force search."
  58 $nl
  59 "Checksums are instances of a class:"
  60 { $subsections checksum }
  61 "Operations on checksums:"
  62 { $subsections
  63     checksum-bytes
  64     checksum-stream
  65     checksum-lines
  66 }
  67 "Checksums should implement at least one of " { $link checksum-bytes } " and " { $link checksum-stream } ". Implementing " { $link checksum-lines } " is optional."
  68 $nl
  69 "Utilities:"
  70 { $subsections
  71     checksum-file
  72     hex-string
  73 }
  74 "Checksum implementations:"
  75 { $subsections "checksums.crc32" }
  76 { $vocab-subsection "MD5 checksum" "checksums.md5" }
  77 { $vocab-subsection "SHA checksums" "checksums.sha" }
  78 { $vocab-subsection "Adler-32 checksum" "checksums.adler-32" }
  79 { $vocab-subsection "OpenSSL checksums" "checksums.openssl" }
  80 { $vocab-subsection "Internet checksum" "checksums.internet" } ;
  81
  82 ABOUT: "checksums"