astview 0.1 → 0.1.1

raw patch · 2 files changed

+113/−4 lines, 2 files

Files

astview.cabal +3/−4
data/astview-tmpl.html +110/−0

astview.cabal view

@@ -1,14 +1,12 @@ Name:            astview-Version:         0.1+Version:         0.1.1 License:         BSD4 License-File:    LICENSE Author:                            Pascal Hof <pascal.hof@udo.edu>,                   Sebastian Menge <sebastian.menge@udo.edu> Maintainer:      Sebastian Menge <sebastian.menge@udo.edu>-Synopsis:        View abstract syntax trees for your custom -                 languages and parsers in a graphical (GTK+) -                 application+Synopsis:        A GTK-based abstract syntax tree viewer for custom languages and parsers Description:                       Astview is a graphical viewer for abstract                   syntax trees. It is implemented on the basis @@ -29,6 +27,7 @@                  data/ExprParser.hs                  data/HaskellExtParser.hs                  data/astview.html+                 data/astview-tmpl.html                  data/style.css                  data/LICENSE.unwrapped

+ data/astview-tmpl.html view

@@ -0,0 +1,110 @@+<!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 -&gt;+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>