Changeset 35347 in project


Ignore:
Timestamp:
03/26/18 07:18:17 (5 weeks ago)
Author:
kon
Message:

better (?), easier to read (?), doc

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/message-digest

    r35046 r35347  
    1313
    1414For best results the source object(s) to be accumulated into the digest should be
    15 something easily treated as a {{byteblock}} or, even better, a {{bytevector}}.
    16 
    17 This extension is split into many modules. The extension module ''message-digest''
    18 exports every other modules except ''message-digest-port''.
     15something easily treated as a {}{bytevector}}.
    1916
    2017
    2118=== Message Digest Primitive
    2219
     20Essentially the reification of a message digest algorithm.
     21
    2322==== Usage
    2423
     
    3332==== message-digest-primitive?
    3433
    35 <procedure>(message-digest-primitive? OBJ) => boolean</procedure>
     34<procedure>(message-digest-primitive? OBJ) -> boolean</procedure>
    3635<procedure>(check-message-digest-primitive LOC OBJ [NAM])</procedure>
    3736<procedure>(error-message-digest-primitive LOC OBJ [NAM])</procedure>
     
    3938==== message-digest-primitive Accessors
    4039
    41 <procedure>(message-digest-primitive-context-info PRIM) => *</procedure>
    42 <procedure>(message-digest-primitive-digest-length PRIM) => fixnum</procedure>
    43 <procedure>(message-digest-primitive-init PRIM) => procedure</procedure>
    44 <procedure>(message-digest-primitive-update PRIM) => procedure</procedure>
    45 <procedure>(message-digest-primitive-raw-update PRIM) => (or #f procedure)</procedure>
    46 <procedure>(message-digest-primitive-final PRIM) => procedure</procedure>
    47 <procedure>(message-digest-primitive-block-length PRIM) => fixnum</procedure>
    48 <procedure>(message-digest-primitive-name PRIM) => symbol</procedure>
     40<procedure>(message-digest-primitive-context-info PRIM) -> *</procedure>
     41<procedure>(message-digest-primitive-digest-length PRIM) -> fixnum</procedure>
     42<procedure>(message-digest-primitive-init PRIM) -> procedure</procedure>
     43<procedure>(message-digest-primitive-update PRIM) -> procedure</procedure>
     44<procedure>(message-digest-primitive-raw-update PRIM) -> (or #f procedure)</procedure>
     45<procedure>(message-digest-primitive-final PRIM) -> procedure</procedure>
     46<procedure>(message-digest-primitive-block-length PRIM) -> fixnum</procedure>
     47<procedure>(message-digest-primitive-name PRIM) -> symbol</procedure>
    4948
    5049==== make-message-digest-primitive
    5150
    52 <procedure>(make-message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [BLOCK-LENGTH [NAME [RAW-UPDATE]]]) => message-digest-primitive</procedure>
    53 
    54 Create a {{message-digest-primitive}} object. The reification of a message
    55 digest algorithm.
    56 
    57 {{CONTEXT-INFO}} is either a {{(procedure () <context>)}}, or a
    58 {{positive-integer}}. When an {{integer}} a memory-block of length
    59 {{CONTEXT-INFO}} is allocated (and automatically free'ed).
    60 
    61 {{<context>}} is an opaque object, except when the {{CONTEXT-INFO}} is an
    62 {{integer}}. In which case it is known that the object is a {{pointer}} to a
    63 block of uninitialized memory.
    64 
    65 The {{<context>}} should be a unique object. At least the object cannot be
    66 shared with another ''activated'' primitive.
    67 
    68 {{DIGEST-LENGTH}} is the count of bytes in the result.
     51<procedure>(make-message-digest-primitive CONTEXT-INFO DIGEST-SIZE INIT! UPDATE! FINAL! [BLOCK-LENGTH] [NAME] [RAW-UPDATE!]) -> message-digest-primitive</procedure>
     52
     53Create a {{message-digest-primitive}} object, defining a message digest
     54algorithm.
    6955
    7056The processing of a message digest is split into three phases: initialization,
    71 update & finalization. These are represented by three procedures: {{INIT}},
    72 {{UPDATE}}/{{RAW-UPDATE}} & {{FINAL}}, respectively.
    73 
    74 {{INIT}} is a {{(procedure (<CONTEXT>))}}. Sets up the {{<CONTEXT>}}.
    75 (Technically the creation of a new {{<CONTEXT>}} is part of the initialization
    76 phase but this detail is hidden from the user.)
    77 
    78 {{<SOURCE>}} is <BLOB>|<STRING>.
    79 
    80 {{UPDATE}} is a {{(procedure (<CONTEXT> <SOURCE> <COUNT>))}}. Must
    81 accumulate the {{<SOURCE>}}, beginning at {{0}}, for {{<COUNT>}} bytes.
    82 Will be called zero or more times.
    83 
    84 The foreign type specifier {{scheme-pointer}} is suitable as a foreign-lambda
    85 argument type for the {{<SOURCE>}} argument since the data-region is a
    86 contiguous array of bytes.
    87 
    88 {{<COUNT>}} is the actual number of bytes in the {{<SOURCE>}}. Since this
    89 value is supplied it means only the first {{<COUNT>}} bytes in the
    90 {{<SOURCE>}} are valid.
    91 
    92 {{<DESTINATION>}} is <BLOB>|<STRING>.
    93 
    94 {{FINAL}} is a {{(procedure (<CONTEXT> <source>))}}. Must build the
    95 message-digest result in the supplied result {{<DESTINATION>}}, which will
    96 have a length/size of at least {{DIGEST-LENGTH}}.
    97 
    98 ('''Note''' that {{INIT}}, {{UPDATE}}/{{RAW-UPDATE}} & {{FINAL}} are
    99 side-effecting procedures!)
    100 
    101 {{BLOCK-LENGTH}} must be a positive {{fixnum}} and identifies the message
    102 digest algorithm accumulator length in bytes. The default is {{4}}.
    103 
    104 {{NAME}} must be a {{symbol}} or a {{string}} and identifies the message
    105 digest algorithm. The suggested form is {{<algorithm name>-primitive}}.
    106 Example: {{'md5-primitive}}. The default is a nearly useless generated,
    107 uninterned {{symbol}}.
    108 
    109 {{RAW-UPDATE}} is a {{(procedure (<CONTEXT> <POINTER> <COUNT>))}}.
    110 Must accumulate the memory at {{<POINTER>}}, beginning at {{0}}, for
    111 {{<COUNT>}} bytes. Will be called zero or more times.
     57update, & finalization. These are represented by procedures: {{INIT!}},
     58{{UPDATE!}}/{{RAW-UPDATE!}}, & {{FINAL!}}, respectively.
     59
     60; {{CONTEXT-INFO}} : {{(or (CONTEXT-INFO -> context-object) positive-fixnum)}}
     61
     62* {{(CONTEXT-INFO -> CONTEXT)}} ; returns the {{context-object}}, which should
     63be unique. At least the object cannot be shared with another ''activated''
     64primitive.
     65
     66* {{positive-fixnum}} : a memory-block of length {{CONTEXT-INFO}} bytes is
     67allocated; the memory is automatically free'ed. The {{context-object}} here is
     68a {pointer}} to a block of uninitialized memory.
     69
     70; {{DIGEST-SIZE}} : {{positive-fixnum}}
     71
     72* The count of bytes in the result.
     73
     74; {{BLOCK-LENGTH}} : {{positive-fixnum}} ; default {{4}}
     75
     76* The primitive's accumulator length in bytes.
     77
     78; {{NAME}} : {{(or symbol string)}} ; default {{uninterned-symbol}}.
     79
     80* Identifies the message digest algorithm. The suggested form is
     81{{<algorithm>-primitive}}, {{'md5-primitive}} for example.
     82
     83; {{INIT!}} : {{(CONTEXT -> void))}} ; sets up the {{CONTEXT}}.
     84
     85; {{UPDATE!}} : {{(CONTEXT SOURCE COUNT -> void))}}.
     86
     87* Must accumulate the {{SOURCE}}, beginning at {{0}}, for {{COUNT}} bytes.
     88Will be called zero or more times. {{SOURCE}} is usually an {{(or blob
     89string)}} object.
     90
     91* {{COUNT}} is the actual number of bytes in the {{SOURCE}}. Only the first
     92{{COUNT}} bytes in the {{SOURCE}} are valid. {{COUNT}} is a
     93{{positive-fixnum}}.
     94
     95; {{RAW-UPDATE!}} : {{(CONTEXT POINTER COUNT -> void))}}.
     96
     97* Must accumulate the memory at {{POINTER}}, beginning at {{0}}, for {{COUNT}}
     98bytes. Will be called zero or more times.
     99
     100* {{COUNT}} is the actual number of bytes in the {{SOURCE}}. Only the first
     101{{COUNT}} bytes in the memory at {{POINTER}} are valid. {{COUNT}} is a
     102{{positive-fixnum}}, limited by {{(message-digest-chunk-size)}}.
     103
     104; {{FINAL!}} : {{(CONTEXT DESTINATION -> void))}}.
     105
     106* Must build the message-digest result in the supplied result {{DESTINATION}},
     107which will have a byte-count of at least {{DIGEST-SIZE}}. {{DESTINATION}} is
     108usually an {{(or blob string)}} object.
    112109
    113110
     
    122119==== Common Argument Definitions
    123120
    124 {{RESULT-FORM}} is one of:
     121{{RESULT-FORM}} is a {{message-digest-result-form}}, one of:
    125122
    126123; {{'byte-string}} {{'string}} : the result bytes as a string; these are raw bytes, not characters!
    127 ; {{'hex-string}} {{'hex}} {{'hexstring}} : the result bytes encoded as a string of lower-case hexadecimal digits.
    128124; {{'blob}} : the result bytes as a blob.
    129125; {{'u8vector}} : the result bytes as a u8vector.
     126; {{'hex-string}} {{'hex}} {{'hexstring}} : the result bytes encoded as a string of lower-case hexadecimal digits.
    130127
    131128{{DIGEST}} is a {{message-digest}}.
     
    135132{{SOURCE}} is a Scheme object.
    136133
    137 The {{<buffer>}} argument for the update phase is translated as:
    138 
    139 ; {{string}} : {{<buffer>}} = {{SOURCE}}.
    140 ; {{blob}} : {{<buffer>}} = {{SOURCE}}.
    141 ; {{srfi-4-vector}} : {{<buffer>}} = {{(...vector->blob/shared SOURCE)}}.
    142 ; {{procedure}} : updates with {{<buffer>}} = {{(procedure)}} until {{#f = (procedure)}}.
     134The {{buffer}} argument for the update phase is translated as:
     135
     136; {{string}} : {{buffer}} is {{SOURCE}}.
     137; {{blob}} : {{buffer}} is {{SOURCE}}.
     138; {{srfi-4-vector}} : {{buffer}} from {{(...vector->blob/shared SOURCE)}}.
     139; {{procedure}} : updates with {{buffer}} from {{(procedure)}} until {{#f}}.
    143140; {{input-port}} : like {{procedure}} above but from {{((message-digest-chunk-read-maker) SOURCE)}}.
    144 ; {{pointer}} : {{<buffer>}} = {{SOURCE}}, thru the digest primitive raw-update.
    145 ; {{*}} : {{<buffer>}} = {{(message-digest-chunk-converter SOURCE)}}.
     141; {{pointer}} : {{buffer}} is {{SOURCE}}, thru the digest primitive ''raw-update'' usually.
     142; {{*}} : {{buffer}} from {{(message-digest-chunk-converter SOURCE)}}.
    146143
    147144Should none of the above interpretations be available then an error is
    148145signaled.
    149146
    150 A {{<byte-source>}} is one of {{string}}, {{blob}}, or {{srfi-4-vector}}.
     147A {{byte-source}} is one of {{string}}, {{blob}}, or {{srfi-4-vector}}.
     148
     149{{message-digest-result-type}} is {{(or blob string u8vector)}}
    151150
    152151==== message-digest-result-form
    153152
    154 <parameter>(message-digest-result-form [RESULT-FORM]) => symbol</parameter>
     153<parameter>(message-digest-result-form [RESULT-FORM]) -> symbol</parameter>
    155154
    156155The initial {{RESULT-FORM}} value is {{'hex-string}}.
     
    160159==== initialize-message-digest
    161160
    162 <procedure>(initialize-message-digest PRIM) => message-digest</procedure>
    163 
    164 Returns a new, initialized {{message-digest}} for the supplied algorithm
     161<procedure>(initialize-message-digest PRIM) -> message-digest</procedure>
     162
     163Returns a new, initialized, {{message-digest}} for the supplied algorithm
    165164{{PRIM}}.
    166165
    167 Initialized here means the intialization phase is completed.
     166''Initialized'' here means the intialization phase is completed.
    168167
    169168==== message-digest?
    170169
    171 <procedure>(message-digest? OBJ) => boolean</procedure>
     170<procedure>(message-digest? OBJ) -> boolean</procedure>
    172171
    173172<procedure>(check-message-digest LOC OBJ [NAM])</procedure>
     
    176175==== message-digest-algorithm
    177176
    178 <procedure>(message-digest-algorithm DIGEST) => message-digest-primitive</procedure>
     177<procedure>(message-digest-algorithm DIGEST) -> message-digest-primitive</procedure>
    179178
    180179Returns the message digest algorithm used by this {{DIGEST}}.
     
    186185==== finalize-message-digest
    187186
    188 <procedure>(finalize-message-digest DIGEST [RESULT-FORM]) => *</procedure>
    189 
    190 Finalize the {{DIGEST}} and return the {{<result>}} in the {{RESULT-FORM}}.
    191 
    192 {{RESULT-FORM}} default is {{(message-digest-result-form)}}.
     187<procedure>(finalize-message-digest DIGEST [RESULT-FORM]) -> message-digest-result-type</procedure>
     188
     189Finalize the {{DIGEST}} and return the {{result}} in the {{RESULT-FORM}}.
     190
     191; {{RESULT-FORM}} : {{message-digest-result-form}} ; default {{(message-digest-result-form)}}.
    193192
    194193Finalize here means the finalization phase is completed. The {{DIGEST}} is not
     
    197196==== finalize-message-digest!
    198197
    199 <procedure>(finalize-message-digest! DIGEST BUFFER) => *</procedure>
    200 
    201 Finalize the {{DIGEST}} and return the {{<result>}} in the {{BUFFER}}.
     198<procedure>(finalize-message-digest! DIGEST BUFFER) -> message-digest-result-type</procedure>
     199
     200Finalize the {{DIGEST}} and return the {{result}} in the {{BUFFER}}.
    202201
    203202The {{BUFFER}} must be a {{string}}, {{blob}}, or {{u8vector}} of sufficient
     
    205204{{BUFFER}}.
    206205
    207 The {{<result>}} starts at the beginning of the {{BUFFER}}, and runs for
     206The {{result}} starts at the beginning of the {{BUFFER}}, and runs for
    208207{{(message-digest-primitive-digest-length (message-digest-algorithm
    209208DIGEST))}} bytes. Result is binary '''only'''.
     
    221220=== Message Digest Chunk
    222221
    223 ''Chunking'' API
     222An inchoate ''Chunking'' API.
    224223
    225224==== Usage
     
    238237==== message-digest-chunk-port-read-maker
    239238
    240 <parameter>(message-digest-chunk-port-read-maker [CONSTRUCTOR]) => procedure</parameter>
     239<parameter>(message-digest-chunk-port-read-maker [CONSTRUCTOR]) -> procedure</parameter>
    241240
    242241Supplies the procedure used to create an input procedure.
    243242
    244 {{CONSTRUCTOR}} is a {{(procedure (INPUT-PORT #!optional SIZE)
    245 (procedure () <byte-source>))}}. The first argument is the chunk source port
    246 and the second argument is the size of chunks.
     243{{CONSTRUCTOR}} is a {{(INPUT-PORT #!optional SIZE) -> (-> byte-source)}}. The
     244first argument is the chunk source port and the second argument is the size of
     245chunks.
    247246
    248247The default {{CONSTRUCTOR}} will return a procedure that reads from
     
    251250==== message-digest-chunk-fileno-read-maker
    252251
    253 <parameter>(message-digest-chunk-fileno-read-maker [CONSTRUCTOR]) => procedure</parameter>
     252<parameter>(message-digest-chunk-fileno-read-maker [CONSTRUCTOR]) -> procedure</parameter>
    254253
    255254Supplies the procedure used to create an input procedure.
    256255
    257 {{CONSTRUCTOR}} is a {{(procedure (FD #!optional SIZE) (procedure ()
    258 <byte-source>))}}. The first argument is the chunk source open fileno and the
    259 second argument is the size of chunks.
     256{{CONSTRUCTOR}} is a {{FD #!optional SIZE) -> (-> byte-source))}}. The first
     257argument is the chunk source open fileno and the second argument is the size
     258of chunks.
    260259
    261260The default {{CONSTRUCTOR}} will return a procedure that reads from {{FD}} in
     
    264263==== message-digest-chunk-size
    265264
    266 <parameter>(message-digest-chunk-size [SIZE]) => positive-integer</parameter>
     265<parameter>(message-digest-chunk-size [SIZE]) -> positive-integer</parameter>
    267266
    268267The number of bytes to read from a binary-stream during the message-digest
     
    273272==== message-digest-chunk-converter
    274273
    275 <parameter>(message-digest-chunk-converter [CONVERTER]) => (or #f procedure)</parameter>
     274<parameter>(message-digest-chunk-converter [CONVERTER]) -> (or #f procedure)</parameter>
    276275
    277276The procedure used to translate an arbitrary object into something
    278277suitable for an {{UPDATE}} procedure. See {{make-message-digest-primitive}}.
    279278
    280 {{CONVERTER}} is a {{(procedure (*) <byte-source>)}} or {{#f}}.
     279{{CONVERTER}} is a {{(* -> byte-source)}} or {{#f}}.
    281280
    282281The default {{CONVERTER}} is {{#f}}.
     
    286285==== message-digest-chunk-read-maker (DEPRECATED)
    287286
    288 <parameter>(message-digest-chunk-read-maker [CONSTRUCTOR]) => procedure</parameter>
     287<parameter>(message-digest-chunk-read-maker [CONSTRUCTOR]) -> procedure</parameter>
    289288
    290289Synonym for {{message-digest-chunk-port-read-maker}}.
     
    315314==== message-digest-string
    316315
    317 <procedure>(message-digest-string PRIM STRING [RESULT-FORM [START [END]]]) => *</procedure>
     316<procedure>(message-digest-string PRIM STRING [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    318317
    319318Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
     
    322321{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    323322
    324 Performs all three phases.
    325 
    326323==== message-digest-blob
    327324
    328 <procedure>(message-digest-blob PRIM BLOB [RESULT-FORM [START [END]]]) => *</procedure>
    329 
    330 Returns the {{<result>}} for the digest algorithm {{PRIM}} applied to
     325<procedure>(message-digest-blob PRIM BLOB [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
     326
     327Returns the {{result}} for the digest algorithm {{PRIM}} applied to
    331328{{BLOB}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
    332329
    333330{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    334331
    335 Performs all three phases.
    336 
    337332==== message-digest-string!
    338333
    339 <procedure>(message-digest-string! PRIM STRING BUFFER [START [END]]) => *</procedure>
     334<procedure>(message-digest-string! PRIM STRING BUFFER [START [END]]) -> message-digest-result-type</procedure>
    340335
    341336Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
    342337{{STRING}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
    343338
    344 Performs all three phases.
    345 
    346339==== message-digest-blob!
    347340
    348 <procedure>(message-digest-blob! PRIM BLOB BUFFER [START [END]]) => *</procedure>
    349 
    350 Returns the {{<result>}} for the digest algorithm {{PRIM}} applied to
     341<procedure>(message-digest-blob! PRIM BLOB BUFFER [START [END]]) -> message-digest-result-type</procedure>
     342
     343Returns the {{result}} for the digest algorithm {{PRIM}} applied to
    351344{{BLOB}}, optionally sliced by {{START END}}, in the {{{BUFFER}}}.
    352 
    353 Performs all three phases.
    354345
    355346==== message-digest-update-substring (DEPRECATED)
     
    488479Update the {{DIGEST}} with a {{THUNK}} until it returns {{#f}}.
    489480
    490 {{THUNK}} is a {{(procedure () <byte-source>)}}.
     481{{THUNK}} is a {{(-> byte-source)}}.
    491482
    492483==== message-digest-update-port
     
    494485<procedure>(message-digest-update-port DIGEST INPUT-PORT)</procedure>
    495486
    496 Update the {{DIGEST}} with {{<byte-source>}} from an {{INPUT-PORT}} until
     487Update the {{DIGEST}} with {{byte-source}} from an {{INPUT-PORT}} until
    497488{{#!eof}} encountered.
    498489
     
    505496Update the {{DIGEST}} with some {{SOURCE}}.
    506497
    507 {{SOURCE}} maybe an {{input-port}} (as in {{message-digest-update-port}}),
    508 {{procedure}} (as in {{message-digest-update-procedure}}), {{string}}, {{blob}},
    509 {{srfi-4-vector}}, or anything a supplied {{message-digest-chunk-converter}} recognizes &
    510 can convert into a {{<byte-source>}}.
    511 
    512 If supplied, and possible, the {{<byte-source>}} is sliced by {{START END}}.
     498{{SOURCE}} maybe
     499
     500; {{input-port}} : as in {{message-digest-update-port}}
     501; {{procedure}} : as in {{message-digest-update-procedure}}
     502; {{string}} :
     503; {{blob}} :
     504; {{srfi-4-vector}} :
     505; {{*}} : {{((message-digest-chunk-converter) SOURCE)}} -> {{byte-source}}.
     506
     507If {{START END}} supplied, and possible, the {{byte-source}} is sliced.
    513508
    514509
     
    525520==== message-digest-object
    526521
    527 <procedure>(message-digest-object PRIM SOURCE [RESULT-FORM [START [END]]]) => *</procedure>
     522<procedure>(message-digest-object PRIM SOURCE [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    528523
    529524Returns the result for the digest algorithm {{PRIM}} applied to
     
    532527{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    533528
    534 Performs all three phases.
    535 
    536529==== message-digest-file
    537530
    538 <procedure>(message-digest-file PRIM FILENAME [RESULT-FORM]) => *</procedure>
     531<procedure>(message-digest-file PRIM FILENAME [RESULT-FORM]) -> message-digest-result-type</procedure>
    539532
    540533Returns the result for the digest algorithm {{PRIM}} applied to the file
     
    543536{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    544537
    545 Performs all three phases.
    546 
    547538==== message-digest-port
    548539
    549 <procedure>(message-digest-port PRIM INPUT-PORT [RESULT-FORM]) => *</procedure>
     540<procedure>(message-digest-port PRIM INPUT-PORT [RESULT-FORM]) -> message-digest-result-type</procedure>
    550541
    551542Returns the result for the digest algorithm {{PRIM}} applied to
     
    554545{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    555546
    556 Performs all three phases.
    557 
    558547==== message-digest-object!
    559548
    560 <procedure>(message-digest-object! PRIM SOURCE BUFFER [START [END]]) => *</procedure>
     549<procedure>(message-digest-object! PRIM SOURCE BUFFER [START [END]]) -> message-digest-result-type</procedure>
    561550
    562551Returns the result for the digest algorithm {{PRIM}} applied to
    563552{{SOURCE}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
    564553
    565 Performs all three phases.
    566 
    567554==== message-digest-file!
    568555
    569 <procedure>(message-digest-file! PRIM FILENAME BUFFER) => *</procedure>
     556<procedure>(message-digest-file! PRIM FILENAME BUFFER) -> message-digest-result-type</procedure>
    570557
    571558Returns the result for the digest algorithm {{PRIM}} applied to the file
    572559{{FILENAME}} in the {{BUFFER}}. Reads until {{#!eof}} encountered.
    573560
    574 Performs all three phases.
    575 
    576561==== message-digest-port!
    577562
    578 <procedure>(message-digest-port! PRIM INPUT-PORT BUFFER) => *</procedure>
     563<procedure>(message-digest-port! PRIM INPUT-PORT BUFFER) -> message-digest-result-type</procedure>
    579564
    580565Returns the result for the digest algorithm {{PRIM}} applied to
    581566{{INPUT-PORT}} in the {{BUFFER}}. Reads until {{#!eof}} encountered.
    582567
    583 Performs all three phases.
    584 
    585568
    586569=== Message Digest SRFI 4
     
    602585==== message-digest-u8vector
    603586
    604 <procedure>(message-digest-u8vector PRIM U8VECTOR [RESULT-FORM [START [END]]]) => *</procedure>
     587<procedure>(message-digest-u8vector PRIM U8VECTOR [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
    605588
    606589Returns the result for the digest algorithm {{PRIM}} applied to
     
    609592{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    610593
    611 Performs all three phases.
    612 
    613594==== message-digest-u8vector!
    614595
    615 <procedure>(message-digest-u8vector! PRIM U8VECTOR BUFFER [START [END]]) => *</procedure>
     596<procedure>(message-digest-u8vector! PRIM U8VECTOR BUFFER [START [END]]) -> message-digest-result-type</procedure>
    616597
    617598Returns the result for the digest algorithm {{PRIM}} applied to
    618599{{U8VECTOR}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
    619600
    620 Performs all three phases.
    621 
    622601==== message-digest-update-subu8vector (DEPRECATED)
    623602
     
    653632==== digest-output-port
    654633
    655 <procedure>(digest-output-port? OBJ) => boolean</procedure>
     634<procedure>(digest-output-port? OBJ) -> boolean</procedure>
    656635<procedure>(check-digest-output-port LOC OBJ [NAM])</procedure>
    657636<procedure>(error-digest-output-port LOC OBJ [NAM])</procedure>
    658 <procedure>(digest-output-port-name PORT) => string</procedure>
     637<procedure>(digest-output-port-name PORT) -> string</procedure>
    659638
    660639==== open-output-digest
    661640
    662 <procedure>(open-output-digest PRIM) => digest-output-port</procedure>
     641<procedure>(open-output-digest PRIM) -> digest-output-port</procedure>
    663642
    664643Returns a message digest output port for the supplied algorithm {{PRIM}}.
     
    668647==== get-output-digest
    669648
    670 <procedure>(get-output-digest PORT [RESULT-FORM]) => string</procedure>
     649<procedure>(get-output-digest PORT [RESULT-FORM]) -> string</procedure>
    671650
    672651Closes the {{PORT}} and returns the result as a {{RESULT-FORM}}.
     
    678657==== call-with-output-digest
    679658
    680 <procedure>(call-with-output-digest PRIM PROC [RESULT-FORM]) => *</procedure>
     659<procedure>(call-with-output-digest PRIM PROC [RESULT-FORM]) -> message-digest-result-type</procedure>
    681660
    682661Returns the result of the call of {{PROC}} with an {{open-output-digest}} for
     
    685664{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    686665
    687 Performs all three phases.
    688 
    689666==== with-output-to-digest
    690667
    691 <procedure>(with-output-to-digest PRIM THUNK [RESULT-FORM]) => *</procedure>
     668<procedure>(with-output-to-digest PRIM THUNK [RESULT-FORM]) -> message-digest-result-type</procedure>
    692669
    693670Invoke the procedure {{THUNK}} with {{(current-output-port)}} bound to a
    694 {{digest-output-port}} and return {{<result>}} in the {{RESULT-FORM}}.
     671{{digest-output-port}} and return in the {{RESULT-FORM}}.
    695672
    696673{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    697674
    698 Performs all three phases.
    699 
    700675
    701676== Usage
    702677
    703 message-digest-primitive, message-digest-type, message-digest-parameters,
     678<enscript highlight=scheme>
     679(use message-digest-basic)
     680</enscript>
     681
     682* message-digest-primitive, message-digest-type, message-digest-chunk,
    704683message-digest-bv, message-digest-int
    705684
    706685<enscript highlight=scheme>
    707 (use message-digest-basic)
    708 </enscript>
    709 
    710 Everything in message-digest-basic plus message-digest-srfi-4,
    711 message-digest-update-item, message-digest-item
    712 
    713 <enscript highlight=scheme>
    714686(use message-digest)
    715687</enscript>
    716688
     689* Everything in message-digest-basic plus message-digest-srfi-4,
     690message-digest-update-item, message-digest-item, message-digest-port
     691
    717692
    718693== Examples
     
    721696
    722697<enscript highlight=scheme>
    723 (use message-digest-port)
    724 (use md5)    ; Or sha1, or sha2, ...
     698(use message-digest-port md5) ; Or sha1, or sha2, ...
    725699
    726700(call-with-output-digest (md5-primitive) (cut display "foo" <>))
     
    758732== Requirements
    759733
    760 [[setup-helper|setup-helper]]
    761 [[miscmacros|miscmacros]]
    762 [[check-errors|check-errors]]
    763 [[blob-utils|blob-utils]]
    764 [[string-utils|string-utils]]
     734[[miscmacros]]
     735[[check-errors]]
     736[[blob-utils]]
     737[[string-utils]]
     738[[dsssl-utils]]
     739
     740[[setup-helper]]
    765741
    766742
     
    806782== License
    807783
    808   Copyright (C) 2006-2017 Kon Lovett.  All rights reserved.
     784  Copyright (C) 2006-2018 Kon Lovett.  All rights reserved.
    809785
    810786  Permission is hereby granted, free of charge, to any person obtaining a
Note: See TracChangeset for help on using the changeset viewer.