suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

attempt to clarify the drracket:tool-exports^ docs

Browse Source
This commit is contained in:
Robby Findler 2013-09-09 08:48:48 -05:00
parent 2cd4dd16da
commit cbfa7ac0ea
2 changed files with 92 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
pkgs/drracket-pkgs/drracket/scribblings/tools/tools.scrbl
View File

@ -118,54 +118,19 @@ This bitmap and the name show up in the about box, the
bug report form, and the splash screen as the tool is bug report form, and the splash screen as the tool is
loaded at DrRacket's startup. loaded at DrRacket's startup.
@index{phase1}
@index{phase2}
Each of the @racket[drracket-tools] files must contain a module that Each of the @racket[drracket-tools] files must contain a module that
@racket[provide]s @racket[tool@], which must be bound to a @racket[provide]s @racket[tool@], which must be bound to a
@racket[unit]. The unit @racket[unit]. The unit
must import the @racket[drracket:tool^] signature, which is must import the @racket[drracket:tool^] signature, which is
provided by the @FileFirst{tool.rkt} library in the provided by the @racketmodname[drracket/tool] library.
@racket[drscheme] collection. The @as-index{@racket[drracket:tool^]} The @as-index{@racket[drracket:tool^]}
signature contains all of the names listed in this manual. signature contains all of the names listed in this manual.
The unit must export the @racket[drracket:tool-exports^] The unit must export the @racket[drracket:tool-exports^]
signature. signature.
The @as-index{@racket[drracket:tool-exports^]} signature contains two
names: @racket[phase1] and @racket[phase2]. These names must
be bound to thunks. After all of the tools are loaded, all of
the @tt{phase1} functions are called and then all of the
@tt{phase2} functions are called. Certain primitives can
only be called during the dynamic extent of those calls.
This mechanism is designed to support DrRacket's
@racket[drracket:language:language<%>] extension
capabilities. That is, this mechanism enables two tools to
cooperate via new capabilities of languages. The first phase
is used for adding functionality that each language must
support and the second is used for creating instances of
languages. As an example, a tool may require certain
specialized language-specific information. It uses phase1 to
extend the @racket[drracket:language:language<%>] interface
and supply a default implementation of the interface
extension. Then, other languages that are aware of the
extension can supply non-default implementations of the
additional functionality.
Phase 1 functions:
@itemize[
@item{@racket[drracket:language:extend-language-interface]}
@item{@racket[drracket:unit:add-to-program-editor-mixin]}
]
Phase 2 functions:
@itemize[
@item{@racket[drracket:language-configuration:add-language]}
@item{@racket[drracket:language:get-default-mixin]}
@item{@racket[drracket:language:get-language-extensions]}
]
If the tool raises an error as it is loaded, invoked, or as If the tool raises an error as it is loaded, invoked, or as
the @racket[phase1] or @racket[phase2] thunks are called, the @sigelem[drracket:tool-exports^ phase1] or
@sigelem[drracket:tool-exports^ phase2] thunks are called,
DrRacket catches the error and displays a message box. Then, DrRacket catches the error and displays a message box. Then,
DrRacket continues to start up, without the tool. DrRacket continues to start up, without the tool.
@ -193,7 +158,8 @@ racket/gui
(message-box "tool example" "unit invoked"))) (message-box "tool example" "unit invoked")))
] ]
This tool just opens a few windows to indicate that it has This tool just opens a few windows to indicate that it has
been loaded and that the @racket[phase1] and @racket[phase2] been loaded and that the @sigelem[drracket:tool-exports^ phase1]
and @sigelem[drracket:tool-exports^ phase2]
functions have been called. functions have been called.
Finally, here is a more involved example. This Finally, here is a more involved example. This
@ -727,7 +693,8 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[end exact-nonnegative-integer?] [end exact-nonnegative-integer?]
[file path-string?]) [file path-string?])
void?]{ void?]{
Called to indicate that there is a @racket[require] at the location from @racket[start] to @racket[end], Called to indicate that there is a @racket[require] at the location from
@racket[start] to @racket[end],
and that it corresponds to @racket[file]. Check Syntax adds a popup menu. and that it corresponds to @racket[file]. Check Syntax adds a popup menu.
} }
@ -739,9 +706,10 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[path any/c] [path any/c]
[tag any/c]) [tag any/c])
void?]{ void?]{
Called to indicate that there is something that has documentation between the range @racket[start] and @racket[end]. The Called to indicate that there is something that has documentation between the range
documented identifier's name is given by @racket[id] and the docs are found in the html file @racket[path] at the @racket[start] and @racket[end]. The documented identifier's name is given by @racket[id]
html tag @racket[tag]. The @racket[label] argument describes the binding for use in the menu item (although it may and the docs are found in the html file @racket[path] at the html tag @racket[tag].
The @racket[label] argument describes the binding for use in the menu item (although it may
be longer than 200 characters). be longer than 200 characters).
} }
@ -781,11 +749,12 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[require-arrow? boolean?] [require-arrow? boolean?]
[name-dup? (-> string? boolean?)]) [name-dup? (-> string? boolean?)])
void?]{ void?]{
Called to indicate that there should be an arrow between the locations described by the first six arguments. Called to indicate that there should be an arrow between the locations described by the first
six arguments.
The @racket[phase-level] argument indicates the phase of the binding and the @racket[actual?] argument The @racket[phase-level] argument indicates the phase of the binding and the
indicates if the binding is a real one, or a predicted one from a syntax template (predicted bindings @racket[actual?] argument indicates if the binding is a real one, or a predicted one from
are drawn with question marks in Check Syntax). a syntax template (predicted bindings are drawn with question marks in Check Syntax).
The @racket[require-arrow?] argument indicates if this arrow points from The @racket[require-arrow?] argument indicates if this arrow points from
an imported identifier to its corresponding @racket[require]. an imported identifier to its corresponding @racket[require].
@ -800,7 +769,8 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[to-source-obj (not/c #f)] [to-source-obj (not/c #f)]
[to-pos exact-nonnegative-integer?]) [to-pos exact-nonnegative-integer?])
void?]{ void?]{
Called to indicate that there are two expressions, beginning at @racket[from-pos] and @racket[to-pos] Called to indicate that there are two expressions, beginning at
@racket[from-pos] and @racket[to-pos]
that are in tail position with respect to each other. that are in tail position with respect to each other.
} }
@defmethod[(syncheck:add-mouse-over-status [source-obj (not/c #f)] @defmethod[(syncheck:add-mouse-over-status [source-obj (not/c #f)]
@ -808,7 +778,8 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[pos-right exact-nonnegative-integer?] [pos-right exact-nonnegative-integer?]
[str string?]) [str string?])
void?]{ void?]{
Called to indicate that the message in @racket[str] should be shown when the mouse passes over the given position. Called to indicate that the message in @racket[str] should be shown when the mouse
passes over the given position.
} }
@defmethod[(syncheck:add-jump-to-definition [source-obj (not/c #f)] @defmethod[(syncheck:add-jump-to-definition [source-obj (not/c #f)]
[start exact-nonnegative-integer?] [start exact-nonnegative-integer?]
@ -818,8 +789,8 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[submods (listof symbol?)]) [submods (listof symbol?)])
void?]{ void?]{
Called to indicate that there is some identifier at the given location (named @racket[id]) that Called to indicate that there is some identifier at the given location (named @racket[id]) that
is defined in the @racket[submods] of the file @racket[filename] (where an empty list in @racket[submods] is defined in the @racket[submods] of the file @racket[filename] (where an empty list in
means that the identifier is defined at the top-level module). @racket[submods] means that the identifier is defined at the top-level module).
} }
@defmethod[(syncheck:add-definition-target [source-obj (not/c #f)] @defmethod[(syncheck:add-definition-target [source-obj (not/c #f)]
@ -835,9 +806,10 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
[style-name any/c] [style-name any/c]
[mode any/c]) [mode any/c])
void?]{ void?]{
Called to indicate that the given location should be colored according to the style @racket[style-name] when Called to indicate that the given location should be colored according to the
in @racket[mode]. The mode either indicates regular check syntax or is used indicate blame for potential contract style @racket[style-name] when in @racket[mode]. The mode either indicates regular
violations (and still experimental). check syntax or is used indicate blame for potential contract violations
(and still experimental).
} }
@defmethod[(syncheck:add-rename-menu [id symbol?] @defmethod[(syncheck:add-rename-menu [id symbol?]
[all-ids (listof (list/c (not/c #f) [all-ids (listof (list/c (not/c #f)
@ -915,7 +887,8 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
@(define-syntax-rule @(define-syntax-rule
(syncheck-method-id x ...) (syncheck-method-id x ...)
(begin @defidform[x]{Bound to an identifier created with @racket[define-local-member-name] (begin @defidform[x]{Bound to an identifier created with
@racket[define-local-member-name]
that is used in @racket[syncheck-annotations<%>].} that is used in @racket[syncheck-annotations<%>].}
...)) ...))
@syncheck-method-id[syncheck:find-source-object @syncheck-method-id[syncheck:find-source-object
@ -1058,6 +1031,59 @@ not part of DrRacket proper, but one helper library is documented here.
@racket[#f], it does not consume anything from @racket[ip]. @racket[#f], it does not consume anything from @racket[ip].
} }
@section{Signatures}
@defmodule*[(drracket/tool drscheme/tool)]
@defsignature[drracket:tool^ ()]{
This signature includes all of the names in this manual that begin
with @tt{drracket:} (except these two signatures).
}
@defsignature[drracket:tool-exports^ ()]{
The @racket[drracket:tool-exports^] signature contains two
names: @sigelem[drracket:tool-exports^ phase1] and
@sigelem[drracket:tool-exports^ phase1].
After all of the tools are loaded, all of
the @tt{phase1} functions are called and then all of the
@tt{phase2} functions are called. Certain primitives can
only be called during the dynamic extent of those calls.
This mechanism is designed to support DrRacket's
@racket[drracket:language:language<%>] extension
capabilities. That is, this mechanism enables two tools to
cooperate via new capabilities of languages. The first phase
is used for adding functionality that each language must
support and the second is used for creating instances of
languages. As an example, a tool may require certain
specialized language-specific information. It uses phase1 to
extend the @racket[drracket:language:language<%>] interface
and supply a default implementation of the interface
extension. Then, other languages that are aware of the
extension can supply non-default implementations of the
additional functionality.
@defproc[(phase1) void?]{
These functions can be called only in the dynamic extent
of a call to @sigelem[drracket:tool-exports^ phase1] (see
above for details).
@itemize[
@item{@racket[drracket:language:extend-language-interface]}
@item{@racket[drracket:unit:add-to-program-editor-mixin]}
]
}
@defproc[(phase2) void?]{
These functions can be called only in the dynamic extent
of a call to @sigelem[drracket:tool-exports^ phase2] (see
above for details).
@itemize[
@item{@racket[drracket:language-configuration:add-language]}
@item{@racket[drracket:language:get-default-mixin]}
@item{@racket[drracket:language:get-language-extensions]}
]
}
}
@include-section["get-slash-extend.scrbl"] @include-section["get-slash-extend.scrbl"]
@include-section["unit.scrbl"] @include-section["unit.scrbl"]
@include-section["language.scrbl"] @include-section["language.scrbl"]
@ -1081,13 +1107,16 @@ library; they are here for backwards compatibility and to provide links to the
(for-syntax racket/base (for-syntax racket/base
racket/unit-exptime)) racket/unit-exptime))
@(define-syntax (drs-compat stx) @(define-syntax (drs-compat stx)
(let-values ([(drs-parent drs-vars drs-var-defs-in-sig drs-stx-defs-in-sig) (signature-members #'drscheme:tool-cm^ #'here)] (let-values ([(drs-parent drs-vars drs-var-defs-in-sig drs-stx-defs-in-sig)
[(drr-parent drr-vars drr-var-defs-in-sig drr-stx-defs-in-sig) (signature-members #'drracket:tool-cm^ #'here)]) (signature-members #'drscheme:tool-cm^ #'here)]
(with-syntax ([(drs-id ...) drs-vars] [(drr-parent drr-vars drr-var-defs-in-sig drr-stx-defs-in-sig)
[(drr-id ...) drr-vars]) (signature-members #'drracket:tool-cm^ #'here)])
(with-syntax ([(drs-id ...) (append '(drscheme:tool^ drscheme:tool-exports^) drs-vars)]
[(drr-id ...) (append '(drracket:tool^ drracket:tool-exports^) drr-vars)])
#'(begin #'(begin
(defthing drs-id any/c (defthing drs-id any/c
"This is provided for backwards compatibility; new code should use " (racket drr-id) " instead.") "This is provided for backwards compatibility; new code should use "
(racket drr-id) " instead.")
...)))) ...))))
@drs-compat[] @drs-compat[]