extra/checksums/process/process-docs.factor

   1 ! Copyright (C) 2016 Alexander Ilin.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: ascii checksums checksums.common destructors help.markup
   4 help.syntax ;
   5 IN: checksums.process
   6
   7 ABOUT: "checksums.process"
   8
   9 ARTICLE: "checksums.process" "Checksumming with External Utilities"
  10 "With the " { $vocab-link "checksums.process" } " vocabulary any console utility can be used to checksum data, provided it supports a certain interface: it should accept input data on STDIN and output result to STDOUT. The output should consist of the hexadecimal checksum string, terminated with a " { $link blank? } " character. For instance, all the checksums from the GNU CoreUtils package support this mode of operation as the default."
  11 $nl
  12 "The " { $link checksum-process } " tuple holds a launch descriptor (see " { $link "io.launcher.descriptors" } ") of the utility, e.g. \"sha1sum\". When the " { $link initialize-checksum-state } " method is called on it, a new instance of the checksum utility is started in the background. In Factor it is represented by the " { $link process-state } " tuple. You can then use " { $link add-checksum-bytes } " to stream data to it. When done, call " { $link get-checksum } " to read the resulting checksum and dispose of the tuple in one step. If you want to cancel the work without calling " { $link get-checksum } ", you must " { $link dispose } " of the tuple so that the underlying process is terminated."
  13 $nl
  14 "The " { $link checksum-bytes } " and the " { $link checksum-stream } " methods encapsulate the above protocol, including instantiation and disposal of the " { $link process-state } " tuple."
  15 { $examples
  16     { $unchecked-example "USING: byte-arrays checksums checksums.process ;"
  17     "\"test\" >byte-array \"sha1sum\" <checksum-process> checksum-bytes ."
  18     "B{
  19     169 74 143 229 204 177 155 166 28 76 8 115 211 145 233 135
  20     152 47 187 211
  21 }" }
  22     $nl
  23     { $unchecked-example "USING: checksums checksums.common checksums.process"
  24     "io io.encodings.binary namespaces ;"
  25     "\"LICENSE.txt\" binary ["
  26     "    input-stream get \"sha1sum\" <checksum-process> checksum-stream"
  27     "] with-file-reader ."
  28     "B{
  29     125 80 102 9 175 178 81 111 33 59 33 149 187 70 193 32 81
  30     188 89 156
  31 }" }
  32 } ;
  33
  34 HELP: <checksum-process>
  35 { $values
  36     { "launch-desc" "see " { $link "io.launcher.descriptors" } }
  37     { "checksum-process" "a new instance of " { $link checksum-process } }
  38 }
  39 { $description "This is a simple constructor for the " { $link checksum-process } " tuple." } ;
  40
  41 HELP: checksum-process
  42 { $class-description "This is an instance of the " { $link block-checksum } " mixin. It calculates checksums by running a console utility as described in the " { $slot "launch-desc" } " slot, piping data to it and receiving the output at the end. Each call to " { $link initialize-checksum-state } " starts a new external process, which is represented by a " { $link process-state } " instance. The latter also holds the resulting checksum." } ;
  43
  44 HELP: process-state
  45 { $class-description "This class represents the current state of a " { $link checksum-process } " checksum calculation. It has an associated external console application running until it is disposed. You may call " { $link add-checksum-bytes } " multiple times to pipe data to the external utility. When finished, call " { $link get-checksum } " to receive the result and terminate the process, or " { $link dispose } " to discard the result and terminate the process. After the first " { $link get-checksum } " call the returned value is stored in the " { $slot "result" } " slot, and subsequent calls return the same value." }
  46 { $notes "It is not possible to add more data to the checksum after the first get-checksum call."
  47 $nl
  48 "Most code should use " { $link with-checksum-state } " to make sure the external process is disposed of. Higher level words like " { $link checksum-bytes } " and " { $link checksum-stream } " use it to perform the disposal." } ;
  49
  50 HELP: trim-hash
  51 { $values
  52     { "str" "a string returned by a console hashing utility" }
  53     { "str'" "extracted hash string" }
  54 }
  55 { $description "This is a helper word for " { $link process-state } "'s " { $link get-checksum } " implementation. It looks for the hash terminator string \" *-\" and returns everything before it." } ;