[racket] How to read procedure documentation?

Hi Norman,
First, thanks to you and Asumu for your help.

On Fri, 19 Apr 2013 19:56:22 +0100
Norman Gray <norman at astro.gla.ac.uk> wrote:

> 
> 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?
> 

Yep, helped very much. Now I know that I have to understand a predicate
in place of a parameter as 'the parameter must satisfy the predicate'.
If I think further I recognize that scheme/racket isn't a statically
typed language, and thus giving a predicate as a constraint for a
parameter is on the one hand pretty flexible and on the other
hand much more powerful than specifying types which doesn't fit as good.

I also will read more about contracts.


-- 
Manfred