[racket] How to read procedure documentation?

Manfred, hello.

On 2013 Apr 19, at 19:18, Manfred Lotz wrote:

> I don't seem to know how to read procedure documentation like in the
> following example.
> 
>    (file->string path [#:mode mode-flag]) → string?
> 
>  path : path-string?
>  mode-flag : (or/c 'binary 'text) = 'binary
> 
> 
> I would expect that the first parameter path is a string and that the
> second parameter is an optional parameter denoting a file mode. Further
> I would assume that file->string returns a string containing the whole
> file.

The first argument to the function ('path') must satisfy the predicate 'path-string?'  Checking that procedure in the documentation[1] says "Return #t if v is either a path value for the current platform or a non-empty string without nul characters, #f otherwise."  That is, it can be a string filename, or a pre-composed version of that, a 'path', which is a structure which various procedures can operate on.  One could (I suppose) define path-string? as something like:

  (define (path-string? x) 
    (or (path? x)
        (string? x)))

The mode-flag argument is a 'contract'[2], which is sort-of like a predicate, but can be checked in a more thorough way (I'm omitting quite a lot of detail, here!).

So in contract terms, this bit of procedure documentation is saying that the file->string procedure obeys a contract where you can call it with an argument which satisfies path-string?, and optionally an argument which is either 'binary or 'text (and if you don't, the system will object on the procedure's behalf); and it contracts itself to produce a value which matches string? (and if it doesn't, the system will object on your behalf).

So yes, the summary you gave is pretty much accurate (except that you could give it a pre-composed 'path' value, as well).

Does this help at all?

All the best,

Norman


[1] http://docs.racket-lang.org/reference/Manipulating_Paths.html?q=path-string%3F#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29

[2] http://docs.racket-lang.org/reference/data-structure-contracts.html?q=or/c&q=path-string%3F#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._or%2Fc%29%29

-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK