astview-0.1.1: data/astview-tmpl.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"/>
<title>astview - Documentation</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<script LANGUAGE="JavaScript">
function mailme(name, domain) {location.href='mailto:'+ name + '@'+ domain;}
</script>
<body>
<h1>Astview - Documentation</h1>
<p>Astview is a little desktop program to be used by people that want
to investigate syntax trees, e.g. students and lecturers in compiler
construction courses. Given a parse function <code>p :: String ->
a</code>, where <code>a</code> is a member of haskell's Data
typeclass, astview can show syntax trees in a standard tree
widget.</p>
<p>The program evolved as a case study in a) generic programming and
b) building graphical user interfaces in haskell.</p>
<ul>
<li><a href="#user-guide">User Guide</a></li>
<li><a href="#adding-parsers">Adding Custom Parsers</a></li>
<li><a href="#developer-notes">Developer Notes</a></li>
</ul>
<h2>User Guide <a name="user-guide"/> </h2>
<h3>Working with source files</h3>
<p>We tried to make the user interface as common as possible by
following the <a href="http://library.gnome.org/devel/hig-book/stable/">
GNOME human interface guidelines</a> closely. You can open a file by
giving the filename at the CLI:
<pre>astview .../path/to/mysource.hs</pre>
or simply open it via the file menu. The file's extension will
determine the parser automaticall. When there are multiple parsers for
one extension, the first one will be taken. Launching astview without
any files will enable the "lines and words"-parser. Saving works as
expected: Ctrl-S saves, Save-As has to be done via the menu. When the
file was changed, the usual star appears in the title bar, next to the
filename.</p>
<p>Cut-and-Paste functionality works as usual (Ctrl-C/P/X), allowing
to copy-paste source code to or from other programs.</p>
<p>Astview uses the same syntax-higlighting sourceview widget as
GNOME's standard editor gedit, so any language recognized there will
be highlighted by astview. For syntax-highlighting, the language is
determined by the name of the parser.</p>
<h3>Choosing Parsers</h3>
<p>As noted above, the parser is chosen automatically when opening a
file. When editing source code, one can change the parser using the
parser menu issuing an immediate reparse. Ctrl-P reparses the source
at any time.</p>
<h2>Adding Custom Parsers <a name="adding-parsers"/></h2>
<p>Astview loads the available parsers <i>at runtime</i> using the
GHC-API wrapper <a href="http://hackage.haskell.org/package/hint"
>hint</a>. In this section we show how to add custom parsers.</p>
<p>A parser is described by a 3-tuple</p>
%%EX1%%
<p>The <i>name></i> of the parser is shown in the parser menu and is
used to determine syntax highlighting. The list of extensions
<i>exts</i> is used to determine the parser when opening a file.
Finally - the magic bit of the whole tool - the buildTree function
constructs a tree of Strings (Data.Tree String) from a haskell value.
Each node of this tree denotes a constructor. This tree can be
constructed using the data2tree function from the SYB approach to
generic programming <i>(TODO: ref)</i>, which is delivered with astview.
Here is an example:</p>
%%EX2%%
<p>You can simply put such a parser into the file </p>
<pre>~/.cabal/share/astview-0.2/data/Parsers.hs</pre>
<p>which exports a list of all parsers:</p>
%%EX3%%
<p>Here, the predefined list of parsers <code>stdParserData</code> is
extended with the new haskell-parser.</p>
<p>If your Parser needs additional modules, these modules have either
be exposed to GHC's package-management, or have to exist as
source-file under the data-Directory of astview. Remember that these
modules are linked in at runtime!</p>
<p>To test your parser consider the following ghci-session:</p>
%%EX4%%
<p>If <code>drawString</code> works for your sourcecode, astview will
too, since ghci uses the parsers in interpreted mode just as astview
does.</p>
<i>describe background, especially unsafeCast, describe hin</i>
<h2>Developer Notes <a name="developer-notes"/></h2>
<p><i>Notes for Developers, Short Module descriptions, references to
haddock (include haddock !?), code conventions, history, GTK
things</i></p>