WIP document ##wr #715
WIP document ##wr #715
Conversation
doc/gambit.txi
Outdated
| (lambda (we obj) | ||
| (case (macro-writeenv-style we) | ||
| ((mark) | ||
| (##default-wr we obj)) |
There was a problem hiding this comment.
This example does not use a good coding style. The branch for the mark case must call ##wr recursively the same way as the other case branch. This is to ensure that the sharing of subobjects is correctly computed during the mark phase. By calling ##default-wr the code is assuming that the default writer will call ##wr like the else branch and it is a coincidence that this is true for symbols. The example may confuse people into thinking this works for all objects.
doc/gambit.txi
Outdated
| @@ -18110,6 +18110,23 @@ Here is an example: | |||
| ;; (#<area-of-rectangle> #<aarea-of-rectangle> #<area-of-rectangle>) | |||
There was a problem hiding this comment.
There's an extra a on aarea-of-rectangle.
|
Should I give examples of teach of the below? |
| @chapter Internal APIs | ||
| @cindex Internal | ||
|
|
||
| Gambit has many internal functions that you might want to use |
There was a problem hiding this comment.
"functions" -> "procedures" (that's the standard name for "functions" in Scheme)
|
|
||
| Gambit has many internal functions that you might want to use | ||
| while writing the lower-level parts of your programs, or debugging them. | ||
| Be mindful though that these functions are subject to change without warning, |
There was a problem hiding this comment.
Same here and in other places too...
| This chapter only covers those few internals that a member of the community | ||
| felt the need to document. | ||
| We encourage you to document those internals you use, or | ||
| to pay a developer to document those you'd like to use. |
There was a problem hiding this comment.
"pay" -> "convince" (since there are many ways to achieve getting another developer to work on the documentation)
| By using the following internals, you can extend the Gambit writer, | ||
| as invoked by @code{write}, to specially recognize and print your data structures. | ||
|
|
||
| @deffn ##wr-set! @var{write-function} |
| This is the main entry point of the internal writer API, that will | ||
| be called by @code{write}, then recursively by other writer functions. | ||
|
|
||
| The entire point of this variable is that you can @code{set!} it |
There was a problem hiding this comment.
Uses of (set! ##wr ...) should be discouraged. The call (##wr-set! procedure) is better because it doesn't expose the implementation of the writer (and this will eventually help the intelligent linker). An even better way is
(include "~~lib/_gambit#.scm") ;; import the "primitive" special form
((primitive wr-set!) <procedure>)
or the alternative
(include "~~lib/_gambit#.scm") ;; import the "primitive" special form
(primitive (wr-set! <procedure>))
or even the following (useful when several calls to wr-set! are made):
(let ()
(namespace ("##" wr-set!))
(wr-set! <procedure>))
This allows avoiding the ## prefix, which is visually displeasing and also will not work with other Scheme systems that don't support ## in symbols (so that the code has the possibility in the long term to be used by other Scheme systems).
This should be explained in the introduction to the "Internal APIs" section because it applies to any internal primitive procedures.
| @itemize | ||
|
|
||
| @item style: | ||
| Its value is one of write-simple/write-shared/write/display/print/pretty-print/mark |
There was a problem hiding this comment.
The symbols should be wrapped in @code{...}
| character above which escapes are used when writing | ||
| out characters (to use only ASCII in output) | ||
|
|
||
| @item symbol @code{not-abandoned}: |
|
|
||
| (define-type point x y) | ||
|
|
||
| (##wr-set! |
There was a problem hiding this comment.
Following the advice given above, this would be better:
(let ()
(namespace ("##" wr-set! wr wr-mark-begin wr-mark-end wr-stamp wr-str))
(define old-wr wr)
(wr-set!
(lambda (we obj) ;; we = write environment, obj = object to write
(if (not (point? obj))
(old-wr we obj) ;; write other objects like before
(case (macro-writeenv-style we)
((mark)
(if (wr-mark-begin we obj) ;; begin a marking extent
(begin ;; this is first visit of obj
(wr we (point-x obj)) ;; recursively mark x field
(wr we (point-y obj)) ;; recursively mark y field
(wr-mark-end we obj)))) ;; end the marking extent
(else
(if (wr-stamp we obj)
(begin
(wr-str we "#<pt x: ")
(wr we (point-x obj))
(wr-str we " y: ")
(wr we (point-y obj))
(wr-str we ">")))))))))
| and call the @code{##wr} function on them. | ||
| @end deffn | ||
|
|
||
| @deffn macro-writeenv-port @var{write-env} |
There was a problem hiding this comment.
A brief explanation of this procedure (and the others below) would be good.
| @deffn ##wr-sn @var{write-env} @var{object} @var{type} @var{name} | ||
| @end deffn | ||
|
|
||
| You may set this ``write-env'' with the following macros: |
There was a problem hiding this comment.
These should be paired with the accessors.
Fixes ##wr #665
Copied Fare work and add for examples.