suzanne.soy/hyper-literate
1
0
Fork 0
Code Issues 4 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

extend load-xref to support multi-use on-demand information

Browse Source 
The result of `load-xref` with an on-demand function only made sense
for a single use context, such as a single rendering request. Add an
on-demand callback that can work right for multiple uses.
This commit is contained in:
Matthew Flatt 2020-05-24 11:06:23 -06:00
parent 340c60ef54
commit 3d7ded8a33
3 changed files with 32 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
scribble-doc/scribblings/scribble/xref.scrbl
View File

@ -20,6 +20,10 @@ by @racket[load-xref], @racket[#f] otherwise.}
@defproc[(load-xref [sources (listof (-> (or/c any/c (-> list?))))]
[#:demand-source-for-use
demand-source-for-use
(tag? symbol? -> (or/c (-> any/c) #f))
(lambda (_tag _use-id) (demand-source _tag))]
[#:demand-source demand-source
(tag? -> (or/c (-> any/c) #f))
(lambda (_tag) #f)]
@ -45,10 +49,22 @@ information, a @racket[#f] to be ignored, or a value produced by
and the @racket[_doc-id] part (if any) overrides
@racket[doc-id-string] to identify the source document.
The @racket[demand-source] function can effectively add a new source
to @racket[sources] in response to a search for information on the
given tag. The @racket[demand-source] function returns @racket[#f]
to indicate that no new sources satisfy the given tag.
The @racket[demand-source-for-use] function can effectively add a new
source to @racket[sources] in response to a search for information on
the given tag in the given rendering, where @racket[_use-id] is unique
to a particular rendering request, a particular transfer (in the sense
of @racket[xref-transfer-info]), or all direct queries of the
cross-reference information (such as through
@racket[xref-binding->definition-tag]). The
@racket[demand-source-for-use] function should return @racket[#f] to
indicate that no new sources satisfy the given tag for the given
@racket[_use-id].
The default @racket[demand-source-for-use] function uses
@racket[demand-source], which is provided only for backward
compatibility. Since the @racket[demand-source] function accepts only
a tag, it is suitable only when the result of @racket[load-xref] will
only have a single use context, such as a single rendering.
Since the format of serialized information is specific to a rendering
class, the optional @racket[using-render%] argument accepts the
@ -72,7 +88,8 @@ method of @racket[render-mixin].
Use @racket[load-collections-xref] from @racketmodname[setup/xref] to
get all cross-reference information for installed documentation.
@history[#:changed "1.1" @elem{Added the @racket[#:doc-id] argument.}]}
@history[#:changed "1.1" @elem{Added the @racket[#:doc-id] argument.}
#:changed "1.34" @elem{Added the @racket[#:demand-source-for-use] argument.}]}
@defproc[(xref-binding->definition-tag [xref xref?]

2
scribble-lib/info.rkt
View File

@ -23,4 +23,4 @@
(define pkg-authors '(mflatt eli))
(define version "1.33")
(define version "1.34")

10
scribble-lib/scribble/xref.rkt
View File

@ -43,6 +43,8 @@
(define (load-xref sources
#:demand-source [demand-source (lambda (key) #f)]
#:demand-source-for-use [demand-source-for-use
(lambda (key use-id) (demand-source key))]
#:render% [render% (html:render-mixin render%)]
#:root [root-path #f]
#:doc-id [doc-id-str #f])
@ -61,9 +63,15 @@
(send renderer deserialize-info data ci
#:root root
#:doc-id doc-id))))))]
[use-ids (make-weak-hasheq)]
[ci (send renderer collect null null fp
(lambda (key ci)
(define src (demand-source key))
(define use-obj (collect-info-ext-ht ci))
(define use-id (or (hash-ref use-ids use-obj #f)
(let ([s (gensym 'render)])
(hash-set! use-ids use-obj s)
s)))
(define src (demand-source-for-use key use-id))
(and src
(load-source src ci))))])
(for ([src sources])