Changeset 39470 in project


Ignore:
Timestamp:
12/30/20 05:26:53 (3 weeks ago)
Author:
Zipheir
Message:

Use italics for argument names, following R7RS style.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/srfi-189

    r39422 r39470  
    6969<procedure>(just obj ...)</procedure>
    7070
    71 Monadic pure. Returns the {{objs}} wrapped in a Just.
     71Monadic pure. Returns the ''objs'' wrapped in a Just.
    7272
    7373<procedure>(nothing)</procedure>
     
    7777<procedure>(right obj ...)</procedure>
    7878
    79 Monadic pure. Returns the {{objs}} wrapped in a Right.
     79Monadic pure. Returns the ''objs'' wrapped in a Right.
    8080
    8181<procedure>(left obj ...)</procedure>
    8282
    83 Returns the {{objs}} wrapped in a Left.
     83Returns the ''objs'' wrapped in a Left.
    8484
    8585<procedure>(list->just list)</procedure>
     
    8787<procedure>(list->right list)</procedure>
    8888
    89 Returns a Just / Left / Right whose values are the elements of {{list}}. Note
     89Returns a Just / Left / Right whose values are the elements of ''list''. Note
    9090that these procedures are not monadic; they are equivalent to
    9191just/left/right but accept a list rather than multiple arguments. There is
     
    9494<procedure>(maybe->either maybe obj ...)</procedure>
    9595
    96 If {{maybe}} is a Just, returns a Right with the same payload objects in the
    97 sense of {{eqv?}}; otherwise returns a Left of _objs_.
     96If ''maybe'' is a Just, returns a Right with the same payload objects in the
     97sense of {{eqv?}}; otherwise returns a Left of ''objs''.
    9898
    9999<procedure>(either->maybe either)</procedure>
    100100
    101 If {{either}} is a Right, returns a Just with the same payload objects in the
     101If ''either'' is a Right, returns a Just with the same payload objects in the
    102102sense of {{eqv?}}; otherwise returns Nothing.
    103103
    104104<procedure>(either-swap either)</procedure>
    105105
    106 If {{either}} is a Left, return a Right with the same payload objects (in the
     106If ''either'' is a Left, return a Right with the same payload objects (in the
    107107sense of {{eqv?}}), and vice versa.
    108108
     
    114114<procedure>(left? obj)</procedure>
    115115
    116 Returns {{#t}} if {{obj}} is a Just, Nothing, Left, or Right respectively, and
     116Returns {{#t}} if ''obj'' is a Just, Nothing, Left, or Right respectively, and
    117117{{#f}} otherwise.
    118118
    119119<procedure>(maybe? obj)</procedure>
    120120
    121 Returns {{#t}} if {{obj}} is a Maybe (that is, either a Just or Nothing) and {{#f}}
     121Returns {{#t}} if ''obj'' is a Maybe (that is, either a Just or Nothing) and {{#f}}
    122122otherwise.
    123123
    124124<procedure>(either? obj)</procedure>
    125125
    126 Returns {{#t}} if {{obj}} is an Either (that is, either a Right or a Left) and
     126Returns {{#t}} if ''obj'' is an Either (that is, either a Right or a Left) and
    127127{{#f}} otherwise.
    128128
    129129<procedure>(maybe= equal maybe1 maybe2 ...)</procedure>
    130130
    131 Returns {{#t}} if all {{maybes}} are Nothing, or if they all are Justs and their
    132 respective payload objects are the same in the sense of {{equal}}, and {{#f}}
     131Returns {{#t}} if all ''maybes'' are Nothing, or if they all are Justs and their
     132respective payload objects are the same in the sense of ''equal'', and {{#f}}
    133133otherwise.
    134134
    135135<procedure>(either= equal either1 either2 ...)</procedure>
    136136
    137 Returns {{#t}} if all {{eithers}} are all Lefts or all Rights and their respective
    138 payload objects are the same in the sense of {{equal}}, and {{#f}} otherwise.
     137Returns {{#t}} if all ''eithers'' are all Lefts or all Rights and their respective
     138payload objects are the same in the sense of ''equal'', and {{#f}} otherwise.
    139139
    140140=== Accessors
     
    142142<procedure>(maybe-ref maybe failure [success])</procedure>
    143143
    144 If {{maybe}} is a Just, tail-calls the procedure {{success}} on the values of its
     144If ''maybe'' is a Just, tail-calls the procedure ''success'' on the values of its
    145145payload and returns the result. Otherwise, it tail-calls the procedure
    146 {{failure}} on no arguments and returns the result. The default value of
    147 {{success}} is {{values}}.
     146''failure'' on no arguments and returns the result. The default value of
     147''success'' is {{values}}.
    148148
    149149<procedure>(either-ref either failure [success])</procedure>
    150150
    151 If {{either}} is a Right, tail-calls the procedure {{success}} on the values of
     151If ''either'' is a Right, tail-calls the procedure ''success'' on the values of
    152152its payload and returns the result. Otherwise, it tail-calls the procedure
    153 {{failure}} on the values of its payload and returns the result. The default
    154 value of {{success}} is {{values}}.
     153''failure'' on the values of its payload and returns the result. The default
     154value of ''success'' is {{values}}.
    155155
    156156<procedure>(maybe-ref/default maybe default ...)</procedure>
    157157<procedure>(either-ref/default either default ...)</procedure>
    158158
    159 If {{maybe/either}} is a Just/Right, returns the values of its payload;
    160 otherwise returns the {{defaults}} as multiple values.
     159If ''maybe''/''either'' is a Just/Right, returns the values of its payload;
     160otherwise returns the ''defaults'' as multiple values.
    161161
    162162=== Join and bind
     
    165165<procedure>(either-join either)</procedure>
    166166
    167 Monadic join. If {{maybe/either}} is a Just/Right whose single payload object is
     167Monadic join. If ''maybe''/''either'' is a Just/Right whose single payload object is
    168168a Maybe/Either, returns that payload; if it is a Nothing/Left, returns
    169 {{maybe}}/{{either}}. In all other cases (including a Just/Right with multiple
     169''maybe''/''either''. In all other cases (including a Just/Right with multiple
    170170values) it is an error. Thus {{(maybe-join (just (just x))}} returns Just
    171171{{x}} and {{(maybe-join (just (nothing))}} returns Nothing, and similarly for
     
    176176
    177177Returns an mproc that accepts zero or more arguments and applies the following
    178 iterative algorithm to each {{mproc}}:
    179 
    180 The {{mproc}} is applied to the arguments and returns a Maybe/Either interim
     178iterative algorithm to each ''mproc'':
     179
     180The ''mproc'' is applied to the arguments and returns a Maybe/Either interim
    181181result. If the result is Nothing / a Left, it is returned as the final result.
    182 If it is a Just/Right, the next {{mproc}} is applied to the values of its
    183 payload, returning the next interim result. When no more {{mprocs}} are
     182If it is a Just/Right, the next ''mproc'' is applied to the values of its
     183payload, returning the next interim result. When no more ''mprocs'' are
    184184available, the interim result is returned as the final result.
    185185
    186 It is an error if one of the {{mprocs}} does not accept as arguments the number
     186It is an error if one of the ''mprocs'' does not accept as arguments the number
    187187of values wrapped in the Just/Right produced by its predecessor.
    188188
     
    190190<procedure>(either-bind either mproc1 mproc2 ...)</procedure>
    191191
    192 Monadic bind. If {{maybe/either}} is a Just/Right, it behaves as if
    193 {{maybe-compose}}/{{either-compose}} were applied to {{mprocs}}, and the
    194 resulting mproc applied to the payload of {{maybe}}/{{either}}. But if
    195 {{maybe}}/{{either}} is a Nothing/Left, it is immediately returned.
     192Monadic bind. If ''maybe/either'' is a Just/Right, it behaves as if
     193{{maybe-compose}}/{{either-compose}} were applied to ''mprocs'', and the
     194resulting mproc applied to the payload of ''maybe''/''either''. But if
     195''maybe''/''either'' is a Nothing/Left, it is immediately returned.
    196196
    197197=== Sequence operations
     
    204204<procedure>(either-length either)</procedure>
    205205
    206 Return 1 if {{maybe}}/{{either}} is a Just/Right, and 0 otherwise.
     206Return 1 if ''maybe''/''either'' is a Just/Right, and 0 otherwise.
    207207
    208208<procedure>(maybe-filter pred maybe)</procedure>
     
    211211<procedure>(either-remove pred either obj ...)</procedure>
    212212
    213 If {{maybe}}/{{either}} is a Just/Right and the values of its payload satisfy / do
    214 not satisfy {{pred}}, then return {{maybe}}; otherwise, returns Nothing / a Left
    215 of {{objs}}.
     213If ''maybe''/''either'' is a Just/Right and the values of its payload satisfy / do
     214not satisfy ''pred'', then return ''maybe''; otherwise, returns Nothing / a Left
     215of ''objs''.
    216216
    217217<procedure>(maybe-sequence mappable map [aggregator])</procedure>
     
    222222type.
    223223
    224 The {{mappable}} argument is the collection to be transformed, and the {{map}}
     224The ''mappable'' argument is the collection to be transformed, and the ''map''
    225225argument is the appropriate procedure that can transform it, one element at a
    226 time. The signature of {{map}} is {{(map proc mappable)}}, where {{proc}} is
     226time. The signature of ''map'' is {{(map proc mappable)}}, where ''proc'' is
    227227supplied by the implementation. Typical mappables are lists and vectors, and
    228228{{map}} and {{vector-map}} are useful map functions, though not the only possible
     
    230230
    231231Each element is processed as follows: If it is a Just/Right, its values are
    232 unwrapped and the {{aggregator}} function (which defaults to {{list}}) is applied
     232unwrapped and the ''aggregator'' function (which defaults to {{list}}) is applied
    233233to them. But if it is a Left/Nothing, that object is immediately returned as
    234234the value of {{maybe-sequence}}/{{either-sequence}}.
    235235
    236 Assuming there are no Lefts/Nothings, the {{map}} function is then responsible
     236Assuming there are no Lefts/Nothings, the ''map'' function is then responsible
    237237for constructing the new mappable out of the results of the calls on
    238 {{aggregator}}.
     238''aggregator''.
    239239
    240240For example, a list of Justs becomes a Just list of lists if the map procedure
     
    267267<procedure>(either->list either)</procedure>
    268268
    269 Returns a list whose elements are the payload of {{maybe}}/{{either}}; if
    270 {{maybe}}/{{either}} is Nothing/Left, returns the empty list. It is an error to
     269Returns a list whose elements are the payload of ''maybe''/''either''; if
     270''maybe''/''either'' is Nothing/Left, returns the empty list. It is an error to
    271271mutate the result of this procedure.
    272272
     
    274274<procedure>(list->either list obj ...)</procedure>
    275275
    276 If {{list}} is empty, returns Nothing / wraps {{objs}} in a Left and returns it;
     276If ''list'' is empty, returns Nothing / wraps ''objs'' in a Left and returns it;
    277277otherwise, wraps the list elements in a Just/Right and returns that.
    278278
     
    284284<procedure>(either->truth either)</procedure>
    285285
    286 If {{maybe}}/{{either}} is a Just/Right, returns its payload; otherwise returns
     286If ''maybe''/''either'' is a Just/Right, returns its payload; otherwise returns
    287287{{#f}}. It is an error if the Just/Right does not have exactly one value.
    288288
     
    290290<procedure>(truth->either obj fail-obj ...)</procedure>
    291291
    292 If {{obj}} is {{#f}}, return Nothing / a Left of {{fail-objs}}; otherwise, return a
    293 Just/Right whose payload is {{obj}}.
     292If ''obj'' is {{#f}}, return Nothing / a Left of ''fail-objs''; otherwise, return a
     293Just/Right whose payload is ''obj''.
    294294
    295295☞ The following procedures interface between the Maybe protocol and the
     
    300300<procedure>(either->list-truth either)</procedure>
    301301
    302 If {{maybe}}/{{either}} is a Just/Right, returns a list whose elements are the
     302If ''maybe''/''either'' is a Just/Right, returns a list whose elements are the
    303303payload; otherwise, returns {{#f}}. It is an error to mutate the result of this
    304304procedure.
     
    307307<procedure>(list-truth->either list-or-false obj ...)</procedure>
    308308
    309 If {{list-or-false}} is {{#f}}, returns Nothing / a Left of {{objs}}; otherwise,
     309If ''list-or-false'' is {{#f}}, returns Nothing / a Left of ''objs''; otherwise,
    310310wraps the list elements in a Just/Right and returns it.
    311311
     
    317317<procedure>(either->generation either)</procedure>
    318318
    319 If {{maybe}}/{{either}} is a Just/Right, then its payload is returned. It is an
    320 error if the Just/Right does not have exactly one value. If {{maybe}}/{{either}}
     319If ''maybe''/''either'' is a Just/Right, then its payload is returned. It is an
     320error if the Just/Right does not have exactly one value. If ''maybe''/''either''
    321321is Nothing / a Left, then an end-of-file object is returned.
    322322
     
    324324<procedure>(generation->either obj fail-objs ...)</procedure>
    325325
    326 If {{obj}} is an end-of-file object, return Nothing / a Left of {{fail-objs}}.
    327 Otherwise, return {{obj}} wrapped in a Just/Right.
     326If ''obj'' is an end-of-file object, return Nothing / a Left of ''fail-objs''.
     327Otherwise, return ''obj'' wrapped in a Just/Right.
    328328
    329329☞ The following procedures interface between the Maybe and Either protocols
     
    334334<procedure>(either->values either)</procedure>
    335335
    336 If {{maybe}}/{{either}} is a Just/Right, returns the values of its payload;
     336If ''maybe''/''either'' is a Just/Right, returns the values of its payload;
    337337otherwise returns no values.
    338338
     
    340340<procedure>(values->either producer fail-obj ...)</procedure>
    341341
    342 These procedures invoke {{producer}} with no arguments. If no values are
    343 returned, Nothing / Left of {{fail-objs}} is returned. Otherwise the values are
     342These procedures invoke ''producer'' with no arguments. If no values are
     343returned, Nothing / Left of ''fail-objs'' is returned. Otherwise the values are
    344344wrapped in a Just/Right and returned.
    345345
     
    352352<procedure>(maybe->two-values maybe)</procedure>
    353353
    354 If {{maybe}} is a Just, returns the value of its payload and the additional
    355 value {{#t}}; otherwise returns two values, both {{#f}}. It is an error if {{maybe}}
     354If ''maybe'' is a Just, returns the value of its payload and the additional
     355value {{#t}}; otherwise returns two values, both {{#f}}. It is an error if ''maybe''
    356356does not have exactly one value.
    357357
    358358<procedure>(two-values->maybe producer)</procedure>
    359359
    360 This procedure is the inverse of {{maybe->two-values}}. It invokes {{producer}}
     360This procedure is the inverse of {{maybe->two-values}}. It invokes ''producer''
    361361with no arguments. If the second value is true, the first value is wrapped in
    362362a Just and returned; otherwise, Nothing is returned.
     
    364364<procedure>(exception->either pred thunk)</procedure>
    365365
    366 This procedure is in a sense the inverse of {{maybe-ref}}. A call to {{thunk}} is
     366This procedure is in a sense the inverse of {{maybe-ref}}. A call to ''thunk'' is
    367367made, wrapped in an exception handler that examines any exception signaled
    368 during {{thunk}}'s execution. If the condition object satisfies {{pred}}, it is
     368during ''thunk'''s execution. If the condition object satisfies ''pred'', it is
    369369wrapped in a Left which is then returned; if it does not, the exception is
    370 reraised. But if no exception is raised, the values returned by {{thunk}} are
     370reraised. But if no exception is raised, the values returned by ''thunk'' are
    371371wrapped in a Right and the Right is returned.
    372372
     
    376376<procedure>(either-map proc either)</procedure>
    377377
    378 Monadic map. If {{maybe}}/{{either}} is a Just/Right, applies {{proc}} to the payload
     378Monadic map. If ''maybe''/''either'' is a Just/Right, applies ''proc'' to the payload
    379379values and wraps the returned values as a Just/Right; otherwise returns
    380 {{maybe}}/{{either}}.
     380''maybe''/''either''.
    381381
    382382<procedure>(maybe-for-each proc maybe)</procedure>
    383383<procedure>(either-for-each proc either)</procedure>
    384384
    385 If {{maybe}}/{{either}} is a Just/Right, applies {{proc}} to the payload values and
     385If ''maybe''/''either'' is a Just/Right, applies ''proc'' to the payload values and
    386386discards the result; otherwise does nothing. Returns an unspecified result.
    387387
     
    389389<procedure>(either-fold kons nil either)</procedure>
    390390
    391 If {{maybe}}/{{either}} is a Just/Right, {{kons}} is invoked on the values of its
    392 payload and the additional value {{nil}} and the result is returned; otherwise,
    393 {{nil}} is returned.
     391If ''maybe''/''either'' is a Just/Right, ''kons'' is invoked on the values of its
     392payload and the additional value ''nil'' and the result is returned; otherwise,
     393''nil'' is returned.
    394394
    395395<procedure>(maybe-unfold stop? mapper successor seed ...)</procedure>
    396396<procedure>(either-unfold stop? mapper successor seed ...)</procedure>
    397397
    398 If {{stop?}} returns true on {{seeds}}, a Nothing / a Left of {{seeds}} is returned.
    399 Otherwise, {{successor}} is applied to {{seeds}}. If {{stop?}} returns false on the
    400 results of {{successor}}, it is an error. But if the second call to {{stop?}}
    401 returns true, {{mapper}} is applied to {{seeds}} and the results are wrapped in a
     398If ''stop?'' returns true on ''seeds'', a Nothing / a Left of ''seeds'' is returned.
     399Otherwise, ''successor'' is applied to ''seeds''. If ''stop?'' returns false on the
     400results of ''successor'', it is an error. But if the second call to ''stop?''
     401returns true, ''mapper'' is applied to ''seeds'' and the results are wrapped in a
    402402Just/Right and returned.
    403403
     
    407407
    408408Equivalent to {{(if (just? maybe-expr) just-expr nothing-expr)}}, except
    409 that an error satisfying {{error-object?}} is signaled if {{maybe-expr}} does not
     409that an error satisfying {{error-object?}} is signaled if ''maybe-expr'' does not
    410410evaluate to a Maybe.
    411411
     
    413413<syntax>(either-and expr ...)</syntax>
    414414
    415 The {{expr}}s are evaluated in order. If an {{expr}} evaluates to a Nothing /
     415The ''expr''s are evaluated in order. If an ''expr'' evaluates to a Nothing /
    416416Left, it is returned without evaluating any more expressions. Otherwise, the
    417 last Just / Right is returned. If there are no {{exprs}}, then a Just/Right of
    418 an unspecified value is returned. If an {{expr}} does not evaluate to a
     417last Just / Right is returned. If there are no ''exprs'', then a Just/Right of
     418an unspecified value is returned. If an ''expr'' does not evaluate to a
    419419Maybe/Either, an error satisfying {{error-object}} is signaled.
    420420
     
    422422<syntax>(either-or expr ...)</syntax>
    423423
    424 The {{exprs}} are evaluated in order. If an {{expr}} evaluates to a Just/Right, it
     424The ''exprs'' are evaluated in order. If an ''expr'' evaluates to a Just/Right, it
    425425is returned without evaluating any more expressions. Otherwise, the last
    426 Nothing/Left is returned. If there are no {{exprs}}, then Nothing / a Left of an
    427 unspecified value is returned. If an {{expr}} does not evaluate to a
     426Nothing/Left is returned. If there are no ''exprs'', then Nothing / a Left of an
     427unspecified value is returned. If an ''expr'' does not evaluate to a
    428428Maybe/Either, an error satisfying {{error-object}} is signaled.
    429429
     
    433433The Maybe/Either equivalent of {{and-let*}} from [[http://srfi.schemers.org/srfi-2/srfi-2.html|SRFI 2]].
    434434However, instead of testing
    435 whether a {{claw}} is true or false, it tests whether it is Just/Right or
    436 Nothing/Left. If a {{claw}} does not evaluate to a Maybe/Either, an error
    437 satisfying {{error-object}} is signaled. The same is true if a {{claw}} evaluates
     435whether a ''claw'' is true or false, it tests whether it is Just/Right or
     436Nothing/Left. If a ''claw'' does not evaluate to a Maybe/Either, an error
     437satisfying {{error-object}} is signaled. The same is true if a ''claw'' evaluates
    438438to a Just or Right that wraps zero values or more than one value.
    439439
    440 A {{claw}} is either a bound identifier, or a list of length 1, in which case it
     440A ''claw'' is either a bound identifier, or a list of length 1, in which case it
    441441is an expression, or a list of length 2, in which case it is a variable and an
    442 expression. In either case, the value of the {{claw}} is the value of the bound
    443 variable or expression. If the value of a {{claw}} is Nothing / a Left, the
    444 expression immediately returns that value. But if the value of a {{claw}} is a
     442expression. In either case, the value of the ''claw'' is the value of the bound
     443variable or expression. If the value of a ''claw'' is Nothing / a Left, the
     444expression immediately returns that value. But if the value of a ''claw'' is a
    445445Just/Right, then the variable (if any) is bound to its unwrapped value; the
    446 scope of this binding is any remaining {{claws}} and the {{body}}.
    447 
    448 If the values of all the {{claws}} are Just/Right, then the {{body}} is evaluated
     446scope of this binding is any remaining ''claws'' and the ''body''.
     447
     448If the values of all the ''claws'' are Just/Right, then the ''body'' is evaluated
    449449as if it were in a {{(let () ...)}}, and its values are wrapped in a Just/Right
    450450and returned.
     
    464464<syntax>(either-guard pred-expr . body)</syntax>
    465465
    466 The syntactic analogue of {{exception->either}}. The {{body}} is evaluated, and
     466The syntactic analogue of {{exception->either}}. The ''body'' is evaluated, and
    467467the values it produces are wrapped in a Right and returned, unless an
    468468exception occurs. If the condition object that is raised satisfies the
    469 predicate that is the value of {{pred-expr}}, the condition object is wrapped in
     469predicate that is the value of ''pred-expr'', the condition object is wrapped in
    470470a Left and returned; otherwise the condition is reraised as if by {{raise-continuable}}.
    471471
     
    485485<procedure>(tri-not maybe)</procedure>
    486486
    487 Returns Just {{#t}} if {{maybe}} is false, Just {{#f}} if {{maybe}} is true, and
    488 Nothing if {{maybe}} is Nothing.
     487Returns Just {{#t}} if ''maybe'' is false, Just {{#f}} if ''maybe'' is true, and
     488Nothing if ''maybe'' is Nothing.
    489489
    490490<procedure>(tri=? maybe1 maybe2 ...)</procedure>
    491491
    492 Similar to {{boolean=?}}, returning Just {{#t}} if all the {{maybes}} are true or if
    493 all are false. Otherwise, if any {{maybe}} is Nothing or any two {{maybes}} have
     492Similar to {{boolean=?}}, returning Just {{#t}} if all the ''maybes'' are true or if
     493all are false. Otherwise, if any ''maybe'' is Nothing or any two ''maybes'' have
    494494different (trivalent) truth values, returns Just {{#f}}.
    495495
     
    499499<procedure>(tri-and maybe ...)</procedure>
    500500
    501 If all {{maybes}} are true, Just {{#t}} is returned. If any {{maybe}} is false or
    502 Nothing, then the first such {{maybe}} is returned. If there are no arguments,
     501If all ''maybes'' are true, Just {{#t}} is returned. If any ''maybe'' is false or
     502Nothing, then the first such ''maybe'' is returned. If there are no arguments,
    503503Just {{#t}} is returned.
    504504
    505505<procedure>(tri-or maybe ...)</procedure>
    506506
    507 If all {{maybes}} are false, Just {{#f}} is returned. If any {{maybe}} is true or
    508 Nothing, then the first such {{maybe}} is returned. If there are no arguments,
     507If all ''maybes'' are false, Just {{#f}} is returned. If any ''maybe'' is true or
     508Nothing, then the first such ''maybe'' is returned. If there are no arguments,
    509509Just {{#f}} is returned.
    510510
    511511<procedure>(tri-merge maybe ...)</procedure>
    512512
    513 If any {{maybes}} are true or false, then the first such {{maybe}} is returned. If
    514 all {{maybes}} are Nothing, then Nothing is returned. If there are no arguments,
     513If any ''maybes'' are true or false, then the first such ''maybe'' is returned. If
     514all ''maybes'' are Nothing, then Nothing is returned. If there are no arguments,
    515515Nothing is returned.
    516516
Note: See TracChangeset for help on using the changeset viewer.