Syntax-Browser: Graphical Syntax Display

_Syntax-Browser: Graphical Syntax Display_
==========================================

By Ryan Culpepper (ryanc at ccs dot neu dot edu)

Keywords: _syntax_, _syntax-browser_, _hygiene_, _lexical context_


Introduction
============

There are two common ways to view syntax objects. One is to call
syntax-object->datum and inspect the underlying S-expression with all
additional information removed. The other is to use DrScheme's
built-in syntax viewer, which shows additional properties of the
syntax object. However, neither solution shows the different lexical
contexts of subterms and identifiers within the syntax object. This
library graphically displays this information, critical for debugging
macro expansions.

Syntax-Browser API
==================

There is a single public module in the syntax-browser collection.

_syntax-browser.ss_
-------------------

Use the following require form to use the library:

> (require (planet "syntax-browser.ss" ("ryanc" "syntax-browser.plt" 1)))

This provides two procedures:

> (browse-syntax syntax) -> void

Creates a frame with the given syntax object shown. More information
on using the GUI is available below.

> (browse-syntaxes list-of-syntax) -> void

Like browse-syntax, but shows multiple syntax objects in the same
frame. The primary coloring partition is shared between the two,
showing the relationships between subterms in different syntax
objects.

The User Interface
==================

The syntax-browser contains a frame with a few controls and an editor
canvas for displaying syntax objects.

The *primary partitioning* always assigns two syntax subterms the same
color if they have the same lexical context (in the sense of
bound-identifier=?). In the absence of unhygienic macros, this means
that subterms with the same foreground color were either present in
the original pre-expansion syntax or generated by the same macro
transcription step.

The drop-down list allows the user to select a *secondary
partitionin*, applied only to identifiers. When the user clicks on a
syntax subterm, that term is highlighted in grey, and all terms in the
same equivalence class as the selected term are highlighted in blue.

The "De-select all" button clears the selection highlighting.

The Secondary Partitionings
---------------------------

* bound-identifier=?
* module-identifier=?
* module-or-top-identifier=?

See the documentation for these predicates in the MzScheme manual.

* symbolic-identifer=?

Two identifiers are symbolic-identifier=? if discarding all lexical
context information yields the same symbol.

* same marks

Two identifiers have the same marks iff using both as the first
argument to datum->syntax-object on the same symbol yields two
bound-identifier=? identifiers.

In other words, they are almost bound-identifier=?, but they may have
different symbolic names.

* same source module

The bindings of the two identifiers come from definitions in the same
module.

* same nominal module

The bindings of the two identifiers were imported into the current
context by requiring the same module.

Notes and Limitations
=====================

The same syntax object may appear multiple times as a subterm of a
syntax object (ie, there are values x such that (eq? (stx-car x)
(stx-cdr x)) is true). The syntax-browser thus identifies the
graphical representations of the same terms--clicking on one
occurrence will highlight *both* in grey.

The syntax-browser does not yet display syntax properties like the
DrScheme syntax viewer does.