Home

News

Download

Docs

Bugs

Contact

Tasks

Code

[Synopsis-changes] Synopsis/Synopsis/doc/Tutorial Makefile,1.8,1.9 Tutorial.xml,1.1,1.2 html.xsl,1.3,1.4 synopsis.css,1.2,1.3

Stefan Seefeld stefan at synopsis.fresco.org
Thu Nov 27 06:00:39 UTC 2003 

Update of /cvs/synopsis/Synopsis/doc/Tutorial
In directory frida:/tmp/cvs-serv13015

Modified Files:
	Makefile Tutorial.xml html.xsl synopsis.css 
Log Message:
some work on the new tutorial

Index: Makefile
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/Makefile,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -p -d -r1.8 -r1.9
--- Makefile	26 Nov 2003 06:11:51 -0000	1.8
+++ Makefile	27 Nov 2003 06:00:36 -0000	1.9
@@ -8,6 +8,7 @@ html: Tutorial.xml
 	mkdir -p $@
 	cp $(srcdir)/synopsis.css $@
 	xsltproc --novalid -o $@/ $(srcdir)/html.xsl $^
+	cp -r $(srcdir)/images $@
 
 pdf: Tutorial.pdf
 

Index: Tutorial.xml
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/Tutorial.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -p -d -r1.1 -r1.2
--- Tutorial.xml	26 Nov 2003 06:11:51 -0000	1.1
+++ Tutorial.xml	27 Nov 2003 06:00:36 -0000	1.2
@@ -19,13 +19,16 @@
 
     <section>
       <title>Inspecting code</title>
+
       <!-- Talk about the problem domain:
          code documentation, software metrics, etc. -->
+
       <para></para>
     </section>
 
     <section>
       <title>The Abstract Syntax Tree</title>
+
       <!-- Talk about source code and its representation
          inside synopsis -->
 
@@ -34,6 +37,7 @@
 
     <section>
       <title>The synopsis processing pipeline</title>
+
       <!-- Talk about AST manipulation as done 
          in synopsis -->
 
@@ -42,6 +46,7 @@
 
     <section>
       <title>The synopsis executable</title>
+
       <!-- Talk about the simplest frontend, the
          synopsis executable: basic usage, options, etc. -->
 
@@ -51,20 +56,121 @@
 
   <chapter>
     <title>Writing a processing pipeline</title>
-      <!-- When the synopsis executable isn't
+
+    <!-- When the synopsis executable isn't
            powerful enough... -->
 
     <para></para>
 
     <section>
       <title>The Processor class</title>
+
       <!-- Talk about the Processor class design -->
 
-      <para></para>
+      <para>The Processor class is at the core of the synopsis framework. It
+      is the basic building block out of which processing pipelines can be
+      composed.</para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/processor.svg" format="SVG" />
+        </imageobject>
+
+        <imageobject>
+          <imagedata fileref="images/processor.png" format="PNG" />
+        </imageobject>
+      </mediaobject>
+
+      <para>The requirement that processors can be composed into a pipeline
+      has some important consequences for its design. The process method takes
+      an ast argument, which it will operate on, and then return. It is this
+      ast that forms the backbone of the pipeline, as it is passed along from
+      one processor to the next. Additionally, parameters may be passed to the
+      processor, such as input and output.</para>
+
+      <programlisting>def process(self, ast, **keywords):
+
+  self.set_parameters(keywords)
+  self.ast = self.merge_input(ast)
+
+  # do the work here...
+
+  return self.output_and_return_ast()</programlisting>
+
+      <para>Depending on the nature of the processor, it may parse the input
+      file as source code, or simply read it in from a persistent state. In
+      any case, the result of the input reading is merged in with the existing
+      ast.</para>
+
+      <programlisting>def process(self, ast, **keywords):
+
+  self.set_parameters(keywords)
+
+  for file in self.input:
+    self.ast.merge(self.parse(file))
+
+  return self.output_and_return_ast()</programlisting>
+
+      <para>Similarly with the output: if an output parameter is defined, the
+      ast may be stored in that file before it is returned. Or, if the
+      processor is a formatter, the output parameter may indicate the file /
+      directory name to store the formatted output in.</para>
+
+      <programlisting>def process(self, ast, **keywords):
+  
+  self.set_parameters(keywords)
+  self.ast = self.merge_input(ast)
+  
+  self.format(self.output)
+  
+  return set.ast</programlisting>
+    </section>
+
+    <section>
+      <title>Composing a pipeline</title>
+
+      <para>With such a design, processors can simply be chained together:</para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/pipeline.svg" format="SVG" />
+        </imageobject>
+
+        <imageobject>
+          <imagedata fileref="images/pipeline.png" format="PNG" />
+        </imageobject>
+      </mediaobject>
+
+      <programlisting>parser = ...
+linker = ...
+formatter = ...
+ast = AST()
+formatter.process(linker.process(parser.process(ast, input=[&#39;source.hh&#39;])), output=&#39;html&#39;)</programlisting>
+
+      <para>And, to be a little bit more scalable, and to allow the use of
+      dependency tracking build tools such as make, the intermediate asts can
+      be persistet into files:</para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/pipelines.svg" format="SVG" />
+        </imageobject>
+
+        <imageobject>
+          <imagedata fileref="images/pipelines.png" format="PNG" />
+        </imageobject>
+      </mediaobject>
+
+      <programlisting>parser.process(AST(), input = [&#39;source1.hh&#39;], output = &#39;source1.syn&#39;)</programlisting>
+
+      <programlisting>parser.process(AST(), input = [&#39;source2.hh&#39;], output = &#39;source2.syn&#39;)</programlisting>
+
+      <programlisting>formatter.process(linker.process(AST(), input = [&#39;source1.syn&#39;, &#39;source2.syn&#39;]), output = &#39;html&#39;)</programlisting>
     </section>
 
     <section>
       <title>Parameters and the order of initialization</title>
+
       <!-- Talk about the Parameter setting for processors and
            other 'Parametrized' -->
 
@@ -75,6 +181,28 @@
       <title></title>
 
       <para></para>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>The AST type hierarchy</title>
+
+    <para></para>
+
+    <section>
+      <title>Recording declarations</title>
+
+      <para></para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/ast.svg" format="SVG" />
+        </imageobject>
+
+        <imageobject>
+          <imagedata fileref="images/ast.png" format="PNG" />
+        </imageobject>
+      </mediaobject>
     </section>
   </chapter>
 </book>

Index: html.xsl
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/html.xsl,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -p -d -r1.3 -r1.4
--- html.xsl	25 Nov 2003 22:08:45 -0000	1.3
+++ html.xsl	27 Nov 2003 06:00:36 -0000	1.4
@@ -6,8 +6,9 @@
 
 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.62.4/html/chunk.xsl"/>
 
-<xsl:param name="html.stylesheet" select="'synopsis-html.css'"/>
+<xsl:param name="html.stylesheet" select="'synopsis.css'"/>
 <xsl:param name="use.id.as.filename" select="1"/>
-<xsl:param name='chunk.first.sections' select="1"/>
+<xsl:param name="chunk.first.sections" select="1"/>
+<xsl:param name="use.svg" select="0"/>
 
 </xsl:stylesheet>

Index: synopsis.css
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/synopsis.css,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -p -d -r1.2 -r1.3
--- synopsis.css	16 Mar 2003 00:27:13 -0000	1.2
+++ synopsis.css	27 Nov 2003 06:00:36 -0000	1.3
@@ -1,16 +1,15 @@
-body {
-    margin-left: 0;
-    margin-right: 0;
-    margin-top: 0;
+body 
+{
+    margin: 0;
     color: #003030;
-    background: #ffffff;
-    background-image: url("bg.png");
+    background-color: #ffffff;
 }
-:link { color: #770000; text-decoration: none;}
+:link { color: #bb0000; text-decoration: none;}
 :visited { color: #770000; text-decoration: none;}
-:active { color: #800000; text-decoration: none;}
+:active { color: #ff0000; text-decoration: none;}
 
-div.page-heading {
+div.page-heading 
+{
     position:float;
     border-width:0 0 2px;
     border-color:grey;
@@ -24,6 +23,11 @@ div.page-heading {
     color:darkred;
 }
 p, dl, ul, ol { margin-left: 30px; }
-pre { margin-left: 50px; background-color:#efefef; padding:5px;}
-h2, h3 { margin-left: 10px; background-color:#efefef; padding:3px;}
+pre { margin-left: 50px; background-color:#f2f5f7; padding:5px;}
+h2, h3 { margin-left: 10px; padding:3px;}
 dt { font-weight:bold; }
+pre.programlisting 
+{
+    font-size : smaller;
+    background: #f2f5f7;
+}
\ No newline at end of file

More information about the Synopsis-changes mailing list