From 1be26400cb15d234238af7958b97a79587c85f66 Mon Sep 17 00:00:00 2001 From: Eli Barzilay Date: Wed, 16 Feb 2011 15:26:11 -0500 Subject: [PATCH] Some random tidyings. --- collects/scribblings/drracket/prefs.scrbl | 327 +++--- collects/scribblings/framework/editor.scrbl | 12 +- collects/scribblings/framework/scheme.scrbl | 271 ++--- collects/scribblings/framework/text.scrbl | 20 +- collects/scribblings/raco/zo-parse.scrbl | 1031 ++++++++--------- collects/scribblings/tools/language.scrbl | 1144 ++++++++----------- collects/scribblings/tools/unit.scrbl | 5 +- 7 files changed, 1279 insertions(+), 1531 deletions(-) diff --git a/collects/scribblings/drracket/prefs.scrbl b/collects/scribblings/drracket/prefs.scrbl index d8e4cb5749..007c4fa237 100644 --- a/collects/scribblings/drracket/prefs.scrbl +++ b/collects/scribblings/drracket/prefs.scrbl @@ -9,216 +9,223 @@ The preferences dialog consists of several panels. + @section{@onscreen{Font}} - This panel controls the main font used by DrRacket. +This panel controls the main font used by DrRacket. + @section{@onscreen{Colors}} - The @onscreen{Colors} panel has several sub-panels that let you - configure the colors that DrRacket uses for the editor background, - for highlighting matching parentheses, for the online coloring for - Racket and Java modes, for @onscreen{Check Syntax}, and for the - colors of the text in the @tech{interactions window}. +The @onscreen{Colors} panel has several sub-panels that let you +configure the colors that DrRacket uses for the editor background, for +highlighting matching parentheses, for the online coloring for Racket +and Java modes, for @onscreen{Check Syntax}, and for the colors of the +text in the @tech{interactions window}. + +It also has two buttons, @onscreen{White on Black} and @onscreen{Black +on White}, which set a number of defaults for the color preferences and +change a few other aspects of DrRacket's behavior to make DrRacket's +colors look nicer for those two modes. - It also has two buttons, @onscreen{White on Black} and - @onscreen{Black on White}, which set a number of defaults for the - color preferences and change a few other aspects of DrRacket's - behavior to make DrRacket's colors look nicer for those two modes. @section{@onscreen{Editing}} - - The @onscreen{Editing} panel consists of several sub-panels: - @itemize[ +The @onscreen{Editing} panel consists of several sub-panels: - @item{@onscreen{Indenting} +@itemize[ - This panel controls which keywords DrRacket recognizes for - indenting, and how each keyword is treated.} - - @item{@onscreen{Square bracket} +@item{@onscreen{Indenting} - This panel controls which keywords DrRacket uses to determine - when to rewrite @litchar["["] to @litchar["("]. For - @racket[cond]-like keywords, the number in parenthesis indicates - how many sub-expressions are skipped before square brackets are - started. + This panel controls which keywords DrRacket recognizes for + indenting, and how each keyword is treated.} + +@item{@onscreen{Square bracket} + + This panel controls which keywords DrRacket uses to determine when + to rewrite @litchar["["] to @litchar["("]. For @racket[cond]-like + keywords, the number in parenthesis indicates how many + sub-expressions are skipped before square brackets are started. See @secref["editor"] for details on how the entries in the columns behave.} - @item{@onscreen{General} - @itemize[@item{@PrefItem{Map delete to backspace} --- If checked, the editor - treats the Delete key like the Backspace key.} +@item{@onscreen{General} - @item{@PrefItem{Wrap words in editor buffers} --- If checked, - DrRacket editors auto-wrap text lines by default. Changing this - preference affects new windows only.} + @itemize[ + @item{@PrefItem{Map delete to backspace} --- If checked, the editor + treats the Delete key like the Backspace key.} + @item{@PrefItem{Wrap words in editor buffers} --- If checked, + DrRacket editors auto-wrap text lines by default. Changing + this preference affects new windows only.} + @item{@PrefItem{Reuse existing frames when opening new files} --- + If checked, new files are opened in the same DrRacket + window, rather than creating a new DrRacket window for each + new file.} + @item{@PrefItem{Enable keybindings in menus} --- If checked, some + DrRacket menu items have keybindings. Otherwise, no menu + items have key bindings. This preference is designed for + people who are comfortable editing in Emacs and find the + standard menu keybindings interfere with the Emacs + keybindings.} + @item{@PrefItem{Treat command key as meta} --- If checked, + DrRacket will use the command key for some Emacs-like + keybindings, instead of using it for menu shortcuts. This + option is only available under Mac OS X.} + @item{@PrefItem{Color syntax interactively} --- If checked, + DrRacket colors your syntax as you type.} + @item{@PrefItem{Search using anchors} --- If checked, DrRacket's + searching mode will jump directly to the first search hit, + using an ``anchor'' to determine where to search if the + search string changes.} + @item{@PrefItem{Normalize pasted strings} --- If checked, DrRacket + adjusts strings that are pasted into the editor to avoid + confusion. For example, non-breaking spaces look just like + spaces but are not considered separators like ordinary + spaces are. If this is checked DrRacket will automatically + turn those non-breaking spaces into regular spaces. + Similarly with other (less common) characters.} + @item{@PrefItem{Enable overwrite mode keybindings} --- If checked, + DrRacket enables the insert keybinding to swap into + overwrite mode} + @item{@PrefItem{Show line numbers} --- If checked, DrRacket shows + line numbers for the file being edited in the left-hand + column}]} - @item{@PrefItem{Reuse existing frames when opening new files} --- - If checked, new files are opened in the same DrRacket window, - rather than creating a new DrRacket window for each new file.} +@item{@onscreen{Racket} - @item{@PrefItem{Enable keybindings in menus} --- If checked, some - DrRacket menu items have keybindings. Otherwise, no menu items - have key bindings. This preference is designed for people who are - comfortable editing in Emacs and find the standard menu - keybindings interfere with the Emacs keybindings.} + @itemize[ + @item{@PrefItem{Highlight between matching parens} --- If checked, + the editor marks the region between matching parenthesis + with a gray background (in color) or a stipple pattern (in + monochrome) when the blinking caret is next to a + parenthesis.} + @item{@PrefItem{Automatically adjust closing parens} --- If + checked, the editor automatically converts a typed + @litchar[")"] to @litchar["]"] to match @litchar["["], or it + converts a typed @litchar["]"] to @litchar[")"] to match + @litchar["("].} + @item{@PrefItem{Automatically adjust opening square brackets} If + checked, the editor changes typed @litchar["["] to match the + context (as explained in @secref["editor"]).} + @item{@PrefItem{Flash paren match} --- If checked, typing a + closing parenthesis, square bracket, or quotation mark + flashes the matching open parenthesis/bracket/quote.}]} - - @item{@PrefItem{Treat command key as meta} --- If checked, DrRacket will use the command key for some Emacs-like keybindings, instead of using it for menu shortcuts. This option is only available under Mac OS X.} - - @item{@PrefItem{Color syntax interactively} --- If checked, DrRacket - colors your syntax as you type.} - - @item{@PrefItem{Search using anchors} --- If checked, DrRacket's searching mode will jump directly to the first search hit, using an ``anchor'' to determine where to search if the search string changes.} - - @item{@PrefItem{Normalize pasted strings} --- If checked, DrRacket adjusts strings that are pasted into the editor to avoid confusion. For example, non-breaking spaces look just like spaces but are not considered separators like ordinary spaces are. If this is checked DrRacket will automatically turn those non-breaking spaces into regular spaces. Similarly with other (less common) characters.} - - @item{@PrefItem{Enable overwrite mode keybindings} --- If checked, DrRacket enables the insert keybinding to swap into overwrite mode} - - @item{@PrefItem{Show line numbers} --- If checked, DrRacket shows line numbers for the file being edited in the left-hand column} - - ]} +] - - - - @item{@onscreen{Racket} - - @itemize[ - - @item{@PrefItem{Highlight between matching parens} --- If checked, the - editor marks the region between matching parenthesis with a gray - background (in color) or a stipple pattern (in monochrome) when - the blinking caret is next to a parenthesis.} - - @item{@PrefItem{Automatically adjust closing parens} --- If checked, the editor - automatically converts a typed @litchar[")"] to @litchar["]"] to - match @litchar["["], or it converts a typed @litchar["]"] to - @litchar[")"] to match @litchar["("].} - - @item{@PrefItem{Automatically adjust opening square brackets} If checked, the editor changes - typed @litchar["["] to match the context (as explained in - @secref["editor"]).} - - @item{@PrefItem{Flash paren match} --- If checked, typing a closing - parenthesis, square bracket, or quotation mark flashes the - matching open parenthesis/bracket/quote.} - - ]}] - @section{@onscreen{Warnings}} - @itemize[ +@itemize[ - @item{@PrefItem{Ask before changing save format} --- If checked, - DrRacket consults the user before saving a file in non-text format - (see @secref["drracket-file-formats"]).} +@item{@PrefItem{Ask before changing save format} --- If checked, + DrRacket consults the user before saving a file in non-text format + (see @secref["drracket-file-formats"]).} - @item{@PrefItem{Verify exit} --- If checked, DrRacket consults the - user before exiting.} +@item{@PrefItem{Verify exit} --- If checked, DrRacket consults the + user before exiting.} - @item{@PrefItem{Ask about normalizing strings} --- If checked, DrRacket - consults the user before normalizing a string pasted into the editor.} - - @item{@PrefItem{Only warn once when executions and interactions are - not synchronized} --- If checked, DrRacket warns the user on the - first interaction after the definitions window, language, or - teachpack is changed without a corresponding click on - @onscreen{Run}. Otherwise, the warning appears on every - interaction.} +@item{@PrefItem{Ask about normalizing strings} --- If checked, DrRacket + consults the user before normalizing a string pasted into the + editor.} - @item{@PrefItem{Ask about clearing test coverage} --- If checked, - when test coverage annotations are displayed DrRacket prompts - about removing them. This setting only applies to the PLT - languages. DrRacket never asks in the teaching languages.} +@item{@PrefItem{Only warn once when executions and interactions are not + synchronized} --- If checked, DrRacket warns the user on the first + interaction after the definitions window, language, or teachpack + is changed without a corresponding click on @onscreen{Run}. + Otherwise, the warning appears on every interaction.} - @item{@PrefItem{Check for newer Racket versions} --- If - checked, DrRacket periodically polls a server to determine - whether a newer version of DrRacket is available.} +@item{@PrefItem{Ask about clearing test coverage} --- If checked, when + test coverage annotations are displayed DrRacket prompts about + removing them. This setting only applies to the PLT languages. + DrRacket never asks in the teaching languages.} + +@item{@PrefItem{Check for newer Racket versions} --- If checked, + DrRacket periodically polls a server to determine whether a newer + version of DrRacket is available.} + +] - ] @section{@onscreen{General}} - @itemize[ +@itemize[ - @item{@PrefItem{Number of recent items} --- controls the - length of the @onscreen{Open Recent} menu (in the @onscreen{File} - menu).} +@item{@PrefItem{Number of recent items} --- controls the length of the + @onscreen{Open Recent} menu (in the @onscreen{File} menu).} - @item{@PrefItem{Auto-save files} --- If checked, the editor - generates autosave files (see @secref["drracket-autosave-files"]) - for files that have not been saved after five minutes.} - - @item{@PrefItem{Backup files} --- If checked, when saving a file for - the first time in each editing session, the original copy of the - file is copied to a backup file in the same directory. The backup - files have the same name as the original, except that they end in - either @indexed-file{.bak} or @indexed-file{~}.} +@item{@PrefItem{Auto-save files} --- If checked, the editor generates + autosave files (see @secref["drracket-autosave-files"]) for files + that have not been saved after five minutes.} - @item{@PrefItem{Show status-line} --- If checked, DrRacket shows a - status line at the bottom of each window.} +@item{@PrefItem{Backup files} --- If checked, when saving a file for the + first time in each editing session, the original copy of the file + is copied to a backup file in the same directory. The backup + files have the same name as the original, except that they end in + either @indexed-file{.bak} or @indexed-file{~}.} - @item{@PrefItem{Count column numbers from one} --- If checked, the - status line's column counter counts from one. Otherwise, it counts - from zero.} +@item{@PrefItem{Show status-line} --- If checked, DrRacket shows a + status line at the bottom of each window.} - @item{@PrefItem{Display line numbers in buffer; not character - offsets} --- If checked, the status line shows a - @nonterm{line}:@nonterm{column} display for the current selection - rather than the character offset into the text.} +@item{@PrefItem{Count column numbers from one} --- If checked, the + status line's column counter counts from one. Otherwise, it + counts from zero.} - @item{@PrefItem{Automatically print to PostScript file} --- If - checked, printing will automatically save PostScript files. If - not, printing will use the standard printing mechanisms for your - computer.} +@item{@PrefItem{Display line numbers in buffer; not character offsets} + --- If checked, the status line shows a + @nonterm{line}:@nonterm{column} display for the current selection + rather than the character offset into the text.} - @item{@PrefItem{Open files in separate tabs (not separate windows)} - -- If checked, DrRacket will use tabs in the front-most window to - open new files, rather than creating new windows for new files.} +@item{@PrefItem{Automatically print to PostScript file} --- If checked, + printing will automatically save PostScript files. If not, + printing will use the standard printing mechanisms for your + computer.} - @item{@PrefItem{Automatically open interactions window when running - a program} -- If checked, DrRacket shows the interactions window - (if it is hidden) when a program is run.} +@item{@PrefItem{Open files in separate tabs (not separate windows)} --- + If checked, DrRacket will use tabs in the front-most window to + open new files, rather than creating new windows for new files.} - @item{@PrefItem{Automatically switch to the module language when opening a module} -- - If checked, DrRacket will recognize files that have a @tt{#lang} line - and adjust the language setting automatically.} +@item{@PrefItem{Automatically open interactions window when running a + program} --- If checked, DrRacket shows the interactions window + (if it is hidden) when a program is run.} + +@item{@PrefItem{Automatically switch to the module language when opening + a module} --- If checked, DrRacket will recognize files that have + a @tt{#lang} line and adjust the language setting automatically.} @item{@PrefItem{Put the interactions window beside the definitions - window} -- If checked, DrRacket puts the interactions window to the - right of the definitions window. By default, the interactions - window is below the definitions window.} + window} --- If checked, DrRacket puts the interactions window to + the right of the definitions window. By default, the interactions + window is below the definitions window.} -@item{@PrefItem{Always show the #lang line in the Module language} -- - If checked, the module language always shows the @hash-lang[] - line (even when it would ordinarily be scrolled off of the page), assuming - that the @hash-lang[] line is the first line in the file. -} +@item{@PrefItem{Always show the #lang line in the Module language} --- + If checked, the module language always shows the @hash-lang[] line + (even when it would ordinarily be scrolled off of the page), + assuming that the @hash-lang[] line is the first line in the file.} + +] - ] @section{@onscreen{Profiling}} - - This preference panel configures the profiling report. The band of - color shows the range of colors that profiled functions take - on. Colors near the right are used for code that is not invoked - often and colors on the right are used for code that is invoked - often. - - If you are interested in more detail at the low end, choose the - @onscreen{Square root} check box. If you are interested in more - detail at the upper end, choose the @onscreen{Square} check box. + +This preference panel configures the profiling report. The band of +color shows the range of colors that profiled functions take on. Colors +near the right are used for code that is not invoked often and colors on +the right are used for code that is invoked often. + +If you are interested in more detail at the low end, choose the +@onscreen{Square root} check box. If you are interested in more detail +at the upper end, choose the @onscreen{Square} check box. + @section{@onscreen{Browser}} - - This preferences panel allows you to configure your HTTP - proxy. Contact your system administrator for details. + +This preferences panel allows you to configure your HTTP proxy. Contact +your system administrator for details. + @section{@onscreen{Tools}} -This preference panel allows you to configure the currently active plugins. \ No newline at end of file +This preference panel allows you to configure the currently active +plugins. diff --git a/collects/scribblings/framework/editor.scrbl b/collects/scribblings/framework/editor.scrbl index 2de107b3bb..3ca6135b35 100644 --- a/collects/scribblings/framework/editor.scrbl +++ b/collects/scribblings/framework/editor.scrbl @@ -25,7 +25,7 @@ for more info about edit sequences. } - @defmethod*[(((run-after-edit-sequence (thunk (-> void)) (tag (union symbol? |#f|) |#f|)) void))]{ + @defmethod*[(((run-after-edit-sequence (thunk (-> void)) (tag (union symbol? #f) #f)) void))]{ This method is used to install callbacks that will be run after any edit-sequence completes. @@ -40,7 +40,7 @@ @method[editor:basic<%> run-after-edit-sequence]'s argument will be called. } - @defmethod*[(((get-top-level-window) (union |#f| (is-a?/c top-level-window<%>))))]{ + @defmethod*[(((get-top-level-window) (union #f (is-a?/c top-level-window<%>))))]{ Returns the @scheme[top-level-window<%>] currently associated with this buffer. @@ -53,7 +53,7 @@ Returns @scheme[#t] if the file on disk has been modified, by some other program. } - @defmethod*[(((save-file/gui-error (filename (union path |#f|) |#f|) (format (union (quote guess) (quote standard) (quote text) (quote text-force-cr) same copy) (quote same)) (show-errors? boolean |#t|)) boolean?))]{ + @defmethod*[(((save-file/gui-error (filename (union path #f) #f) (format (union (quote guess) (quote standard) (quote text) (quote text-force-cr) same copy) (quote same)) (show-errors? boolean |#t|)) boolean?))]{ This method is an alternative to @method[editor<%> save-file]. Rather than showing errors via the original stdout, it opens a dialog with an error message showing the error. @@ -63,7 +63,7 @@ no error occurred and @scheme[#f] if an error occurred. } - @defmethod*[(((load-file/gui-error (filename (union string |#f|) |#f|) (format (union (quote guess) (quote standard) (quote text) (quote text-force-cr) (quote same) (quote copy)) (quote guess)) (show-errors? boolean |#t|)) boolean?))]{ + @defmethod*[(((load-file/gui-error (filename (union string #f) #f) (format (union (quote guess) (quote standard) (quote text) (quote text-force-cr) (quote same) (quote copy)) (quote guess)) (show-errors? boolean |#t|)) boolean?))]{ This method is an alternative to @method[editor<%> load-file]. Rather than showing errors via the original stdout, it opens a dialog with an error message showing the error. @@ -347,7 +347,7 @@ The class that this mixin produces uses the same initialization arguments as its input. - @defmethod*[#:mode override (((set-filename (name string) (temp? boolean |#f|)) void))]{ + @defmethod*[#:mode override (((set-filename (name string) (temp? boolean #f)) void))]{ Updates the filename on each frame displaying this editor, for each frame that matches @@ -399,7 +399,7 @@ Returns @scheme[#t]. } - @defmethod*[(((do-autosave) (union |#f| string)))]{ + @defmethod*[(((do-autosave) (union #f string)))]{ This method is called to perform the autosaving. See also @scheme[autosave:register] diff --git a/collects/scribblings/framework/scheme.scrbl b/collects/scribblings/framework/scheme.scrbl index 270af5a7ae..c033f759f7 100644 --- a/collects/scribblings/framework/scheme.scrbl +++ b/collects/scribblings/framework/scheme.scrbl @@ -7,272 +7,251 @@ @definterface[scheme:sexp-snip<%> ()]{ @defmethod*[(((get-saved-snips) (listof snip%)))]{ This returns the list of snips hidden by the sexp snip. - } } @defclass[scheme:sexp-snip% snip% (scheme:sexp-snip<%> readable-snip<%>)]{ - - @defmethod*[#:mode override (((get-text (offset number) (num number) (flattened? boolean |#f|)) string))]{ - - Returns the concatenation of the text for all of the hidden - snips. + @defmethod*[#:mode override + (((get-text (offset number) (num number) + (flattened? boolean #f)) + string))]{ + Returns the concatenation of the text for all of the hidden snips. } @defmethod*[#:mode override (((copy) (is-a?/c scheme:sexp-snip%)))]{ - Returns a copy of this snip that includes the hidden snips. } @defmethod*[#:mode override (((write (stream-out editor-stream-out%)) void))]{ - Saves the embedded snips } - @defmethod*[#:mode override (((draw (dc dc<%>) (x real) (y real) (left real) (top real) (right real) (bottom real) (dx real) (dy real) (draw-caret symbol?)) void))]{ - + @defmethod*[#:mode override + (((draw (dc dc<%>) (x real) (y real) + (left real) (top real) (right real) (bottom real) + (dx real) (dy real) (draw-caret symbol?)) + void))]{ Draws brackets with a centered ellipses between them. } - @defmethod*[#:mode override (((get-extent (dc (is-a?/c dc<%>)) (x real) (y real) (w boxed |#f|) (h boxed |#f|) (descent boxed |#f|) (space boxed |#f|) (lspace boxed |#f|) (rspace boxed |#f|)) void))]{ - + @defmethod*[#:mode override + (((get-extent (dc (is-a?/c dc<%>)) (x real) (y real) + (w boxed #f) (h boxed #f) + (descent boxed #f) (space boxed #f) + (lspace boxed #f) (rspace boxed #f)) + void))]{ Returns a size corresponding to what this snip draws. } } @definterface[scheme:text<%> (text:basic<%> mode:host-text<%> color:text<%>)]{ Texts matching this interface support Racket mode operations. @defmethod*[(((get-limit (start exact-integer)) int))]{ - - Returns a limit for backward-matching parenthesis starting at position - @scheme[start]. - + Returns a limit for backward-matching parenthesis starting at + position @scheme[start]. } @defmethod*[(((balance-parens (key-event (instance key-event%))) void))]{ - This function is called when the user types a close parenthesis in the - @scheme[text%]. If the close parenthesis that the user inserted does not match the - corresponding open parenthesis and the @scheme['framework:fixup-parens] preference is - @scheme[#t] (see - @scheme[preferences:get]) the correct closing parenthesis is inserted. - If the @scheme['framework:paren-match] preference is - @scheme[#t] (see - @scheme[preferences:get]) the matching open parenthesis is flashed. - + This function is called when the user types a close parenthesis in + the @scheme[text%]. If the close parenthesis that the user inserted + does not match the corresponding open parenthesis and the + @scheme['framework:fixup-parens] preference is @scheme[#t] (see + @scheme[preferences:get]) the correct closing parenthesis is + inserted. If the @scheme['framework:paren-match] preference is + @scheme[#t] (see @scheme[preferences:get]) the matching open + parenthesis is flashed. } @defmethod*[(((tabify-on-return?) boolean?))]{ The result of this method is used to determine if the return key automatically tabs over to the correct position. Override it to change its behavior. - - } - @defmethod*[(((tabify (start-pos exact-integer (send this text get-start-position))) void))]{ - + @defmethod*[(((tabify (start-pos exact-integer + (send this text get-start-position))) + void))]{ Tabs the line containing by @scheme[start-pos] - } - @defmethod*[(((tabify-selection (start exact-integer) (end exact-integer)) void))]{ - + @defmethod*[(((tabify-selection (start exact-integer) (end exact-integer)) + void))]{ Sets the tabbing for the lines containing positions @scheme[start] through @scheme[end]. } @defmethod*[(((tabify-all) void))]{ - Tabs all lines. } @defmethod*[(((insert-return) void))]{ - - Inserts a newline into the buffer. If - @method[scheme:text<%> tabify-on-return?] - returns @scheme[#t], this will tabify the new line. + Inserts a newline into the buffer. If + @method[scheme:text<%> tabify-on-return?] returns @scheme[#t], this + will tabify the new line. } - @defmethod*[(((box-comment-out-selection (start-pos (or/c (symbols 'start) exact-integer?)) (end-pos (or/c (symbols 'end) exact-integer?))) void))]{ - This method comments out a selection in the text by putting it into a comment box. + @defmethod*[(((box-comment-out-selection + (start-pos (or/c (symbols 'start) exact-integer?)) + (end-pos (or/c (symbols 'end) exact-integer?))) + void))]{ + This method comments out a selection in the text by putting it into + a comment box. + Removes the region from @scheme[start-pos] to @scheme[end-pos] from + the editor and inserts a comment box with that region of text + inserted into the box. - Removes the region from @scheme[start-pos] to @scheme[end-pos] - from the editor and inserts a comment box with that region - of text inserted into the box. - - If @scheme[start-pos] is @scheme['start], the starting point of - the selection is used. If @scheme[end-pos] is @scheme['end], - the ending point of the selection is used. + If @scheme[start-pos] is @scheme['start], the starting point of the + selection is used. If @scheme[end-pos] is @scheme['end], the ending + point of the selection is used. } - @defmethod*[(((comment-out-selection (start exact-integer) (end exact-integer)) void))]{ - - Comments the lines containing positions @scheme[start] through @scheme[end] - by inserting a semi-colon at the front of each line. + @defmethod*[(((comment-out-selection (start exact-integer) + (end exact-integer)) + void))]{ + Comments the lines containing positions @scheme[start] through + @scheme[end] by inserting a semi-colon at the front of each line. } @defmethod*[(((uncomment-selection (start int) (end int)) void))]{ - - Uncomments the lines containing positions @scheme[start] through @scheme[end]. - + Uncomments the lines containing positions @scheme[start] through + @scheme[end]. } - @defmethod*[(((get-forward-sexp (start exact-integer)) (union |#f| exact-integer)))]{ - + @defmethod*[(((get-forward-sexp (start exact-integer)) + (union #f exact-integer)))]{ Returns the position of the end of next S-expression after position @scheme[start], or @scheme[#f] if there is no appropriate answer. - } @defmethod*[(((remove-sexp (start exact-integer)) void))]{ - - Forward-deletes the S-expression starting after the position @scheme[start]. - + Forward-deletes the S-expression starting after the position + @scheme[start]. } @defmethod*[(((forward-sexp (start |#t|)) exact-integer))]{ - - Moves forward over the S-expression starting at position @scheme[start]. + Moves forward over the S-expression starting at position + @scheme[start]. } @defmethod*[(((flash-forward-sexp (start-pos exact-integer)) void))]{ - Flashes the parenthesis that closes the sexpression at @scheme[start-pos]. - - } - @defmethod*[(((get-backward-sexp (start exact-integer)) (union exact-integer |#f|)))]{ - - + @defmethod*[(((get-backward-sexp (start exact-integer)) + (union exact-integer #f)))]{ Returns the position of the start of the S-expression before or containing @scheme[start], or @scheme[#f] if there is no appropriate answer. } @defmethod*[(((flash-backward-sexp (start-pos exact-integer)) void))]{ - Flashes the parenthesis that opens the sexpression at @scheme[start-pos]. - } @defmethod*[(((backward-sexp (start-pos exact-integer)) void))]{ Move the caret backwards one sexpression - Moves the caret to the beginning of the sexpression that ends at @scheme[start-pos]. } - @defmethod*[(((find-up-sexp (start-pos exact-integer)) (union |#f| exact-integer)))]{ - - Returns the position of the beginning of the next sexpression outside - the sexpression that contains @scheme[start-pos]. If there is no such - sexpression, it returns @scheme[#f]. - + @defmethod*[(((find-up-sexp (start-pos exact-integer)) + (union #f exact-integer)))]{ + Returns the position of the beginning of the next sexpression + outside the sexpression that contains @scheme[start-pos]. If there + is no such sexpression, it returns @scheme[#f]. } @defmethod*[(((up-sexp (start exact-integer)) void))]{ - - Moves backward out of the S-expression containing the position @scheme[start]. - + Moves backward out of the S-expression containing the position + @scheme[start]. } - @defmethod*[(((find-down-sexp (start-pos exact-integer)) (union |#f| exact-integer)))]{ - + @defmethod*[(((find-down-sexp (start-pos exact-integer)) + (union #f exact-integer)))]{ Returns the position of the beginning of the next sexpression inside - the sexpression that contains @scheme[start-pos]. If there is no such - sexpression, it returns @scheme[#f]. + the sexpression that contains @scheme[start-pos]. If there is no + such sexpression, it returns @scheme[#f]. } @defmethod*[(((down-sexp (start exact-integer)) void))]{ - - Moves forward into the next S-expression after the position @scheme[start]. + Moves forward into the next S-expression after the position + @scheme[start]. } @defmethod*[(((remove-parens-forward (start exact-integer)) void))]{ - Removes the parentheses from the S-expression starting after the position @scheme[start]. - } @defmethod*[(((select-forward-sexp (start exact-integer)) |#t|))]{ - Selects the next S-expression, starting at position @scheme[start]. } @defmethod*[(((select-backward-sexp (start exact-integer)) |#t|))]{ - - Selects the previous S-expression, starting at position @scheme[start]. - + Selects the previous S-expression, starting at position + @scheme[start]. } @defmethod*[(((select-up-sexp (start exact-integer)) |#t|))]{ - - Selects the region to the enclosing S-expression, starting at position @scheme[start]. - + Selects the region to the enclosing S-expression, starting at + position @scheme[start]. } @defmethod*[(((select-down-sexp (start exact-integer)) |#t|))]{ - - Selects the region to the next contained S-expression, starting at position @scheme[start]. - + Selects the region to the next contained S-expression, starting at + position @scheme[start]. } @defmethod*[(((transpose-sexp (start exact-integer)) void))]{ - - Swaps the S-expression beginning before the position @scheme[start] with - the next S-expression following @scheme[start]. + Swaps the S-expression beginning before the position @scheme[start] + with the next S-expression following @scheme[start]. } - @defmethod*[(((mark-matching-parenthesis (pos exact-positive-integer)) void))]{ - If the paren after @scheme[pos] is matched, this method - highlights it and its matching counterpart in dark green. - + @defmethod*[(((mark-matching-parenthesis (pos exact-positive-integer)) + void))]{ + If the paren after @scheme[pos] is matched, this method highlights + it and its matching counterpart in dark green. } @defmethod*[(((get-tab-size) exact-integer))]{ This method returns the current size of the tabs for scheme mode. - See also - @method[scheme:text<%> set-tab-size]. - + See also @method[scheme:text<%> set-tab-size]. } @defmethod*[(((set-tab-size (new-size exact-integer)) void))]{ - This method sets the tab size for this - text. - + This method sets the tab size for this text. } @defmethod*[(((introduce-let-ans) void))]{ - Adds a let around the current s-expression and a printf into the body - of the let. - + Adds a let around the current s-expression and a printf into the + body of the let. } @defmethod*[(((move-sexp-out) void))]{ Replaces the sexpression surrounding the insertion point with the sexpression following the insertion point. - } } -@defmixin[scheme:text-mixin (text:basic<%> mode:host-text<%> color:text<%> text:autocomplete<%>) (scheme:text<%>)]{ +@defmixin[scheme:text-mixin + (text:basic<%> mode:host-text<%> color:text<%> text:autocomplete<%>) + (scheme:text<%>)]{ This mixin adds functionality for editing Racket files. The result of this mixin uses the same initialization arguments as the mixin's argument. - @defmethod*[#:mode override (((get-word-at (pos positive-exact-integer)) string))]{ - Returns the word just before @scheme[pos], which is then used - as the prefix for auto-completion. + @defmethod*[#:mode override + (((get-word-at (pos positive-exact-integer)) string))]{ + Returns the word just before @scheme[pos], which is then used as the + prefix for auto-completion. } - - @defmethod[#:mode override (get-start-of-line [pos exact-nonnegative-integer?]) exact-nonnegative-integer?]{ - Returns the first non-whitespace character in the paragraph containing @racket[pos], - unless the position is already there, in which case it returns the first position of the paragraph. + + @defmethod[#:mode override + (get-start-of-line [pos exact-nonnegative-integer?]) + exact-nonnegative-integer?]{ + Returns the first non-whitespace character in the paragraph + containing @racket[pos], unless the position is already there, in + which case it returns the first position of the paragraph. } } @definterface[scheme:text-mode<%> ()]{ - The result of - @scheme[scheme:text-mode-mixin] - implements this interface. + The result of @scheme[scheme:text-mode-mixin] implements this + interface. } -@defmixin[scheme:text-mode-mixin (color:text-mode<%> mode:surrogate-text<%>) (scheme:text-mode<%>)]{ - This mixin adds Racket mode functionality - to the mode that it is mixed into. The resulting - mode assumes that it is only set to an editor - that is the result of - @scheme[scheme:text-mixin]. - @defmethod*[#:mode override (((on-disable-surrogate) void))]{ +@defmixin[scheme:text-mode-mixin + (color:text-mode<%> mode:surrogate-text<%>) + (scheme:text-mode<%>)]{ + This mixin adds Racket mode functionality to the mode that it is mixed + into. The resulting mode assumes that it is only set to an editor + that is the result of @scheme[scheme:text-mixin]. - Removes the scheme keymap (see also - @scheme[scheme:get-keymap]) and disables any parenthesis - highlighting in the host editor. + @defmethod*[#:mode override (((on-disable-surrogate) void))]{ + Removes the scheme keymap (see also @scheme[scheme:get-keymap]) and + disables any parenthesis highlighting in the host editor. } @defmethod*[#:mode override (((on-enable-surrogate) void))]{ - - Adds the scheme keymap (see also - @scheme[scheme:get-keymap]) and enables a parenthesis - highlighting in the host editor. - + Adds the scheme keymap (see also @scheme[scheme:get-keymap]) and + enables a parenthesis highlighting in the host editor. } } @defmixin[scheme:set-mode-mixin (scheme:text<%> mode:host-text<%>) ()]{ - This mixin creates a new instance of - @scheme[scheme:text-mode%] - and installs it, by calling its own - @method[mode:host-text<%> set-surrogate] - method with the object. + This mixin creates a new instance of @scheme[scheme:text-mode%] and + installs it, by calling its own @method[mode:host-text<%> + set-surrogate] method with the object. } -@defclass[scheme:text% (scheme:set-mode-mixin (scheme:text-mixin (text:autocomplete-mixin (mode:host-text-mixin color:text%)))) ()]{} +@defclass[scheme:text% + (scheme:set-mode-mixin + (scheme:text-mixin + (text:autocomplete-mixin (mode:host-text-mixin color:text%)))) + ()]{} @defclass[scheme:text-mode% (scheme:text-mode-mixin color:text-mode%) ()]{} @(include-previously-extracted "main-extracts.ss" #rx"^scheme:") diff --git a/collects/scribblings/framework/text.scrbl b/collects/scribblings/framework/text.scrbl index 4c59ee40bf..494983bcdf 100644 --- a/collects/scribblings/framework/text.scrbl +++ b/collects/scribblings/framework/text.scrbl @@ -107,7 +107,7 @@ moved. A snip may refuse to be moved by returning @scheme[#f] from @method[snip% release-from-owner]. } - @defmethod*[(((initial-autowrap-bitmap) (union |#f| (instance bitmap%))))]{ + @defmethod*[(((initial-autowrap-bitmap) (union #f (instance bitmap%))))]{ The result of this method is used as the initial autowrap bitmap. Override this method to change the initial @scheme[bitmap%]. See also @@ -488,13 +488,13 @@ The contents of the two editor are kept in sync, as modifications to this object happen. - @defmethod*[(((get-delegate) (union |#f| (instanceof text%))))]{ + @defmethod*[(((get-delegate) (union #f (instanceof text%))))]{ The result of this method is the @scheme[text%] object that the contents of this editor are being delegated to, or @scheme[#f], if there is none. } - @defmethod*[(((set-delegate (delegate (union |#f| (instanceof text%)))) void))]{ + @defmethod*[(((set-delegate (delegate (union #f (instanceof text%)))) void))]{ This method sets the current delegate. @@ -531,7 +531,17 @@ Creates and returns an instance of @scheme[text:1-pixel-string-snip%]. } - @defmethod*[#:mode override (((get-extent (dc (instanceof dc<%>)) (x real) (y real) (w (box (union non-negative-real-number |#f|)) |#f|) (h (box (union non-negative-real-number |#f|)) |#f|) (descent (box (union non-negative-real-number |#f|)) |#f|) (space (box (union non-negative-real-number |#f|)) |#f|) (lspace (box (union non-negative-real-number |#f|)) |#f|) (rspace (box (union non-negative-real-number |#f|)) |#f|)) void))]{ + @defmethod*[#:mode override + (((get-extent + (dc (instanceof dc<%>)) + (x real) (y real) + (w (box (union non-negative-real-number #f)) #f) + (h (box (union non-negative-real-number #f)) #f) + (descent (box (union non-negative-real-number #f)) #f) + (space (box (union non-negative-real-number #f)) #f) + (lspace (box (union non-negative-real-number #f)) #f) + (rspace (box (union non-negative-real-number #f)) #f)) + void))]{ Sets the descent, space, lspace, and rspace to zero. Sets the height to 1. Sets the width to the number of characters @@ -573,7 +583,7 @@ Creates and returns an instance of @scheme[text:1-pixel-tab-snip%]. } - @defmethod*[#:mode override (((get-extent (dc (instanceof dc<%>)) (x real) (y real) (w (box (union non-negative-real-number |#f|)) |#f|) (h (box (union non-negative-real-number |#f|)) |#f|) (descent (box (union non-negative-real-number |#f|)) |#f|) (space (box (union non-negative-real-number |#f|)) |#f|) (lspace (box (union non-negative-real-number |#f|)) |#f|) (rspace (box (union non-negative-real-number |#f|)) |#f|)) void))]{ + @defmethod*[#:mode override (((get-extent (dc (instanceof dc<%>)) (x real) (y real) (w (box (union non-negative-real-number #f)) #f) (h (box (union non-negative-real-number #f)) #f) (descent (box (union non-negative-real-number #f)) #f) (space (box (union non-negative-real-number #f)) #f) (lspace (box (union non-negative-real-number #f)) #f) (rspace (box (union non-negative-real-number #f)) #f)) void))]{ Sets the descent, space, lspace, and rspace to zero. Sets the height to 1. Sets the width to the width of tabs as diff --git a/collects/scribblings/raco/zo-parse.scrbl b/collects/scribblings/raco/zo-parse.scrbl index 937b111a1f..7ef0c62b30 100644 --- a/collects/scribblings/raco/zo-parse.scrbl +++ b/collects/scribblings/raco/zo-parse.scrbl @@ -12,662 +12,615 @@ @defmodule[compiler/zo-parse] @defproc[(zo-parse [in input-port? (current-input-port)]) compilation-top?]{ + Parses a port (typically the result of opening a @filepath{.zo} file) + containing bytecode. Beware that the structure types used to + represent the bytecode are subject to frequent changes across Racket + versons. -Parses a port (typically the result of opening a @filepath{.zo} file) -containing bytecode. Beware that the structure types used to represent the -bytecode are subject to frequent changes across Racket versons. + The parsed bytecode is returned in a @racket[compilation-top] + structure. For a compiled module, the @racket[compilation-top] + structure will contain a @racket[mod] structure. For a top-level + sequence, it will normally contain a @racket[seq] or @racket[splice] + structure with a list of top-level declarations and expressions. -The parsed bytecode is returned in a @racket[compilation-top] -structure. For a compiled module, the @racket[compilation-top] -structure will contain a @racket[mod] structure. For a top-level -sequence, it will normally contain a @racket[seq] or @racket[splice] -structure with a list of top-level declarations and expressions. + The bytecode representation of an expression is closer to an + S-expression than a traditional, flat control string. For example, an + @racket[if] form is represented by a @racket[branch] structure that + has three fields: a test expression, a ``then'' expression, and an + ``else'' expression. Similarly, a function call is represented by an + @racket[application] structure that has a list of argument + expressions. -The bytecode representation of an expression is closer to an -S-expression than a traditional, flat control string. For example, an -@racket[if] form is represented by a @racket[branch] structure that -has three fields: a test expression, a ``then'' expression, and an -``else'' expression. Similarly, a function call is represented by an -@racket[application] structure that has a list of argument -expressions. + Storage for local variables or intermediate values (such as the + arguments for a function call) is explicitly specified in terms of a + stack. For example, execution of an @racket[application] structure + reserves space on the stack for each argument result. Similarly, when + a @racket[let-one] structure (for a simple @racket[let]) is executed, + the value obtained by evaluating the right-hand side expression is + pushed onto the stack, and then the body is evaluated. Local + variables are always accessed as offsets from the current stack + position. When a function is called, its arguments are passed on the + stack. A closure is created by transferring values from the stack to + a flat closure record, and when a closure is applied, the saved values + are restored on the stack (though possibly in a different order and + likely in a more compact layout than when they were captured). -Storage for local variables or intermediate values (such as the -arguments for a function call) is explicitly specified in terms of a -stack. For example, execution of an @racket[application] structure -reserves space on the stack for each argument result. Similarly, when -a @racket[let-one] structure (for a simple @racket[let]) is executed, -the value obtained by evaluating the right-hand side expression is -pushed onto the stack, and then the body is evaluated. Local variables -are always accessed as offsets from the current stack position. When a -function is called, its arguments are passed on the stack. A closure -is created by transferring values from the stack to a flat closure -record, and when a closure is applied, the saved values are restored -on the stack (though possibly in a different order and likely in a -more compact layout than when they were captured). + When a sub-expression produces a value, then the stack pointer is + restored to its location from before evaluating the sub-expression. + For example, evaluating the right-hand size for a @racket[let-one] + structure may temporarily push values onto the stack, but the stack is + restored to its pre-@racket[let-one] position before pushing the + resulting value and continuing with the body. In addition, a tail + call resets the stack pointer to the position that follows the + enclosing function's arguments, and then the tail call continues by + pushing onto the stack the arguments for the tail-called function. -When a sub-expression produces a value, then the stack pointer is -restored to its location from before evaluating the -sub-expression. For example, evaluating the right-hand size for a -@racket[let-one] structure may temporarily push values onto the stack, -but the stack is restored to its pre-@racket[let-one] position before -pushing the resulting value and continuing with the body. In addition, -a tail call resets the stack pointer to the position that follows the -enclosing function's arguments, and then the tail call continues by -pushing onto the stack the arguments for the tail-called function. + Values for global and module-level variables are not put directly on + the stack, but instead stored in ``buckets,'' and an array of + accessible buckets is kept on the stack. When a closure body needs to + access a global variable, the closure captures and later restores the + bucket array in the same way that it captured and restores a local + variable. Mutable local variables are boxed similarly to global + variables, but individual boxes are referenced from the stack and + closures. -Values for global and module-level variables are not put directly on -the stack, but instead stored in ``buckets,'' and an array of -accessible buckets is kept on the stack. When a closure body needs to -access a global variable, the closure captures and later restores the -bucket array in the same way that it captured and restores a local -variable. Mutable local variables are boxed similarly to global -variables, but individual boxes are referenced from the stack and -closures. - -Quoted syntax (in the sense of @racket[quote-syntax]) is treated like -a global variable, because it must be instantiated for an appropriate -phase. A @racket[prefix] structure within a @racket[compilation-top] -or @racket[mod] structure indicates the list of global variables and -quoted syntax that need to be instantiated (and put into an array on -the stack) before evaluating expressions that might use them.} + Quoted syntax (in the sense of @racket[quote-syntax]) is treated like + a global variable, because it must be instantiated for an appropriate + phase. A @racket[prefix] structure within a @racket[compilation-top] + or @racket[mod] structure indicates the list of global variables and + quoted syntax that need to be instantiated (and put into an array on + the stack) before evaluating expressions that might use them.} @; -------------------------------------------------- @section{Prefix} @defstruct+[zo ()]{ -A supertype for all zo objects that can appear in compiled code.} + A supertype for all zo objects that can appear in compiled code.} -@defstruct+[(compilation-top zo) ([max-let-depth exact-nonnegative-integer?] - [prefix prefix?] - [code (or/c form? any/c)])]{ +@defstruct+[(compilation-top zo) + ([max-let-depth exact-nonnegative-integer?] + [prefix prefix?] + [code (or/c form? any/c)])]{ + Wraps compiled code. The @racket[max-let-depth] field indicates the + maximum stack depth that @racket[code] creates (not counting the + @racket[prefix] array). The @racket[prefix] field describes top-level + variables, module-level variables, and quoted syntax-objects accessed + by @racket[code]. The @racket[code] field contains executable code; + it is normally a @racket[form], but a literal value is represented as + itself.} -Wraps compiled code. The @racket[max-let-depth] field indicates the -maximum stack depth that @racket[code] creates (not counting the -@racket[prefix] array). The @racket[prefix] field describes top-level -variables, module-level variables, and quoted syntax-objects accessed -by @racket[code]. The @racket[code] field contains executable code; it -is normally a @racket[form], but a literal value is represented as -itself.} +@defstruct+[(prefix zo) + ([num-lifts exact-nonnegative-integer?] + [toplevels (listof (or/c #f symbol? global-bucket? + module-variable?))] + [stxs (listof stx?)])]{ + Represents a ``prefix'' that is pushed onto the stack to initiate + evaluation. The prefix is an array, where buckets holding the values + for @racket[toplevels] are first, then a bucket for another array if + @racket[stxs] is non-empty, then @racket[num-lifts] extra buckets for + lifted local procedures. + In @racket[toplevels], each element is one of the following: + @itemize[ + @item{a @racket[#f], which indicates a dummy variable that is used + to access the enclosing module/namespace at run time;} + @item{a symbol, which is a reference to a variable defined in the + enclosing module;} + @item{a @racket[global-bucket], which is a top-level variable (appears + only outside of modules); or} + @item{a @racket[module-variable], which indicates a variable imported + from another module.} + ] -@defstruct+[(prefix zo) ([num-lifts exact-nonnegative-integer?] - [toplevels (listof (or/c #f symbol? global-bucket? module-variable?))] - [stxs (listof stx?)])]{ - -Represents a ``prefix'' that is pushed onto the stack to initiate -evaluation. The prefix is an array, where buckets holding the values -for @racket[toplevels] are first, then a bucket for another array if -@racket[stxs] is non-empty, then @racket[num-lifts] extra buckets for -lifted local procedures. - -In @racket[toplevels], each element is one of the following: - -@itemize[ - - @item{a @racket[#f], which indicates a dummy variable that is used to - access the enclosing module/namespace at run time;} - - @item{a symbol, which is a reference to a variable defined in the - enclosing module;} - - @item{a @racket[global-bucket], which is a top-level variable - (appears only outside of modules); or} - - @item{a @racket[module-variable], which indicates a variable imported - from another module.} - -] - -The variable buckets and syntax objects that are recorded in a prefix -are accessed by @racket[toplevel] and @racket[topsyntax] expression -forms.} - + The variable buckets and syntax objects that are recorded in a prefix + are accessed by @racket[toplevel] and @racket[topsyntax] expression + forms.} @defstruct+[(global-bucket zo) ([name symbol?])]{ + Represents a top-level variable, and used only in a @racket[prefix].} -Represents a top-level variable, and used only in a @racket[prefix].} - - -@defstruct+[(module-variable zo) ([modidx module-path-index?] - [sym symbol?] - [pos exact-integer?] - [phase (or/c 0 1)])]{ - -Represents a top-level variable, and used only in a @racket[prefix]. -The @racket[pos] may record the variable's offset within its module, -or it can be @racket[-1] if the variable is always located by name. -The @racket[phase] indicates the phase level of the definition within -its module.} +@defstruct+[(module-variable zo) + ([modidx module-path-index?] + [sym symbol?] + [pos exact-integer?] + [phase (or/c 0 1)])]{ + Represents a top-level variable, and used only in a @racket[prefix]. + The @racket[pos] may record the variable's offset within its module, + or it can be @racket[-1] if the variable is always located by name. + The @racket[phase] indicates the phase level of the definition within + its module.} @defstruct+[(stx zo) ([encoded wrapped?])]{ - -Wraps a syntax object in a @racket[prefix].} + Wraps a syntax object in a @racket[prefix].} @; -------------------------------------------------- @section{Forms} @defstruct+[(form zo) ()]{ + A supertype for all forms that can appear in compiled code (including + @racket[expr]s), except for literals that are represented as + themselves.} -A supertype for all forms that can appear in compiled code (including -@racket[expr]s), except for literals that are represented as -themselves.} +@defstruct+[(def-values form) + ([ids (listof toplevel?)] + [rhs (or/c expr? seq? any/c)])]{ + Represents a @racket[define-values] form. Each element of + @racket[ids] will reference via the prefix either a top-level variable + or a local module variable. -@defstruct+[(def-values form) ([ids (listof toplevel?)] - [rhs (or/c expr? seq? any/c)])]{ - -Represents a @racket[define-values] form. Each element of @racket[ids] -will reference via the prefix either a top-level variable or a local -module variable. - -After @racket[rhs] is evaluated, the stack is restored to its depth -from before evaluating @racket[rhs].} + After @racket[rhs] is evaluated, the stack is restored to its depth + from before evaluating @racket[rhs].} @deftogether[( @defstruct+[(def-syntaxes form) ([ids (listof symbol?)] [rhs (or/c expr? seq? any/c)] [prefix prefix?] [max-let-depth exact-nonnegative-integer?])] -@defstruct+[(def-for-syntax form) ([ids (listof toplevel?)] - [rhs (or/c expr? seq? any/c)] - [prefix prefix?] - [max-let-depth exact-nonnegative-integer?])] +@defstruct+[(def-for-syntax form) + ([ids (listof toplevel?)] + [rhs (or/c expr? seq? any/c)] + [prefix prefix?] + [max-let-depth exact-nonnegative-integer?])] )]{ - -Represents a @racket[define-syntaxes] or -@racket[define-values-for-syntax] form. The @racket[rhs] expression -has its own @racket[prefix], which is pushed before evaluating -@racket[rhs]; the stack is restored after obtaining the result -values. The @racket[max-let-depth] field indicates the maximum size of -the stack that will be created by @racket[rhs] (not counting -@racket[prefix]).} + Represents a @racket[define-syntaxes] or + @racket[define-values-for-syntax] form. The @racket[rhs] expression + has its own @racket[prefix], which is pushed before evaluating + @racket[rhs]; the stack is restored after obtaining the result values. + The @racket[max-let-depth] field indicates the maximum size of the + stack that will be created by @racket[rhs] (not counting + @racket[prefix]).} @defstruct+[(req form) ([reqs stx?] [dummy toplevel?])]{ - -Represents a top-level @racket[#%require] form (but not one in a -@racket[module] form) with a sequence of specifications -@racket[reqs]. The @racket[dummy] variable is used to access to the -top-level namespace.} - + Represents a top-level @racket[#%require] form (but not one in a + @racket[module] form) with a sequence of specifications @racket[reqs]. + The @racket[dummy] variable is used to access to the top-level + namespace.} @defstruct+[(seq form) ([forms (listof (or/c form? any/c))])]{ + Represents a @racket[begin] form, either as an expression or at the + top level (though the latter is more commonly a @racket[splice] form). + When a @racket[seq] appears in an expression position, its + @racket[forms] are expressions. -Represents a @racket[begin] form, either as an expression or at the -top level (though the latter is more commonly a @racket[splice] form). -When a @racket[seq] appears in an expression position, its -@racket[forms] are expressions. - -After each form in @racket[forms] is evaluated, the stack is restored -to its depth from before evaluating the form.} - + After each form in @racket[forms] is evaluated, the stack is restored + to its depth from before evaluating the form.} @defstruct+[(splice form) ([forms (listof (or/c form? any/c))])]{ + Represents a top-level @racket[begin] form where each evaluation is + wrapped with a continuation prompt. -Represents a top-level @racket[begin] form where each evaluation is -wrapped with a continuation prompt. + After each form in @racket[forms] is evaluated, the stack is restored + to its depth from before evaluating the form.} -After each form in @racket[forms] is evaluated, the stack is restored -to its depth from before evaluating the form.} +@defstruct+[(mod form) + ([name symbol?] + [srcname symbol?] + [self-modidx module-path-index?] + [prefix prefix?] + [provides (listof (list/c (or/c exact-integer? #f) + (listof provided?) + (listof provided?)))] + [requires (listof (cons/c (or/c exact-integer? #f) + (listof module-path-index?)))] + [body (listof (or/c form? any/c))] + [syntax-body (listof (or/c def-syntaxes? def-for-syntax?))] + [unexported (list/c (listof symbol?) + (listof symbol?) + (listof symbol?))] + [max-let-depth exact-nonnegative-integer?] + [dummy toplevel?] + [lang-info (or/c #f (vector/c module-path? symbol? any/c))] + [internal-context (or/c #f #t stx?)])]{ + Represents a @racket[module] declaration. The @racket[body] forms use + @racket[prefix], rather than any prefix in place for the module + declaration itself (and each @racket[syntax-body] has its own prefix). + The @racket[provides] and @racket[requires] lists are each an + association list from phases to exports or imports. In the case of + @racket[provides], each phase maps to two lists: one for exported + variables, and another for exported syntax. In the case of + @racket[requires], each phase maps to a list of imported module paths. -@defstruct+[(mod form) ([name symbol?] - [srcname symbol?] - [self-modidx module-path-index?] - [prefix prefix?] - [provides (listof (list/c (or/c exact-integer? #f) - (listof provided?) - (listof provided?)))] - [requires (listof (cons/c (or/c exact-integer? #f) - (listof module-path-index?)))] - [body (listof (or/c form? any/c))] - [syntax-body (listof (or/c def-syntaxes? def-for-syntax?))] - [unexported (list/c (listof symbol?) (listof symbol?) - (listof symbol?))] - [max-let-depth exact-nonnegative-integer?] - [dummy toplevel?] - [lang-info (or/c #f (vector/c module-path? symbol? any/c))] - [internal-context (or/c #f #t stx?)])]{ + The @racket[body] field contains the module's run-time code, and + @racket[syntax-body] contains the module's compile-time code. After + each form in @racket[body] or @racket[syntax-body] is evaluated, the + stack is restored to its depth from before evaluating the form. -Represents a @racket[module] declaration. The @racket[body] forms use -@racket[prefix], rather than any prefix in place for the module -declaration itself (and each @racket[syntax-body] has its own -prefix). + The @racket[unexported] list contains lists of symbols for unexported + definitions that can be accessed through macro expansion. The first + list is phase-0 variables, the second is phase-0 syntax, and the last + is phase-1 variables. -The @racket[provides] and @racket[requires] lists are each an -association list from phases to exports or imports. In the case of -@racket[provides], each phase maps to two lists: one for exported -variables, and another for exported syntax. In the case of -@racket[requires], each phase maps to a list of imported module paths. + The @racket[max-let-depth] field indicates the maximum stack depth + created by @racket[body] forms (not counting the @racket[prefix] + array). The @racket[dummy] variable is used to access to the + top-level namespace. -The @racket[body] field contains the module's run-time code, and -@racket[syntax-body] contains the module's compile-time code. After -each form in @racket[body] or @racket[syntax-body] is evaluated, the -stack is restored to its depth from before evaluating the form. + The @racket[lang-info] value specifies an optional module path that + provides information about the module's implementation language. -The @racket[unexported] list contains lists of symbols for unexported -definitions that can be accessed through macro expansion. The first -list is phase-0 variables, the second is phase-0 syntax, and the last -is phase-1 variables. + The @racket[internal-module-context] value describes the lexical + context of the body of the module. This value is used by + @racket[module->namespace]. A @racket[#f] value means that the + context is unavailable or empty. A @racket[#t] value means that the + context is computed by re-importing all required modules. A + syntax-object value embeds an arbitrary lexical context.} -The @racket[max-let-depth] field indicates the maximum stack depth -created by @racket[body] forms (not counting the @racket[prefix] -array). The @racket[dummy] variable is used to access to the -top-level namespace. - -The @racket[lang-info] value specifies an optional module path that -provides information about the module's implementation language. - -The @racket[internal-module-context] value describes the lexical -context of the body of the module. This value is used by -@racket[module->namespace]. A @racket[#f] value means that the context -is unavailable or empty. A @racket[#t] value means that the context is -computed by re-importing all required modules. A syntax-object value -embeds an arbitrary lexical context.} - -@defstruct+[provided ([name symbol?] - [src (or/c module-path-index? #f)] - [src-name symbol?] - [nom-mod (or/c module-path-index? #f)] - [src-phase (or/c 0 1)] - [protected? boolean?] - [insp (or #t #f void?)])]{ - -Describes an individual provided identifier within a @racket[mod] instance.} +@defstruct+[provided + ([name symbol?] + [src (or/c module-path-index? #f)] + [src-name symbol?] + [nom-mod (or/c module-path-index? #f)] + [src-phase (or/c 0 1)] + [protected? boolean?] + [insp (or #t #f void?)])]{ + Describes an individual provided identifier within a @racket[mod] + instance.} @; -------------------------------------------------- @section{Expressions} @defstruct+[(expr form) ()]{ + A supertype for all expression forms that can appear in compiled code, + except for literals that are represented as themselves and some + @racket[seq] structures (which can appear as an expression as long as + it contains only other things that can be expressions).} -A supertype for all expression forms that can appear in compiled code, -except for literals that are represented as themselves and some @racket[seq] -structures (which can appear as an expression as long as it contains -only other things that can be expressions).} +@defstruct+[(lam expr) + ([name (or/c symbol? vector?)] + [flags (listof (or/c 'preserves-marks 'is-method 'single-result 'only-rest-arg-not-used))] + [num-params exact-nonnegative-integer?] + [param-types (listof (or/c 'val 'ref 'flonum))] + [rest? boolean?] + [closure-map (vectorof exact-nonnegative-integer?)] + [closure-types (listof (or/c 'val/ref 'flonum))] + [max-let-depth exact-nonnegative-integer?] + [body (or/c expr? seq? any/c)])]{ + Represents a @racket[lambda] form. The @racket[name] field is a name + for debugging purposes. The @racket[num-params] field indicates the + number of arguments accepted by the procedure, not counting a rest + argument; the @racket[rest?] field indicates whether extra arguments + are accepted and collected into a ``rest'' variable. The + @racket[param-types] list contains @racket[num-params] symbols + indicating the type of each argumet, either @racket['val] for a normal + argument, @racket['ref] for a boxed argument (representing a mutable + local variable), or @racket['flonum] for a flonum argument. The + @racket[closure-map] field is a vector of stack positions that are + captured when evaluating the @racket[lambda] form to create a closure. + The @racket[closure-types] field provides a corresponding list of + types, but no distinction is made between normal values and boxed + values; also, this information is redundant, since it can be inferred + by the bindings referenced though @racket[closure-map]. + When the function is called, the rest-argument list (if any) is pushed + onto the stack, then the normal arguments in reverse order, then the + closure-captured values in reverse order. Thus, when @racket[body] is + run, the first value on the stack is the first value captured by the + @racket[closure-map] array, and so on. -@defstruct+[(lam expr) ([name (or/c symbol? vector?)] - [flags (listof (or/c 'preserves-marks 'is-method 'single-result 'only-rest-arg-not-used))] - [num-params exact-nonnegative-integer?] - [param-types (listof (or/c 'val 'ref 'flonum))] - [rest? boolean?] - [closure-map (vectorof exact-nonnegative-integer?)] - [closure-types (listof (or/c 'val/ref 'flonum))] - [max-let-depth exact-nonnegative-integer?] - [body (or/c expr? seq? any/c)])]{ + The @racket[max-let-depth] field indicates the maximum stack depth + created by @racket[body] plus the arguments and closure-captured + values pushed onto the stack. The @racket[body] field is the + expression for the closure's body.} -Represents a @racket[lambda] form. The @racket[name] field is a name -for debugging purposes. The @racket[num-params] field indicates the -number of arguments accepted by the procedure, not counting a rest -argument; the @racket[rest?] field indicates whether extra arguments -are accepted and collected into a ``rest'' variable. The -@racket[param-types] list contains @racket[num-params] symbols -indicating the type of each argumet, either @racket['val] for a normal -argument, @racket['ref] for a boxed argument (representing a mutable -local variable), or @racket['flonum] for a flonum argument. The -@racket[closure-map] field is a vector of stack positions that are -captured when evaluating the @racket[lambda] form to create a closure. -The @racket[closure-types] field provides a corresponding list of -types, but no distinction is made between normal values and boxed -values; also, this information is redundant, since it can be inferred by -the bindings referenced though @racket[closure-map]. - -When the function is called, the rest-argument list (if any) is pushed -onto the stack, then the normal arguments in reverse order, then the -closure-captured values in reverse order. Thus, when @racket[body] is -run, the first value on the stack is the first value captured by the -@racket[closure-map] array, and so on. - -The @racket[max-let-depth] field indicates the maximum stack depth -created by @racket[body] plus the arguments and closure-captured -values pushed onto the stack. The @racket[body] field is the -expression for the closure's body.} - - -@defstruct+[(closure expr) ([code lam?] [gen-id symbol?])]{ - -A @racket[lambda] form with an empty closure, which is a procedure -constant. The procedure constant can appear multiple times in the -graph of expressions for bytecode, and the @racket[code] field can -be a cycle for a recursive constant procedure; the @racket[gen-id] -is different for each such constant.} +@defstruct+[(closure expr) + ([code lam?] [gen-id symbol?])]{ + A @racket[lambda] form with an empty closure, which is a procedure + constant. The procedure constant can appear multiple times in the + graph of expressions for bytecode, and the @racket[code] field can be + a cycle for a recursive constant procedure; the @racket[gen-id] is + different for each such constant.} @defstruct+[(case-lam expr) ([name (or/c symbol? vector?)] [clauses (listof lam?)])]{ + Represents a @racket[case-lambda] form as a combination of + @racket[lambda] forms that are tried (in order) based on the number of + arguments given.} -Represents a @racket[case-lambda] form as a combination of -@racket[lambda] forms that are tried (in order) based on the number of -arguments given.} +@defstruct+[(let-one expr) + ([rhs (or/c expr? seq? any/c)] + [body (or/c expr? seq? any/c)] + [flonum? boolean?] + [unused? boolean?])]{ + Pushes an uninitialized slot onto the stack, evaluates @racket[rhs] + and puts its value into the slot, and then runs @racket[body]. If + @racket[flonum?] is @racket[#t], then @racket[rhs] must produce a + flonum, and the slot must be accessed by @racket[localref]s that + expect a flonum. If @racket[unused?] is @racket[#t], then the slot + must not be used, and the value of @racket[rhs] is not actually pushed + onto the stack (but @racket[rhs] is constrained to produce a single + value). + After @racket[rhs] is evaluated, the stack is restored to its depth + from before evaluating @racket[rhs]. Note that the new slot is + created before evaluating @racket[rhs].} -@defstruct+[(let-one expr) ([rhs (or/c expr? seq? any/c)] - [body (or/c expr? seq? any/c)] - [flonum? boolean?] - [unused? boolean?])]{ +@defstruct+[(let-void expr) + ([count exact-nonnegative-integer?] + [boxes? boolean?] + [body (or/c expr? seq? any/c)])]{ + Pushes @racket[count] uninitialized slots onto the stack and then runs + @racket[body]. If @racket[boxes?] is @racket[#t], then the slots are + filled with boxes that contain @|undefined-const|.} -Pushes an uninitialized slot onto the stack, evaluates @racket[rhs] -and puts its value into the slot, and then runs @racket[body]. If -@racket[flonum?] is @racket[#t], then @racket[rhs] must produce a -flonum, and the slot must be accessed by @racket[localref]s that -expect a flonum. If @racket[unused?] is @racket[#t], then the slot -must not be used, and the value of @racket[rhs] is not actually pushed -onto the stack (but @racket[rhs] is constrained to produce a single -value). - -After @racket[rhs] is evaluated, the stack is restored to its depth -from before evaluating @racket[rhs]. Note that the new slot is created -before evaluating @racket[rhs].} - - -@defstruct+[(let-void expr) ([count exact-nonnegative-integer?] - [boxes? boolean?] - [body (or/c expr? seq? any/c)])]{ - -Pushes @racket[count] uninitialized slots onto the stack and then runs -@racket[body]. If @racket[boxes?] is @racket[#t], then the slots are -filled with boxes that contain @|undefined-const|.} - - -@defstruct+[(install-value expr) ([count exact-nonnegative-integer?] - [pos exact-nonnegative-integer?] - [boxes? boolean?] - [rhs (or/c expr? seq? any/c)] - [body (or/c expr? seq? any/c)])]{ - -Runs @racket[rhs] to obtain @racket[count] results, and installs them -into existing slots on the stack in order, skipping the first -@racket[pos] stack positions. If @racket[boxes?] is @racket[#t], then -the values are put into existing boxes in the stack slots. - -After @racket[rhs] is evaluated, the stack is restored to its depth -from before evaluating @racket[rhs].} +@defstruct+[(install-value expr) + ([count exact-nonnegative-integer?] + [pos exact-nonnegative-integer?] + [boxes? boolean?] + [rhs (or/c expr? seq? any/c)] + [body (or/c expr? seq? any/c)])]{ + Runs @racket[rhs] to obtain @racket[count] results, and installs them + into existing slots on the stack in order, skipping the first + @racket[pos] stack positions. If @racket[boxes?] is @racket[#t], then + the values are put into existing boxes in the stack slots. + After @racket[rhs] is evaluated, the stack is restored to its depth + from before evaluating @racket[rhs].} @defstruct+[(let-rec expr) ([procs (listof lam?)] [body (or/c expr? seq? any/c)])]{ + Represents a @racket[letrec] form with @racket[lambda] bindings. It + allocates a closure shell for each @racket[lambda] form in + @racket[procs], installs each onto the stack in previously allocated + slots in reverse order (so that the closure shell for the last element + of @racket[procs] is installed at stack position @racket[0]), fills + out each shell's closure (where each closure normally references some + other just-created closures, which is possible because the shells have + been installed on the stack), and then evaluates @racket[body].} -Represents a @racket[letrec] form with @racket[lambda] bindings. It -allocates a closure shell for each @racket[lambda] form in -@racket[procs], installs each onto the stack in previously -allocated slots in reverse order (so that the closure shell for the -last element of @racket[procs] is installed at stack position -@racket[0]), fills out each shell's closure (where each closure -normally references some other just-created closures, which is -possible because the shells have been installed on the stack), and -then evaluates @racket[body].} +@defstruct+[(boxenv expr) + ([pos exact-nonnegative-integer?] + [body (or/c expr? seq? any/c)])]{ + Skips @racket[pos] elements of the stack, setting the slot afterward + to a new box containing the slot's old value, and then runs + @racket[body]. This form appears when a @racket[lambda] argument is + mutated using @racket[set!] within its body; calling the function + initially pushes the value directly on the stack, and this form boxes + the value so that it can be mutated later.} +@defstruct+[(localref expr) + ([unbox? boolean?] + [pos exact-nonnegative-integer?] + [clear? boolean?] + [other-clears? boolean?] + [flonum? boolean?])]{ + Represents a local-variable reference; it accesses the value in the + stack slot after the first @racket[pos] slots. If @racket[unbox?] is + @racket[#t], the stack slot contains a box, and a value is extracted + from the box. If @racket[clear?] is @racket[#t], then after the value + is obtained, the stack slot is cleared (to avoid retaining a reference + that can prevent reclamation of the value as garbage). If + @racket[other-clears?] is @racket[#t], then some later reference to + the same stack slot may clear after reading. If @racket[flonum?] is + @racket[#t], the slot holds to a flonum value.} -@defstruct+[(boxenv expr) ([pos exact-nonnegative-integer?] - [body (or/c expr? seq? any/c)])]{ +@defstruct+[(toplevel expr) + ([depth exact-nonnegative-integer?] + [pos exact-nonnegative-integer?] + [const? boolean?] + [ready? boolean?])]{ + Represents a reference to a top-level or imported variable via the + @racket[prefix] array. The @racket[depth] field indicates the number + of stack slots to skip to reach the prefix array, and @racket[pos] is + the offset into the array. -Skips @racket[pos] elements of the stack, setting the slot afterward -to a new box containing the slot's old value, and then runs -@racket[body]. This form appears when a @racket[lambda] argument is -mutated using @racket[set!] within its body; calling the function -initially pushes the value directly on the stack, and this form boxes -the value so that it can be mutated later.} + If @racket[const?] is @racket[#t], then the variable definitely will + be defined, and its value stays constant. If @racket[ready?] is + @racket[#t], then the variable definitely will be defined (but its + value might change in the future). If @racket[const?] and + @racket[ready?] are both @racket[#f], then a check is needed to + determine whether the variable is defined.} +@defstruct+[(topsyntax expr) + ([depth exact-nonnegative-integer?] + [pos exact-nonnegative-integer?] + [midpt exact-nonnegative-integer?])]{ + Represents a reference to a quoted syntax object via the + @racket[prefix] array. The @racket[depth] field indicates the number + of stack slots to skip to reach the prefix array, and @racket[pos] is + the offset into the array. The @racket[midpt] value is used + internally for lazy calculation of syntax information.} -@defstruct+[(localref expr) ([unbox? boolean?] - [pos exact-nonnegative-integer?] - [clear? boolean?] - [other-clears? boolean?] - [flonum? boolean?])]{ +@defstruct+[(application expr) + ([rator (or/c expr? seq? any/c)] + [rands (listof (or/c expr? seq? any/c))])]{ + Represents a function call. The @racket[rator] field is the + expression for the function, and @racket[rands] are the argument + expressions. Before any of the expressions are evaluated, + @racket[(length rands)] uninitialized stack slots are created (to be + used as temporary space).} -Represents a local-variable reference; it accesses the value in the -stack slot after the first @racket[pos] slots. If @racket[unbox?] is -@racket[#t], the stack slot contains a box, and a value is extracted -from the box. If @racket[clear?] is @racket[#t], then after the value -is obtained, the stack slot is cleared (to avoid retaining a reference -that can prevent reclamation of the value as garbage). If -@racket[other-clears?] is @racket[#t], then some later reference to -the same stack slot may clear after reading. If @racket[flonum?] is -@racket[#t], the slot holds to a flonum value.} +@defstruct+[(branch expr) + ([test (or/c expr? seq? any/c)] + [then (or/c expr? seq? any/c)] + [else (or/c expr? seq? any/c)])]{ + Represents an @racket[if] form. + After @racket[test] is evaluated, the stack is restored to its depth + from before evaluating @racket[test].} -@defstruct+[(toplevel expr) ([depth exact-nonnegative-integer?] - [pos exact-nonnegative-integer?] - [const? boolean?] - [ready? boolean?])]{ +@defstruct+[(with-cont-mark expr) + ([key (or/c expr? seq? any/c)] + [val (or/c expr? seq? any/c)] + [body (or/c expr? seq? any/c)])]{ + Represents a @racket[with-continuation-mark] expression. -Represents a reference to a top-level or imported variable via the -@racket[prefix] array. The @racket[depth] field indicates the number -of stack slots to skip to reach the prefix array, and @racket[pos] is -the offset into the array. - -If @racket[const?] is @racket[#t], then the variable definitely will -be defined, and its value stays constant. If @racket[ready?] is -@racket[#t], then the variable definitely will be defined (but its -value might change in the future). If @racket[const?] and -@racket[ready?] are both @racket[#f], then a check is needed to -determine whether the variable is defined.} - - -@defstruct+[(topsyntax expr) ([depth exact-nonnegative-integer?] - [pos exact-nonnegative-integer?] - [midpt exact-nonnegative-integer?])]{ - -Represents a reference to a quoted syntax object via the -@racket[prefix] array. The @racket[depth] field indicates the number -of stack slots to skip to reach the prefix array, and @racket[pos] is -the offset into the array. The @racket[midpt] value is used internally -for lazy calculation of syntax information.} - - -@defstruct+[(application expr) ([rator (or/c expr? seq? any/c)] - [rands (listof (or/c expr? seq? any/c))])]{ - -Represents a function call. The @racket[rator] field is the expression -for the function, and @racket[rands] are the argument -expressions. Before any of the expressions are evaluated, -@racket[(length rands)] uninitialized stack slots are created (to be -used as temporary space).} - - -@defstruct+[(branch expr) ([test (or/c expr? seq? any/c)] - [then (or/c expr? seq? any/c)] - [else (or/c expr? seq? any/c)])]{ - -Represents an @racket[if] form. - -After @racket[test] is evaluated, the stack is restored to its depth -from before evaluating @racket[test].} - - -@defstruct+[(with-cont-mark expr) ([key (or/c expr? seq? any/c)] - [val (or/c expr? seq? any/c)] - [body (or/c expr? seq? any/c)])]{ - -Represents a @racket[with-continuation-mark] expression. - -After each of @racket[key] and @racket[val] is evaluated, the stack is -restored to its depth from before evaluating @racket[key] or -@racket[val].} + After each of @racket[key] and @racket[val] is evaluated, the stack is + restored to its depth from before evaluating @racket[key] or + @racket[val].} @defstruct+[(beg0 expr) ([seq (listof (or/c expr? seq? any/c))])]{ + Represents a @racket[begin0] expression. -Represents a @racket[begin0] expression. - -After each expression in @racket[seq] is evaluated, the stack is -restored to its depth from before evaluating the expression.} - + After each expression in @racket[seq] is evaluated, the stack is + restored to its depth from before evaluating the expression.} @defstruct+[(varref expr) ([toplevel toplevel?])]{ + Represents a @racket[#%variable-reference] form.} -Represents a @racket[#%variable-reference] form.} +@defstruct+[(assign expr) + ([id toplevel?] + [rhs (or/c expr? seq? any/c)] + [undef-ok? boolean?])]{ + Represents a @racket[set!] expression that assigns to a top-level or + module-level variable. (Assignments to local variables are represented + by @racket[install-value] expressions.) + + After @racket[rhs] is evaluated, the stack is restored to its depth + from before evaluating @racket[rhs].} + +@defstruct+[(apply-values expr) + ([proc (or/c expr? seq? any/c)] + [args-expr (or/c expr? seq? any/c)])]{ + Represents @racket[(call-with-values (lambda () args-expr) proc)], + which is handled specially by the run-time system.} -@defstruct+[(assign expr) ([id toplevel?] - [rhs (or/c expr? seq? any/c)] - [undef-ok? boolean?])]{ - -Represents a @racket[set!] expression that assigns to a top-level or -module-level variable. (Assignments to local variables are represented -by @racket[install-value] expressions.) - -After @racket[rhs] is evaluated, the stack is restored to its depth -from before evaluating @racket[rhs].} - - -@defstruct+[(apply-values expr) ([proc (or/c expr? seq? any/c)] - [args-expr (or/c expr? seq? any/c)])]{ - -Represents @racket[(call-with-values (lambda () args-expr) proc)], -which is handled specially by the run-time system.} - - -@defstruct+[(primval expr) ([id exact-nonnegative-integer?])]{ - -Represents a direct reference to a variable imported from the run-time -kernel.} +@defstruct+[(primval expr) + ([id exact-nonnegative-integer?])]{ + Represents a direct reference to a variable imported from the run-time + kernel.} @; -------------------------------------------------- @section{Syntax Objects} -@defstruct+[(wrapped zo) ([datum any/c] - [wraps (listof wrap?)] - [certs (or/c certificate? #f)])]{ - -Represents a syntax object, where @racket[wraps] contain the lexical -information and @racket[certs] is certificate information. When the -@racket[datum] part is itself compound, its pieces are wrapped, too.} +@defstruct+[(wrapped zo) + ([datum any/c] + [wraps (listof wrap?)] + [certs (or/c certificate? #f)])]{ + Represents a syntax object, where @racket[wraps] contain the lexical + information and @racket[certs] is certificate information. When the + @racket[datum] part is itself compound, its pieces are wrapped, too.} @defstruct+[(certificate zo) ()]{ - -A supertype for syntax certificates.} + A supertype for syntax certificates.} -@defstruct+[(certificate:nest certificate) ([nested (listof number? module-path-index? ...)] - [map (listof number? module-path-index? ...)])]{ - -A nested certificate.} +@defstruct+[(certificate:nest certificate) + ([nested (listof number? module-path-index? ...)] + [map (listof number? module-path-index? ...)])]{ + A nested certificate.} -@defstruct+[(certificate:ref certificate) ([val any/c] - [map (listof number? module-path-index? ...)])]{ - -A reference certificate.} - -@defstruct+[(certificate:plain certificate) ([map (listof number? module-path-index? ...)])]{ - -A plain certificate.} - +@defstruct+[(certificate:ref certificate) + ([val any/c] + [map (listof number? module-path-index? ...)])]{ + A reference certificate.} + +@defstruct+[(certificate:plain certificate) + ([map (listof number? module-path-index? ...)])]{ + A plain certificate.} @defstruct+[(wrap zo) ()]{ - -A supertype for lexical-information elements.} + A supertype for lexical-information elements.} @defstruct+[(top-level-rename wrap) ([flag boolean?])]{ - -A top-level renaming.} + A top-level renaming.} @defstruct+[(mark-barrier wrap) ([value symbol?])]{ - -A mark barrier.} + A mark barrier.} -@defstruct+[(free-id-info zo) ([path0 module-path-index?] - [symbol0 symbol?] - [path1 module-path-index?] - [symbol1 symbol?] - [phase0 (or/c exact-integer? #f)] - [phase1 (or/c exact-integer? #f)] - [phase2 (or/c exact-integer? #f)] - [use-current-inspector? boolean?])]{ -Information about a free identifier.} +@defstruct+[(free-id-info zo) + ([path0 module-path-index?] + [symbol0 symbol?] + [path1 module-path-index?] + [symbol1 symbol?] + [phase0 (or/c exact-integer? #f)] + [phase1 (or/c exact-integer? #f)] + [phase2 (or/c exact-integer? #f)] + [use-current-inspector? boolean?])]{ + Information about a free identifier.} -@defstruct+[(lexical-rename wrap) ([has-free-id-info? boolean?] - [bool2 boolean?] - [alist (listof - (cons/c symbol? - (or/c - symbol? - (cons/c - symbol? - (or/c - (cons/c symbol? (or/c symbol? #f)) - free-id-info?)))))])]{ - -A local-binding mapping from symbols to binding-set names.} +@defstruct+[(lexical-rename wrap) + ([has-free-id-info? boolean?] + [bool2 boolean?] + [alist + (listof + (cons/c symbol? + (or/c symbol? + (cons/c symbol? + (or/c (cons/c symbol? (or/c symbol? #f)) + free-id-info?)))))])]{ + A local-binding mapping from symbols to binding-set names.} -@defstruct+[(phase-shift wrap) ([amt exact-integer?] - [src module-path-index?] - [dest module-path-index?])]{ +@defstruct+[(phase-shift wrap) + ([amt exact-integer?] + [src module-path-index?] + [dest module-path-index?])]{ + Shifts module bindings later in the wrap set.} -Shifts module bindings later in the wrap set.} +@defstruct+[(module-rename wrap) + ([phase exact-integer?] + [kind (or/c 'marked 'normal)] + [set-id any/c] + [unmarshals (listof make-all-from-module?)] + [renames (listof module-binding?)] + [mark-renames any/c] + [plus-kern? boolean?])]{ + Represents a set of module and import bindings.} -@defstruct+[(module-rename wrap) ([phase exact-integer?] - [kind (or/c 'marked 'normal)] - [set-id any/c] - [unmarshals (listof make-all-from-module?)] - [renames (listof module-binding?)] - [mark-renames any/c] - [plus-kern? boolean?])]{ - -Represents a set of module and import bindings.} - -@defstruct+[(all-from-module zo) ([path module-path-index?] - [phase (or/c exact-integer? #f)] - [src-phase (or/c exact-integer? #f)] - [exceptions (listof (or/c symbol? number?))] - [prefix (or/c symbol? #f)])]{ - -Represents a set of simple imports from one module within a -@racket[module-rename].} +@defstruct+[(all-from-module zo) + ([path module-path-index?] + [phase (or/c exact-integer? #f)] + [src-phase (or/c exact-integer? #f)] + [exceptions (listof (or/c symbol? number?))] + [prefix (or/c symbol? #f)])]{ + Represents a set of simple imports from one module within a + @racket[module-rename].} @defstruct+[(module-binding zo) ()]{ + A supertype for module bindings.} -A supertype for module bindings.} +@defstruct+[(simple-module-binding module-binding) + ([path module-path-index?])]{ + Represents a single identifier import within a + @racket[module-rename].} -@defstruct+[(simple-module-binding module-binding) ([path module-path-index?])]{ - -Represents a single identifier import within -a @racket[module-rename].} +@defstruct+[(phased-module-binding module-binding) + ([path module-path-index?] + [phase exact-integer?] + [export-name any/c] + [nominal-path nominal-path?] + [nominal-export-name any/c])]{ + Represents a single identifier import within a + @racket[module-rename].} + +@defstruct+[(exported-nominal-module-binding module-binding) + ([path module-path-index?] + [export-name any/c] + [nominal-path nominal-path?] + [nominal-export-name any/c])]{ + Represents a single identifier import within a + @racket[module-rename].} + +@defstruct+[(nominal-module-binding module-binding) + ([path module-path-index?] + [nominal-path nominal-path?])]{ + Represents a single identifier import within a + @racket[module-rename].} + +@defstruct+[(exported-module-binding module-binding) + ([path module-path-index?] + [export-name any/c])]{ + Represents a single identifier import within a + @racket[module-rename].} -@defstruct+[(phased-module-binding module-binding) ([path module-path-index?] - [phase exact-integer?] - [export-name any/c] - [nominal-path nominal-path?] - [nominal-export-name any/c])]{ - -Represents a single identifier import within -a @racket[module-rename].} - -@defstruct+[(exported-nominal-module-binding module-binding) ([path module-path-index?] - [export-name any/c] - [nominal-path nominal-path?] - [nominal-export-name any/c])]{ - -Represents a single identifier import within -a @racket[module-rename].} - -@defstruct+[(nominal-module-binding module-binding) ([path module-path-index?] - [nominal-path nominal-path?])]{ - -Represents a single identifier import within -a @racket[module-rename].} - -@defstruct+[(exported-module-binding module-binding) ([path module-path-index?] - [export-name any/c])]{ - -Represents a single identifier import within -a @racket[module-rename].} - - @defstruct+[(nominal-path zo) ()]{ - -A supertype for nominal paths.} + A supertype for nominal paths.} -@defstruct+[(simple-nominal-path nominal-path) ([value module-path-index?])]{ +@defstruct+[(simple-nominal-path nominal-path) + ([value module-path-index?])]{ + Represents a simple nominal path.} -Represents a simple nominal path.} +@defstruct+[(imported-nominal-path nominal-path) + ([value module-path-index?] + [import-phase exact-integer?])]{ + Represents an imported nominal path.} -@defstruct+[(imported-nominal-path nominal-path) ([value module-path-index?] - [import-phase exact-integer?])]{ - -Represents an imported nominal path.} - -@defstruct+[(phased-nominal-path nominal-path) ([value module-path-index?] - [import-phase (or/c false/c exact-integer?)] - [phase exact-integer?])]{ - -Represents a phased nominal path.} +@defstruct+[(phased-nominal-path nominal-path) + ([value module-path-index?] + [import-phase (or/c false/c exact-integer?)] + [phase exact-integer?])]{ + Represents a phased nominal path.} diff --git a/collects/scribblings/tools/language.scrbl b/collects/scribblings/tools/language.scrbl index a9ca88f6c1..b8af380086 100644 --- a/collects/scribblings/tools/language.scrbl +++ b/collects/scribblings/tools/language.scrbl @@ -4,71 +4,59 @@ @definterface[drracket:language:simple-module-based-language<%> ()]{ -This interface represents the bare essentials when defining -a module-based language. Use the +This interface represents the bare essentials when defining a module-based +language. Use the @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] mixin to construct an implementation of -@scheme[drracket:language:module-based-language<%>] from an implementation of this interface. - -The class -@scheme[drracket:language:simple-module-based-language%] provides an implementation of this interface. - +@scheme[drracket:language:module-based-language<%>] from an implementation of +this interface. +The class @scheme[drracket:language:simple-module-based-language%] provides an +implementation of this interface. @defmethod[(get-language-numbers) (cons number (listof number))]{ -Returns a list of numbers, whose length must be the same as -the result of -@method[drracket:language:simple-module-based-language<%> get-language-position]. Each number indicates the sorted order of the -language positions in the language dialog. - + Returns a list of numbers, whose length must be the same as the result + of + @method[drracket:language:simple-module-based-language<%> get-language-position]. + Each number indicates the sorted order of the language positions in + the language dialog. } @defmethod[(get-language-position) (cons string (listof string))]{ -This method is the same as -@method[drracket:language:language<%> get-language-position]. - + This method is the same as + @method[drracket:language:language<%> get-language-position]. } @defmethod[(get-module) s-expression]{ -This method specifies the module that defines the language. + This method specifies the module that defines the language. -This method replaces -@method[drracket:language:language<%> front-end/complete-program] and -@method[drracket:language:language<%> front-end/interaction]. - - -The result is expected to be the -@scheme[module] (its initial require) -except as value, ie @scheme[quote]d. + This method replaces + @method[drracket:language:language<%> front-end/complete-program] and + @method[drracket:language:language<%> front-end/interaction]. + The result is expected to be the @scheme[module] (its initial require) + except as value, ie @scheme[quote]d. } @defmethod[(get-one-line-summary) string?]{ -The result of this method is shown in the language dialog -when the user selects this language. - + The result of this method is shown in the language dialog when the + user selects this language. } @defmethod[(get-reader) (->* () (any/c input-port?) (or/c syntax? eof-object?))]{ - -This method must return a procedure that is used to read -syntax from a port in the same manner as -@scheme[read-syntax]. It is used as the reader -for this language. - - - + This method must return a procedure that is used to read syntax from a + port in the same manner as @scheme[read-syntax]. It is used as the + reader for this language. }} - -@defclass[drracket:language:simple-module-based-language% object% (drracket:language:simple-module-based-language<%>)]{ - - +@defclass[drracket:language:simple-module-based-language% + object% + (drracket:language:simple-module-based-language<%>)]{ @defconstructor/make[([module s-expression] [language-position (cons string (listof string))] @@ -77,62 +65,47 @@ for this language. [documentation-reference (or/c false/c something-else) #f] [reader (->* () (any/c input-port?) (or/c syntax? eof-object?))] [language-id string?])]{ - -The init args are used as the results of the -@method[drracket:language:simple-module-based-language% get-module] and -@method[drracket:language:simple-module-based-language% get-language-position] methods - - + The init args are used as the results of the + @method[drracket:language:simple-module-based-language% get-module] + and + @method[drracket:language:simple-module-based-language% get-language-position] + methods. } -@defmethod[#:mode override +@defmethod[#:mode override (get-language-numbers) (cons number (listof number))]{ - -returns the corresponding init arg. - - + returns the corresponding init arg. } -@defmethod[#:mode override +@defmethod[#:mode override (get-language-position) s-expression]{ - -returns the corresponding init arg. - - + returns the corresponding init arg. } -@defmethod[#:mode override +@defmethod[#:mode override (get-module) (cons string (listof string))]{ - -returns the corresponding init arg. - - + returns the corresponding init arg. } -@defmethod[#:mode override +@defmethod[#:mode override (get-one-line-summary) string?]{ - -returns the corresponding initialization argument. - - + returns the corresponding initialization argument. } -@defmethod[#:mode override +@defmethod[#:mode override (get-reader) (->* () (any/c input-port?) (or/c syntax? eof-object?))]{ - -returns the corresponding init arg. - - - + returns the corresponding init arg. }} -@defmixin[drracket:language:simple-module-based-language->module-based-language-mixin (drracket:language:simple-module-based-language<%>) (drracket:language:module-based-language<%>)]{ +@defmixin[drracket:language:simple-module-based-language->module-based-language-mixin + (drracket:language:simple-module-based-language<%>) + (drracket:language:module-based-language<%>)]{ @index{drracket:language:simple-settings} This mixin uses a struct definition for its settings: @@ -148,312 +121,258 @@ This mixin uses a struct definition for its settings: (code:comment @#,t{ 'test-coverage)}) ] -The settings in this structure reflect the settings show in -the language configuration dialog for languages constructed -with this mixin. The first controls the input for the -language. The rest specify printing controls for the -language. The style @scheme['print] is the default style, -as normally used in the Racket REPL. The sharing field determines if -cycles and sharing in values are displayed when the value is -rendered. The insert newlines field determines if values in -the repl are formatted with @scheme[write] style-line -printouts, or with @scheme[pretty-print] multi-line printouts. +The settings in this structure reflect the settings show in the language +configuration dialog for languages constructed with this mixin. The +first controls the input for the language. The rest specify printing +controls for the language. The style @scheme['print] is the default +style, as normally used in the Racket REPL. The sharing field +determines if cycles and sharing in values are displayed when the value +is rendered. The insert newlines field determines if values in the repl +are formatted with @scheme[write] style-line printouts, or with +@scheme[pretty-print] multi-line printouts. - - -@defmethod[#:mode override +@defmethod[#:mode override (config-panel) (case-> (-> settings) (settings -> void))]{ + Constructs a configuration panel that lets the user configure all of + the settings for this language. -Constructs a configuration panel that lets the user -configure all of the settings for this language. - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] -for details of the -simple-settings structure, this mixin's @scheme[settings] type. + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixin's + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (default-settings) settings]{ + The defaults for the settings are + @itemize[ + @item{@scheme[case-sensitive] is @scheme[#f]} + @item{@scheme[printing-style] is @scheme['write]} + @item{@scheme[show-sharing] is @scheme[#f]} + @item{@scheme[insert-newlines] is @scheme[#t]} + ] -The defaults for the settings are -@itemize[ -@item{@scheme[case-sensitive] is @scheme[#f]} -@item{@scheme[printing-style] is @scheme['write]} -@item{@scheme[show-sharing] is @scheme[#f]} -@item{@scheme[insert-newlines] is @scheme[#t]} -] - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] for details of the -simple-settings structure, this mixins @scheme[settings] type. - - + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixins + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (default-settings?) - boolean?]{} + boolean?]{ +} -@defmethod[#:mode override +@defmethod[#:mode override (get-init-code [settings settings]) sexpression]{ - -Creates an s-expression of a module that sets the -@scheme[current-inspector], @scheme[read-case-sensitive], -and @scheme[error-value->string] parameters. Additionally, -it may load @scheme[errortrace], if debugging is enabled. - - + Creates an s-expression of a module that sets the + @scheme[current-inspector], @scheme[read-case-sensitive], and + @scheme[error-value->string] parameters. Additionally, it may load + @scheme[errortrace], if debugging is enabled. } -@defmethod[#:mode override +@defmethod[#:mode override (get-transformer-module) s-expression]{ - -Returns @scheme['mzscheme]. - - + Returns @scheme['mzscheme]. } -@defmethod[#:mode override +@defmethod[#:mode override (marshall-settings) writable]{ + Constructs a vector from the structure. -Constructs a vector from the structure. - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] -for details of the -simple-settings structure, this mixins @scheme[settings] type. - - + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixins + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (on-execute) void?]{ + Sets the case sensitivity of the language. -Sets the case sensitivity of the language. + Sets the structure inspector to a new inspector, saving the original + inspector for use during printing. -Sets the structure inspector to a new inspector, -saving the original inspector for use during printing. - -Sets the -@scheme[global-port-print-handler] -to print based on the settings structure, but without -any newlines. - -If debugging is enabled, it sets the -@scheme[current-eval] -handler to one that annotates each evaluated program with -debugging annotations. Additionally, it sets the -@scheme[error-display-handler] -to show the debugging annotations when an error is raised. - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] for details of the -simple-settings structure, this mixin's @scheme[settings] type. + Sets the @scheme[global-port-print-handler] to print based on the + settings structure, but without any newlines. + If debugging is enabled, it sets the @scheme[current-eval] handler to + one that annotates each evaluated program with debugging annotations. + Additionally, it sets the @scheme[error-display-handler] to show the + debugging annotations when an error is raised. + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixin's + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (render-value) void?]{ + Translates the value to a string, based on the settings. -Translates the value to a string, based on the settings. - -Restores a super struct inspector to render structs properly. -(See also -@method[drracket:language:simple-module-based-language->module-based-language-mixin% on-execute]) - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] for details of the -simple-settings structure, this mixin's @scheme[settings] type. - + Restores a super struct inspector to render structs properly. (See + also + @method[drracket:language:simple-module-based-language->module-based-language-mixin% on-execute]) + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixin's + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (render-value/format) void?]{ + Translates the value to a string, based on the settings. -Translates the value to a string, based on the settings. - -Restores a super struct inspector to render structs properly. -(See also -@method[drracket:language:simple-module-based-language->module-based-language-mixin% on-execute]) - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] -for details of the -simple-settings structure, this mixin's @scheme[settings] type. - + Restores a super struct inspector to render structs properly. (See + also + @method[drracket:language:simple-module-based-language->module-based-language-mixin% on-execute].) + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixin's + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (unmarshall-settings) (or/c false/c settings)]{ + Builds a settings structure from the vector, or @scheme[#f] if the + vector doesn't match the types of the structure. -Builds a settings structure from the vector, or @scheme[#f] if -the vector doesn't match the types of the structure. - -See also -@scheme[drracket:language:simple-module-based-language->module-based-language-mixin] for details of the -simple-settings structure, this mixin's @scheme[settings] type. - - - + See also + @scheme[drracket:language:simple-module-based-language->module-based-language-mixin] + for details of the simple-settings structure, this mixin's + @scheme[settings] type. } -@defmethod[#:mode override +@defmethod[#:mode override (use-mred-launcher) boolean?]{ - -Returns @scheme[#t]. - - + Returns @scheme[#t]. }} @definterface[drracket:language:module-based-language<%> ()]{ -This interface is for languages that can be implemented -with Racket @scheme[module]s. +This interface is for languages that can be implemented with Racket +@scheme[module]s. -Use the -@scheme[drracket:language:module-based-language->language-mixin] +Use the @scheme[drracket:language:module-based-language->language-mixin] mixin to construct an implementation of -@scheme[drracket:language:language<%>] from an implementation of this interface. - - +@scheme[drracket:language:language<%>] from an implementation of this +interface. @defmethod[(config-panel [parent (is-a?/c panel%)]) (case-> (-> settings) (settings -> void))]{ -This method is the same as -@method[drracket:language:language<%> config-panel]. - + This method is the same as + @method[drracket:language:language<%> config-panel]. } @defmethod[(default-settings) settings]{ -This method is the same as -@method[drracket:language:language<%> default-settings]. - + This method is the same as + @method[drracket:language:language<%> default-settings]. } @defmethod[(default-settings? [settings settings]) boolean?]{ -This method is the same as -@method[drracket:language:language<%> default-settings?]. - + This method is the same as + @method[drracket:language:language<%> default-settings?]. } @defmethod[(get-init-code [settings settings]) - sexp ]{ -Returns a module in sexpression form that is used for -creating executables. The module must provide a thunk, -called @scheme[init-code]. - -When either a stand-alone executable or a launcher is -created, the module is required, and @scheme[init-code] is -invoked. This procedure is expected to set up the -environment, based on the settings. + sexp]{ + Returns a module in sexpression form that is used for creating + executables. The module must provide a thunk, called + @scheme[init-code]. + When either a stand-alone executable or a launcher is created, the + module is required, and @scheme[init-code] is invoked. This procedure + is expected to set up the environment, based on the settings. } @defmethod[(get-language-numbers) (cons number (listof number))]{ -This method is the same as -@method[drracket:language:language<%> get-language-numbers]. - + This method is the same as + @method[drracket:language:language<%> get-language-numbers]. } @defmethod[(get-language-position) (cons string (listof string))]{ -This method is the same as -@method[drracket:language:language<%> get-language-position]. - + This method is the same as + @method[drracket:language:language<%> get-language-position]. } @defmethod[(get-module) s-expression]{ -This method specifies the module that defines the language. -It is used to initialize the user's namespace. - -The result is expected to be the -@scheme[module] (its initial require) -except as value, ie @scheme[quote]d. - -See also -@method[drracket:language:module-based-language<%> get-transformer-module]. + This method specifies the module that defines the language. It is + used to initialize the user's namespace. + The result is expected to be the @scheme[module] (its initial require) + except as value, ie @scheme[quote]d. + See also + @method[drracket:language:module-based-language<%> get-transformer-module]. } @defmethod[(get-one-line-summary) string?]{ -The result of this method is shown in the language dialog -when the user selects this language. - + The result of this method is shown in the language dialog when the + user selects this language. } @defmethod[(get-reader) (->* () (any/c input-port?) (or/c syntax? eof-object?))]{ - -This method must return a procedure that is used to read -syntax from a port in the same manner as -@scheme[read-syntax]. It is used as the reader -for this language. - - - + This method must return a procedure that is used to read syntax from a + port in the same manner as @scheme[read-syntax]. It is used as the + reader for this language. } @defmethod[(get-transformer-module) (or/c quoted-module-path #f)]{ -This method specifies the module that defines the -transformation language. It is used to initialize -the transformer portion of the user's namespace. + This method specifies the module that defines the transformation + language. It is used to initialize the transformer portion of the + user's namespace. -The result is expected to be the -@scheme[module] (its initial require) -except as value, ie @scheme[quote]d or @scheme[#f]. + The result is expected to be the @scheme[module] (its initial require) + except as value, i.e., @scheme[quote]d or @scheme[#f]. -If the result is @scheme[#f], no module is required into the -transformer part of the namespace. - -See also -@method[drracket:language:module-based-language<%> get-module]. + If the result is @scheme[#f], no module is required into the + transformer part of the namespace. + See also + @method[drracket:language:module-based-language<%> get-module]. } @defmethod[(marshall-settings [settings settings]) writable]{ -This method is the same as -@method[drracket:language:language<%> marshall-settings]. - + This method is the same as + @method[drracket:language:language<%> marshall-settings]. } @defmethod[(on-execute [settings settings] [run-on-user-thread ((-> void) -> void)]) - vod]{ -This method is the same as -@method[drracket:language:language<%> on-execute]. - + void?]{ + This method is the same as + @method[drracket:language:language<%> on-execute]. } @defmethod[(render-value [value TST] [settings settings] [port port]) void?]{ -This method is the same as -@method[drracket:language:language<%> render-value]. - + This method is the same as + @method[drracket:language:language<%> render-value]. } @defmethod[(render-value/format [value TST] @@ -461,595 +380,475 @@ This method is the same as [port port] [width (or/c number (symbols 'infinity))]) void?]{ -This method is the same as -@method[drracket:language:language<%> render-value/format]. - + This method is the same as + @method[drracket:language:language<%> render-value/format]. } @defmethod[(unmarshall-settings [input writable]) (or/c settings false/c)]{ -This method is the same as -@method[drracket:language:language<%> unmarshall-settings]. - + This method is the same as + @method[drracket:language:language<%> unmarshall-settings]. } @defmethod[(use-mred-launcher) boolean?]{ -This method is called when an executable is created to -determine if the executable should use the GRacket or the -Racket binary. - + This method is called when an executable is created to determine if + the executable should use the GRacket or the Racket binary. } @defmethod[(use-namespace-require/copy?) boolean?]{ @methspec{ - -The result of this method controls how the module is -attached to the user's namespace. If -the method returns @scheme[#t], -the Racket primitive -@scheme[namespace-require/copy] -is used and if it returns @scheme[#f], -@scheme[namespace-require] -is used. - + The result of this method controls how the module is attached to the + user's namespace. If the method returns @scheme[#t], the Racket + primitive @scheme[namespace-require/copy] is used and if it returns + @scheme[#f], @scheme[namespace-require] is used. } @methimpl{ - -Defaultly returns @scheme[#f]. - - + Defaultly returns @scheme[#f]. }}} @defmixin[drracket:language:module-based-language->language-mixin (drracket:language:module-based-language<%>) (drracket:language:language<%>)]{ - - -@defmethod[#:mode override +@defmethod[#:mode override (front-end/complete-program) (-> (or/c sexp/c syntax? eof-object?))]{ + Reads a syntax object, from @scheme[input]. Does not use + @scheme[settings]. -Reads a syntax object, from @scheme[input]. Does not use -@scheme[settings]. - -For languages that use these mixins, there is no difference -between this method and -@method[drracket:language:module-based-language->language-mixin% front-end/interaction]. - - + For languages that use these mixins, there is no difference between + this method and + @method[drracket:language:module-based-language->language-mixin% front-end/interaction]. } -@defmethod[#:mode override +@defmethod[#:mode override (front-end/interaction) (-> (or/c sexp/c syntax? eof-object?))]{ + Reads a syntax object, from @scheme[input]. Does not use + @scheme[settings]. -Reads a syntax object, from @scheme[input]. Does not use -@scheme[settings]. - -For languages that use these mixins, there is no difference -between this method and -@method[drracket:language:module-based-language->language-mixin% front-end/complete-program]. - - + For languages that use these mixins, there is no difference between + this method and + @method[drracket:language:module-based-language->language-mixin% front-end/complete-program]. } -@defmethod[#:mode override +@defmethod[#:mode override (get-language-name) string?]{ - -Returns the last element of the list returned by -@method[drracket:language:language<%> get-language-position]. - - + Returns the last element of the list returned by + @method[drracket:language:language<%> get-language-position]. } -@defmethod[#:mode override +@defmethod[#:mode override (on-execute) void?]{ + Calls the super method. -Calls the super method. - -Uses @scheme[namespace-require] -to install the result of -@method[drracket:language:module-based-language<%> get-module] and -Uses @scheme[namespace-transformer-require] -to install the result of -@method[drracket:language:module-based-language<%> get-transformer-module] into the user's namespace. - - + Uses @scheme[namespace-require] to install the result of + @method[drracket:language:module-based-language<%> get-module] and + Uses @scheme[namespace-transformer-require] to install the result of + @method[drracket:language:module-based-language<%> + get-transformer-module] into the user's namespace. }} @definterface[drracket:language:language<%> ()]{ -Implementations of this interface are languages that -DrRacket supports. - -See @secref["adding-languages"] for an overview of -adding languages to DrRacket. - +Implementations of this interface are languages that DrRacket supports. +See @secref["adding-languages"] for an overview of adding languages to +DrRacket. @defmethod[(capability-value [key symbol]) any]{ @methspec{ - -Returns the language-specific value for some capability. See -also -@scheme[drracket:language:register-capability]. - + Returns the language-specific value for some capability. See also + @scheme[drracket:language:register-capability]. } @methimpl{ - -Defaultly returns the value from: -@scheme[drracket:language:get-capability-default]. - - + Defaultly returns the value from: + @scheme[drracket:language:get-capability-default]. }} @defmethod[(config-panel [parent (is-a?/c panel%)]) (case-> (-> settings) (settings -> void))]{ -This method used by the language configuration dialog to -construct the "details" panel for this language. It accepts -a parent panel and returns a get/set function that either -updates the GUI to the argument or returns the settings for -the current GUI. - + This method used by the language configuration dialog to construct the + ``details'' panel for this language. It accepts a parent panel and + returns a get/set function that either updates the GUI to the argument + or returns the settings for the current GUI. } @defmethod[(create-executable [settings settings] [parent (or/c (is-a?/c dialog%) (is-a?/c frame%))] [program-filename string?]) void?]{ -This method creates an executable in the given language. The -@scheme[program-filename] is the name of the program to store -in the executable and @scheme[executable-filename] is the name -of a file where the executable goes. - -See also -@scheme[drracket:language:create-module-based-stand-alone-executable] and -@scheme[drracket:language:create-module-based-launcher]. + This method creates an executable in the given language. The + @scheme[program-filename] is the name of the program to store in the + executable and @scheme[executable-filename] is the name of a file + where the executable goes. + See also + @scheme[drracket:language:create-module-based-stand-alone-executable] + and @scheme[drracket:language:create-module-based-launcher]. } @defmethod[(default-settings) settings]{ -Specifies the default settings for this language. - + Specifies the default settings for this language. } @defmethod[(default-settings? [settings settings]) boolean?]{ -Return @scheme[#t] if the input settings matches the -default settings obtained via -@method[drracket:language:language<%> default-settings]. - + Return @scheme[#t] if the input settings matches the default settings + obtained via @method[drracket:language:language<%> default-settings]. } @defmethod[(first-opened [settings settings]) void?]{ + This method is called after the language is initialized, but no + program has yet been run. It is called from the user's eventspace's + main thread. -This method is called after the language is initialized, but -no program has yet been run. It is called from the user's -eventspace's main thread. + See also @method[drracket:rep:text% initialize-console]. -See also -@method[drracket:rep:text% initialize-console]. + Calling this method should not escape. DrRacket calls this method in + a @racket[parameterize] where the @racket[error-escape-handler] is set + to an escaping continuation that continues initializing the + interactions window. Thus, raising an exception will report the error + in the user's interactions window as if this were a bug in the user's + program. Escaping in any other way, however, can cause DrRacket to + fail to start up. -Calling this method should not escape. -DrRacket calls this method in a @racket[parameterize] -where the @racket[error-escape-handler] is set to an escaping -continuation that continues initializing the interactions window. -Thus, raising an exception will report the error in the user's -interactions window as if this were a bug in the user's program. -Escaping in any other way, however, can cause DrRacket to fail -to start up. + Also, IO system will deadlock if the @racket[first-opened] method does + IO on the user's IO ports, so the calling context of + @racket[first-opened] sets the @racket[current-output-port] and + @racket[current-error-port] to ports that just collect all of the IO + that happened and then replay it later in the initialization of the + user's program. -Also, IO system will deadlock if the @racket[first-opened] method -does IO on the user's IO ports, so the calling context of -@racket[first-opened] sets the @racket[current-output-port] and -@racket[current-error-port] to ports that just collect all of the -IO that happened and then replay it later in the initialization of the -user's program. - -Contrary to the method contract spec, DrRacket will also invoke this -method if it has zero arguments, passing nothing; the zero argument -version is for backwards compatibility and is not recommended. + Contrary to the method contract spec, DrRacket will also invoke this + method if it has zero arguments, passing nothing; the zero argument + version is for backwards compatibility and is not recommended. } @defmethod[(front-end/complete-program [port port] [settings settings]) (-> (or/c sexp/c syntax? eof-object?))]{ -@scheme[front-end/complete-program] method reads and parses -a program in the language. The @scheme[port] -argument contains all of the data to be read (until eof) and -the name of the @scheme[port] (obtained via @racket[object-name]) -is a value representing the source of -the program (typically an editor, but may also be a string -naming a file or some other value). -The @scheme[settings] argument is the current settings -for the language. + @scheme[front-end/complete-program] method reads and parses a program + in the language. The @scheme[port] argument contains all of the data + to be read (until eof) and the name of the @scheme[port] (obtained via + @racket[object-name]) is a value representing the source of the + program (typically an editor, but may also be a string naming a file + or some other value). The @scheme[settings] argument is the current + settings for the language. -The @scheme[front-end/complete-program] -method is expected to return a thunk that is called -repeatedly to get all of the expressions in the -program. When all expressions have been read, the thunk is -expected to return @scheme[eof]. + The @scheme[front-end/complete-program] method is expected to return a + thunk that is called repeatedly to get all of the expressions in the + program. When all expressions have been read, the thunk is expected to + return @scheme[eof]. -This method is only called for programs in the definitions -window. Notably, it is not called for -programs that are @scheme[load]ed or @scheme[eval]ed. -See -@scheme[current-load] and -@scheme[current-eval] -for those. + This method is only called for programs in the definitions + window. Notably, it is not called for programs that are + @scheme[load]ed or @scheme[eval]ed. See @scheme[current-load] and + @scheme[current-eval] for those. -This method is expected to raise an appropriate exception if -the program is malformed, eg an @scheme[exn:syntax] or -@scheme[exn:read]. + This method is expected to raise an appropriate exception if the + program is malformed, eg an @scheme[exn:syntax] or @scheme[exn:read]. -This is called on the user's thread, as is the thunk it -returns. + This is called on the user's thread, as is the thunk it returns. -Implementations of this method should not return fully -expanded expressions, since there are two forms of -expansion, using either -@scheme[expand] -or -@scheme[expand-top-level-with-compile-time-evals] -and the use of the expanded code dictates which applies. + Implementations of this method should not return fully expanded + expressions, since there are two forms of expansion, using either + @scheme[expand] or @scheme[expand-top-level-with-compile-time-evals] + and the use of the expanded code dictates which applies. -See also -@method[drracket:language:language<%> front-end/interaction] -and -@method[drracket:language:language<%> front-end/finished-complete-program]. + See also @method[drracket:language:language<%> front-end/interaction] + and + @method[drracket:language:language<%> front-end/finished-complete-program]. } @defmethod[(front-end/finished-complete-program [settings settings]) any]{ This method is called when @onscreen{Run} is clicked, but only after - @method[drracket:language:language<%> front-end/complete-program] - has been called. Specifically, - @method[drracket:language:language<%> front-end/complete-program] is - first called to get a thunk that reads from the program. That thunk - is called some number of times, eventually returning @scheme[eof], - or raising an exception. Then, this method is called. - - This method is called on the user's main eventspace thread, and without - a prompt or other control delimiter. It must return without raising an - error, or else the DrRacket window will be wedged. + @method[drracket:language:language<%> front-end/complete-program] has + been called. Specifically, @method[drracket:language:language<%> + front-end/complete-program] is first called to get a thunk that reads + from the program. That thunk is called some number of times, + eventually returning @scheme[eof], or raising an exception. Then, this + method is called. + + This method is called on the user's main eventspace thread, and + without a prompt or other control delimiter. It must return without + raising an error, or else the DrRacket window will be wedged. } @defmethod[(front-end/interaction [port input-port] [settings settings]) (-> (or/c sexp/c syntax? eof-object?))]{ -This method is just like -@method[drracket:language:language<%> front-end/complete-program] -except that it is called with program fragments, for example the -expressions entered in the interactions window. It is also used in -other contexts by tools to expand single expressions. + This method is just like + @method[drracket:language:language<%> front-end/complete-program] + except that it is called with program fragments, for example the + expressions entered in the interactions window. It is also used in + other contexts by tools to expand single expressions. -See also -@method[drracket:language:language<%> front-end/finished-complete-program]. + See also + @method[drracket:language:language<%> front-end/finished-complete-program]. } @defmethod[(get-comment-character) (values string? char?)]{ -Returns text to be used for the ``Insert Large Letters'' -menu item in DrRacket. The first result is a prefix to be -placed at the beginning of each line and the second result -is a character to be used for each pixel in the letters. - + Returns text to be used for the ``Insert Large Letters'' menu item in + DrRacket. The first result is a prefix to be placed at the beginning + of each line and the second result is a character to be used for each + pixel in the letters. } @defmethod[(get-language-name) string?]{ -Returns the name of the language, as shown in the REPL when -executing programs in the language and in the bottom left of -the DrRacket window. - + Returns the name of the language, as shown in the REPL when executing + programs in the language and in the bottom left of the DrRacket + window. } @defmethod[(get-language-numbers) (cons number (listof number))]{ -This method is used in a manner analogous to -@method[drracket:language:language<%> get-language-position]. + This method is used in a manner analogous to + @method[drracket:language:language<%> get-language-position]. -Each element in the list indicates how the names at that -point in dialog will be sorted. Names with lower numbers -appear first. If two languages are added to DrRacket with -the same strings (as given by the -@method[drracket:language:language<%> get-language-position] method) the corresponding numbers returned by this method -must be the same. Additionally, no two languages can have the -same set of numbers. + Each element in the list indicates how the names at that point in + dialog will be sorted. Names with lower numbers appear first. If two + languages are added to DrRacket with the same strings (as given by the + @method[drracket:language:language<%> get-language-position] method) + the corresponding numbers returned by this method must be the same. + Additionally, no two languages can have the same set of numbers. -(Note: this method should always return the same result, for -the same language.) + (Note: this method should always return the same result, for the same + language.) } @defmethod[(get-language-position) (cons string (listof string))]{ -This method returns a list of strings that is used to -organize this language with the other languages. Each entry -in that list is a category or subcategory of the language -and the last entry in the list is the name of the language -itself. In the language dialog, each element in the list -except for the last will be a nested turn down triangle on -the left of the dialog. The final entry will be the name -that the user can choose to select this language. Names that -are the same will be combined into the same turndown entry. + This method returns a list of strings that is used to organize this + language with the other languages. Each entry in that list is a + category or subcategory of the language and the last entry in the list + is the name of the language itself. In the language dialog, each + element in the list except for the last will be a nested turn down + triangle on the left of the dialog. The final entry will be the name + that the user can choose to select this language. Names that are the + same will be combined into the same turndown entry. -For example, if one language's position is: -@schemeblock[ -(list "General Category" "Specific Category" "My Language") -] -and another's is: -@schemeblock[ -(list "General Category" "Specific Category" "My Other Language") -] -The language dialog will collapse the first two elements in -the list, resulting in only a pair of nested turn-down -triangles, not parallel pairs of nested turn-down triangles. + For example, if one language's position is: + @schemeblock[ + (list "General Category" "Specific Category" "My Language") + ] + and another's is: + @schemeblock[ + (list "General Category" "Specific Category" "My Other Language") + ] + The language dialog will collapse the first two elements in the list, + resulting in only a pair of nested turn-down triangles, not parallel + pairs of nested turn-down triangles. } @defmethod[(get-language-url) (or/c string? false/c)]{ @methspec{ - -Returns a url for the language. - + Returns a url for the language. } @methimpl{ - -If the result isn't @scheme[#f], the name of the language is -clickable in the interactions window and clicking takes you -to this url. - - + If the result isn't @scheme[#f], the name of the language is clickable + in the interactions window and clicking takes you to this url. }} @defmethod[(get-metadata [modname symbol?] [settings any/c]) string?]{ + This method is only called when + @method[drracket:language:language<%> get-reader-module] returns an + sexp. -This method is only called when -@method[drracket:language:language<%> get-reader-module] returns an sexp. + It is expected to return a string that contains N lines, where N is + the result of calling + @method[drracket:language:language<%> get-metadata-lines]. + The string is prefixed to the buffer before the file is saved by + DrRacket, and removed from the buffer after it is opened in DrRacket. -It is expected to return a string that contains N lines, -where N is the result of calling -@method[drracket:language:language<%> get-metadata-lines]. The string is prefixed to the buffer before the file is -saved by DrRacket, and removed from the buffer after it is -opened in DrRacket. - -The string is expect to be a prefix to the file that sets up -a reader for files in this language, using @tt{#reader}. - -The @scheme[modname] argument's printed form is the same as the file's -name, but without the path, and without an extension. The -@scheme[settings] argument is the current language's settings value. - -See also -@method[drracket:language:language<%> metadata->settings], -@method[drracket:language:language<%> get-metadata-lines], and -@method[drracket:language:language<%> get-reader-module]. + The string is expect to be a prefix to the file that sets up a reader + for files in this language, using @tt{#reader}. + The @scheme[modname] argument's printed form is the same as the file's + name, but without the path, and without an extension. The + @scheme[settings] argument is the current language's settings value. + See also @method[drracket:language:language<%> metadata->settings], + @method[drracket:language:language<%> get-metadata-lines], and + @method[drracket:language:language<%> get-reader-module]. } @defmethod[(get-metadata-lines) number]{ + This method is only called when + @method[drracket:language:language<%> get-reader-module] returns an + sexp. -This method is only called when -@method[drracket:language:language<%> get-reader-module] returns an sexp. - -The result of the method is a count of the number of lines -in the strings that -@method[drracket:language:language<%> get-metadata] returns. The -@method[drracket:language:language<%> get-metadata] function does not necessarily return the same string -each time it is called (see -@method[drracket:language:language<%> metadata->settings]) but it is expected to always return a string with a fixed -number of lines, as indicated by the result of this method. - - + The result of the method is a count of the number of lines in the + strings that @method[drracket:language:language<%> get-metadata] + returns. The @method[drracket:language:language<%> get-metadata] + function does not necessarily return the same string each time it is + called (see @method[drracket:language:language<%> metadata->settings]) + but it is expected to always return a string with a fixed number of + lines, as indicated by the result of this method. } @defmethod[(get-one-line-summary) string?]{ @methspec{ - -The result of this method is shown in the language dialog -when the user selects this language. - + The result of this method is shown in the language dialog when the + user selects this language. } @methimpl{ - - - }} @defmethod[(get-reader-module) (or/c sexp-representing-a-require-spec false/c)]{ + The result of this method is used when saving or loading files. -The result of this method is used when saving or loading files. - -If the result is a sexp, saved files get a prefix inserted -at the beginning (the prefix is determined by calling -@method[drracket:language:language<%> get-metadata]). When the file is then loaded, DrRacket recognizes this -prefix and sets the language back to match the saved file. - -See also -@method[drracket:language:language<%> metadata->settings], -@method[drracket:language:language<%> get-metadata-lines], and -@method[drracket:language:language<%> get-metadata]. - + If the result is a sexp, saved files get a prefix inserted at the + beginning (the prefix is determined by calling + @method[drracket:language:language<%> get-metadata]). When the file + is then loaded, DrRacket recognizes this prefix and sets the language + back to match the saved file. + See also @method[drracket:language:language<%> metadata->settings], + @method[drracket:language:language<%> get-metadata-lines], and + @method[drracket:language:language<%> get-metadata]. } @defmethod[(get-style-delta) (or/c #f (is-a?/c style-delta%) (listof (list/c (is-a?/c style-delta%) number? number?)))]{ -The style delta that this method returns is used in the -language dialog and the DrRacket REPL when the language's -name is printed. + The style delta that this method returns is used in the language + dialog and the DrRacket REPL when the language's name is printed. -When it is @scheme[#f], no styling is used. - -If the result is a list, each element is expected to be a -list of three items, a style-delta, and two numbers. The -style delta will be applied to the corresponding portion of -the name. + When it is @scheme[#f], no styling is used. + If the result is a list, each element is expected to be a list of + three items, a style-delta, and two numbers. The style delta will be + applied to the corresponding portion of the name. } @defmethod[(extra-repl-information [settings settings] [port output-port?]) void?]{ - This method is called on the DrRacket eventspace main thread to insert extra - information into the REPL to reflect the state of the program. - - It is used, for example, to print out the ``Teachpack'' lines in the HtDP languages. -} - + This method is called on the DrRacket eventspace main thread to insert + extra information into the REPL to reflect the state of the program. + + It is used, for example, to print out the ``Teachpack'' lines in the + HtDP languages. +} - @defmethod[(marshall-settings [settings settings]) writable]{ -Translates an instance of the settings type into a Racket -object that can be written out to disk. - + Translates an instance of the settings type into a Racket object that + can be written out to disk. } @defmethod[(metadata->settings [metadata string?]) settings]{ + This method is only called when + @method[drracket:language:language<%> get-reader-module] returns an + sexp. -This method is only called when -@method[drracket:language:language<%> get-reader-module] returns an sexp. - -When a file is opened in DrRacket, if this language's -@method[drracket:language:language<%> get-reader-module] returns an sexp, the prefix of the file -(the first N lines, where N is the number -returned by -@method[drracket:language:language<%> get-metadata-lines]) is scanned for @scheme["#reader"] followed by the -result of -@method[drracket:language:language<%> get-reader-module]. If that pattern is found, the language is set to this language. -Also, the entire prefix is passed, as a string, -to this method which returns a @scheme[settings] value, used as -the settings for this language. - - + When a file is opened in DrRacket, if this language's + @method[drracket:language:language<%> get-reader-module] returns an + sexp, the prefix of the file (the first N lines, where N is the number + returned by @method[drracket:language:language<%> get-metadata-lines]) + is scanned for @scheme["#reader"] followed by the result of + @method[drracket:language:language<%> get-reader-module]. If that + pattern is found, the language is set to this language. Also, the + entire prefix is passed, as a string, to this method which returns a + @scheme[settings] value, used as the settings for this language. } @defmethod[(on-execute [settings settings] [run-on-user-thread ((-> any) -> any)]) any]{ -The @scheme[on-execute] method is called on DrRacket's -eventspace's main thread before any evaluation happens -when the Run button is clicked. It is also called when -a new DrRacket tab (or window) is created to initialize -the empty interactions window. + The @scheme[on-execute] method is called on DrRacket's eventspace's + main thread before any evaluation happens when the Run button is + clicked. It is also called when a new DrRacket tab (or window) is + created to initialize the empty interactions window. -Use this method to initialize Racket's -@secref[#:doc '(lib "scribblings/reference/reference.scrbl") "parameters"] -for the user. When -this function is called, the user's thread has already been -created, as has its custodian. These parameters have been -changed from the defaults in Racket: -@itemize[ -@item{@scheme[current-custodian] is set to a new custodian.} -@item{@scheme[current-namespace] has been set to a newly - created empty namespace.This namespace has the following modules - copied (with @scheme[namespace-attach-module]) - from DrRacket's original namespace: + Use this method to initialize Racket's + @secref[#:doc '(lib "scribblings/reference/reference.scrbl") "parameters"] + for the user. When this function is called, the user's thread has + already been created, as has its custodian. These parameters have + been changed from the defaults in Racket: @itemize[ - @item{@scheme['mzscheme]} - @item{@scheme['mred]} - ]} -@item{ - @scheme[read-curly-brace-as-paren] - is @scheme[#t],} -@item{ - @scheme[read-square-bracket-as-paren] - is @scheme[#t],} -@item{The - @scheme[port-write-handler] - and - @scheme[port-display-handler] - have been set to procedures - that call - @scheme[pretty-print] - and - @scheme[pretty-display] instead - of - @scheme[write] and - @scheme[display]. When - @scheme[pretty-print] and - @scheme[pretty-display] are - called by these parameters, the - @scheme[pretty-print-columns] parameter is set to - @scheme['infinity], so the output looks just like - @scheme[write] and - @scheme[display]. This is done so that - special scheme values can be displayed as snips.} -@item{The - @scheme[current-print-covert-hook] is to a - procedure so that @scheme[snip%]s are just returned - directly to be inserted into the interactions - @scheme[text%] object.} -@item{The output and input ports are set to point to the - interactions window with these parameters: - @scheme[current-input-port], - @scheme[current-output-port], and - @scheme[current-error-port].} -@item{The -@scheme[event-dispatch-handler] is set so that DrRacket can perform some initial setup and - close down around the user's code.} -@item{The - @scheme[current-directory] and - @scheme[current-load-relative-directory] - are set to the directory where the definitions file is - saved, or if it isn't saved, to the initial directory where - DrRacket started up.} -@item{The snip-class-list, returned by -@scheme[get-the-snip-class-list] is initialized with all of the snipclasses in DrRacket's eventspace's snip-class-list.} + @item{@scheme[current-custodian] is set to a new custodian.} + @item{@scheme[current-namespace] has been set to a newly created empty + namespace. This namespace has the following modules copied (with + @scheme[namespace-attach-module]) from DrRacket's original + namespace: + @itemize[ + @item{@scheme['mzscheme]} + @item{@scheme['mred]} + ]} + @item{@scheme[read-curly-brace-as-paren] is @scheme[#t],} + @item{@scheme[read-square-bracket-as-paren] is @scheme[#t],} + @item{The @scheme[port-write-handler] and @scheme[port-display-handler] + have been set to procedures that call @scheme[pretty-print] and + @scheme[pretty-display] instead of @scheme[write] and + @scheme[display]. When @scheme[pretty-print] and + @scheme[pretty-display] are called by these parameters, the + @scheme[pretty-print-columns] parameter is set to + @scheme['infinity], so the output looks just like @scheme[write] and + @scheme[display]. This is done so that special scheme values can be + displayed as snips.} + @item{The @scheme[current-print-covert-hook] is to a procedure so that + @scheme[snip%]s are just returned directly to be inserted into the + interactions @scheme[text%] object.} + @item{The output and input ports are set to point to the interactions + window with these parameters: @scheme[current-input-port], + @scheme[current-output-port], and @scheme[current-error-port].} + @item{The @scheme[event-dispatch-handler] is set so that DrRacket can + perform some initial setup and close down around the user's code.} + @item{The @scheme[current-directory] and + @scheme[current-load-relative-directory] are set to the directory + where the definitions file is saved, or if it isn't saved, to the + initial directory where DrRacket started up.} + @item{The snip-class-list, returned by @scheme[get-the-snip-class-list] + is initialized with all of the snipclasses in DrRacket's + eventspace's snip-class-list.} + @item{The @scheme[error-print-source-location] parameter is set to + @scheme[#f] and the @scheme[error-display-handler] is set to a + handler that creates an error message from the exception record, + with font and color information and inserts that error message into + the definitions window.} + ] -@item{ -The -@scheme[error-print-source-location] -parameter is set to @scheme[#f] and the -@scheme[error-display-handler] -is set to a handler that creates an error message from the -exception record, with font and color information and inserts -that error message into the definitions window.} + The @scheme[run-on-user-thread] arguments accepts thunks and runs them + on the user's eventspace's main thread. The output ports are not yet + functioning, so print outs should be directed to the original DrRacket + output port, if necessary. -] - -The @scheme[run-on-user-thread] arguments accepts thunks and -runs them on the user's eventspace's main thread. -The output ports are not yet -functioning, so print outs should be directed to the -original DrRacket output port, if necessary. - -This thunk is wrapped in a @racket[with-handlers] that -catches all exceptions matching @racket[exn:fail?] and -then prints out the exception message to the original -output port of the DrRacket process. + This thunk is wrapped in a @racket[with-handlers] that catches all + exceptions matching @racket[exn:fail?] and then prints out the + exception message to the original output port of the DrRacket process. } @defmethod[(order-manuals [manuals (listof bytes?)]) (values (listof bytes?) boolean?)]{ -Returns a sublist of its input, that specifies the manuals -(and their order) to search in. The boolean result indicates -if doc.txt files should be searched. - + Returns a sublist of its input, that specifies the manuals + (and their order) to search in. The boolean result indicates + if @tt{doc.txt} files should be searched. } @defmethod[(render-value [value TST] [settings settings] [port port]) void?]{ -This method is just like -@method[drracket:language:language<%> render-value/format] except that it is expected to put the entire value on a -single line with no newline after the value. - + This method is just like + @method[drracket:language:language<%> render-value/format] except that + it is expected to put the entire value on a single line with no + newline after the value. } @defmethod[(render-value/format [value TST] @@ -1057,24 +856,21 @@ single line with no newline after the value. [port port] [width (or/c number (symbols 'infinity))]) void?]{ -This method is used to print values into a port, for display -to a user. The final argument is a maximum width to use (in -characters) when formatting the value. + This method is used to print values into a port, for display to a + user. The final argument is a maximum width to use (in characters) + when formatting the value. -This method is expected to format the value by inserting -newlines in appropriate places and is expected to render a -newline after the value. - -See also -@method[drracket:language:language<%> render-value]. + This method is expected to format the value by inserting newlines in + appropriate places and is expected to render a newline after the + value. + See also @method[drracket:language:language<%> render-value]. } @defmethod[(unmarshall-settings [input writable]) (or/c settings false/c)]{ -Translates a Racket value into a settings, returning -@scheme[#f] if that is not possible. - + Translates a Racket value into a settings, returning @scheme[#f] if + that is not possible. }} @(tools-include "language") diff --git a/collects/scribblings/tools/unit.scrbl b/collects/scribblings/tools/unit.scrbl index 50aded5152..03b2805cb2 100644 --- a/collects/scribblings/tools/unit.scrbl +++ b/collects/scribblings/tools/unit.scrbl @@ -713,7 +713,10 @@ that the button is not referenced by this frame and thus can be gc'd. } -@defclass[drracket:unit:definitions-text% (drracket:rep:drs-bindings-keymap-mixin (drracket:unit:program-editor-mixin (scheme:text-mixin text:info%))) (drracket:unit:definitions-text<%>)]{ +@defclass[drracket:unit:definitions-text% + (drracket:rep:drs-bindings-keymap-mixin + (drracket:unit:program-editor-mixin (scheme:text-mixin text:info%))) + (drracket:unit:definitions-text<%>)]{ @defconstructor[()]{ Passes all arguments to @scheme[super-init].