core/checksums/checksums-docs.factor

   1 USING: byte-arrays help.markup help.syntax ;
   2 IN: checksums
   3
   4 HELP: checksum
   5 { $class-description "The class of checksum algorithms." } ;
   6
   7 HELP: checksum-stream
   8 { $values { "stream" "an input stream" } { "checksum" "a checksum specifier" } { "value" byte-array } }
   9 { $contract "Computes the checksum of all data read from the stream." }
  10 { $side-effects "stream" } ;
  11
  12 HELP: checksum-bytes
  13 { $values { "bytes" "a sequence of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  14 { $contract "Computes the checksum of all data in a sequence." }
  15 { $examples
  16     { $example
  17         "USING: checksums checksums.crc32 prettyprint ;"
  18         "B{ 1 10 100 } crc32 checksum-bytes ."
  19         "B{ 78 179 254 238 }"
  20     }
  21 } ;
  22
  23 HELP: checksum-lines
  24 { $values { "lines" "a sequence of sequences of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  25 { $contract "Computes the checksum of all data in a sequence." }
  26 { $examples
  27     { $example
  28         "USING: checksums checksums.crc32 prettyprint ;"
  29 "{
  30     \"Take me out to the ball game\"
  31     \"Take me out with the crowd\"
  32 } crc32 checksum-lines ."
  33         "B{ 111 205 9 27 }"
  34     }
  35 } ;
  36
  37 HELP: checksum-file
  38 { $values { "path" "a pathname specifier" } { "checksum" "a checksum specifier" } { "value" byte-array } }
  39 { $description "Computes the checksum of all data in a file." }
  40 { $examples
  41     { $unchecked-example
  42         ! This example fails on Windows if you ``git clone`` with Windows line-endings
  43         ! Issue #2276
  44         "USING: checksums checksums.crc32 prettyprint ;"
  45         "\"resource:core/checksums/crc32/crc-me.txt\" crc32 checksum-file ."
  46         "B{ 196 202 117 155 }"
  47     }
  48 } ;
  49
  50 ARTICLE: "checksums" "Checksums"
  51 "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."
  52 $nl
  53 "Checksums are instances of a class:"
  54 { $subsections checksum }
  55 "Operations on checksums:"
  56 { $subsections
  57     checksum-bytes
  58     checksum-stream
  59     checksum-lines
  60     checksum-file
  61 }
  62 "Checksums should implement at least one of " { $link checksum-bytes } " and " { $link checksum-stream } ". Implementing " { $link checksum-lines } " is optional."
  63 $nl
  64 "Checksums can also implement a stateful checksum protocol that allows users to push bytes when needed and then at a later point request the checksum value. The default implementation is not very efficient, storing all of the bytes and then calling " { $link checksum-bytes } " when " { $link get-checksum } " is requested."
  65 $nl
  66 { $subsections
  67     initialize-checksum-state
  68     add-checksum-bytes
  69     add-checksum-stream
  70     add-checksum-lines
  71     add-checksum-file
  72     get-checksum
  73 }
  74 "Checksum implementations:"
  75 { $vocab-subsections
  76     { "CRC32 checksum" "checksums.crc32" }
  77     { "MD5 checksum" "checksums.md5" }
  78     { "SHA checksums" "checksums.sha" }
  79     { "Adler-32 checksum" "checksums.adler-32" }
  80     { "OpenSSL checksums" "checksums.openssl" }
  81     { "Internet checksum" "checksums.internet" }
  82     { "Checksum using an external utility" "checksums.process" }
  83 } ;
  84
  85 ABOUT: "checksums"