Oberon to Markdown

This is the twelfth post in the Mostly Oberon series. Mostly Oberon documents my exploration of the Oberon Language, Oberon System and the various rabbit holes I will inevitably fall into.

A nice feature of Oberon

Oberon source code has a very nice property in that anything after the closing end statement is ignored by the compiler. This makes it a nice place to write documentation, program notes and other ideas.

I’ve gotten in the habit of writing up program docs and notes there. When I prep to make a web document I used to copy the source file, doing a cut and paste to re-order the module code to the bottom of the document. I’d follow that with adding headers and code fences. Not hard but tedious. Of course if I changed the source code I’d also have to do another cut and paste edit. This program, ObnToMd.Mod automates that process.

Program Documentation

  2. PROGRAM
  4.   ObnToMd
  6. FUNCTION
  8.   This is a simple program that reads Oberon modules
  9.   from standard in and re-renders that to standard output
  10.   such that it is suitable to process with Pandoc or other
  11.   text processing system.
  13. EXAMPLE
  15.   Read the source for this program and render a file
  16.   called "blog-post.md". Use Pandoc to render HTML.
  18.     ObnToMd <ObnToMd.Mod > blog-post.md
  19.     pandoc -s --metadata title="Blog Post" \
  20.         blog-post.md >blog-post.html
  22. BUGS
  24.   It uses a naive line analysis to identify the module
  25.   name and then the end of module statement. Might be
  26.   tripped up by comments containing the same strings.
  27.   The temporary file created is called "o2m.tmp" and
  28.   this filename could potentially conflict with another
  29.   file.

Source code for ObnToMd.Mod

  2. (* ObnToMd.Mod - an simple filter process for reading
  3. an Oberon-07 module source file and rendering a markdown
  4. friendly output suitable for piping into Pandoc. The
  5. filter reads from standard input and writes to standard
  6. output and makes use of a temp file name o2m.tmp which
  7. it removes after successful rendering.
  9. @Author R. S. Doiel, <rsdoiel@gmail.com>
  10. copyright (c) 2020, all rights reserved.
  11. Released under the BSD 2-clause license
  12. See: https://opensource.org/licenses/BSD-2-Clause
  13. *)
  14. MODULE ObnToMd;
  15.   IMPORT In, Out, Files, Strings;
  17. CONST
  18.   MAXLENGTH = 1024;
  19.   LF = CHR(10);
  21. VAR
  22.   endOfLine : ARRAY 2 OF CHAR;
  24. (*
  25.  * Helper methods
  26.  *)
  27. PROCEDURE GenTempName(prefix, suffix : ARRAY OF CHAR; VAR name : ARRAY OF CHAR);
  28. BEGIN
  29.   name := "";
  30.   Strings.Append(prefix, name);
  31.   Strings.Append(".", name);
  32.   Strings.Append(suffix, name);
  33. END GenTempName;
  35. PROCEDURE GenTempFile(name : ARRAY OF CHAR; VAR r : Files.Rider; VAR f : Files.File);
  36. BEGIN
  37.   f := Files.New(name);
  38.   IF f = NIL THEN
  39.     Out.String("ERROR: can't create ");Out.String(name);Out.Ln();
  40.     ASSERT(FALSE);
  41.   END;
  42.   Files.Register(f);
  43.   Files.Set(r, f, 0);
  44. END GenTempFile;
  47. PROCEDURE StartsWith(target, source : ARRAY OF CHAR) : BOOLEAN;
  48.   VAR res : BOOLEAN;
  49. BEGIN
  50.   IF Strings.Pos(target, source, 0) > -1 THEN
  51.     res := TRUE;
  52.   ELSE
  53.     res := FALSE;
  54.   END;
  55.   RETURN res
  56. END StartsWith;
  58. PROCEDURE ClearString(VAR s : ARRAY OF CHAR);
  59.   VAR i : INTEGER;
  60. BEGIN
  61.   FOR i := 0 TO LEN(s) - 1 DO
  62.     s[i] := 0X;
  63.   END;
  64. END ClearString;
  67. PROCEDURE ProcessModuleDef(VAR r : Files.Rider; VAR modName : ARRAY OF CHAR);
  68.   VAR
  69.     line, endStmt : ARRAY MAXLENGTH OF CHAR;
  70.     start, end : INTEGER;
  71. BEGIN
  72.   line := "";
  73.   endStmt := "";
  74.   modName := "";
  75.   (* Find the name of the module and calc the "END {NAME}." statement *)
  76.   REPEAT
  77.     ClearString(line);
  78.     In.Line(line);
  79.     IF In.Done THEN
  80.       Files.WriteString(r, line); Files.WriteString(r, endOfLine);
  81.       (* When `MODULE {NAME};` is encountered extract the module name *)
  82.       IF StartsWith("MODULE ", line) THEN
  83.         start := 7;
  84.         end := Strings.Pos(";", line, 0);
  85.         IF (end > -1) & (end > start) THEN
  86.             Strings.Extract(line, start, end - start, modName);
  87.             endStmt := "END ";
  88.             Strings.Append(modName, endStmt);
  89.             Strings.Append(".", endStmt);
  90.         END;
  91.       END;
  92.     END;
  93.   UNTIL (In.Done # TRUE) OR (endStmt # "");
  95.   (* When `END {NAME}.` is encountered  stop writing tmp file *)
  96.   REPEAT
  97.     In.Line(line);
  98.     IF In.Done THEN
  99.       Files.WriteString(r, line); Files.WriteString(r, endOfLine);
  100.     END;
  101.   UNTIL (In.Done # TRUE) OR StartsWith(endStmt, line);
  102. END ProcessModuleDef;
  104. PROCEDURE WriteModuleDef(name : ARRAY OF CHAR; VAR r : Files.Rider; VAR f : Files.File);
  105.   VAR s : ARRAY MAXLENGTH OF CHAR; res : INTEGER;
  106. BEGIN
  107.   Files.Set(r, f, 0);
  108.   REPEAT
  109.     Files.ReadString(r, s);
  110.     IF r.eof # TRUE THEN
  111.       Out.String(s);
  112.     END;
  113.   UNTIL r.eof;
  114.   Files.Close(f);
  115.   Files.Delete(name, res);
  116. END WriteModuleDef;
  119. PROCEDURE OberonToMarkdown();
  120. VAR
  121.   tmpName, modName, line : ARRAY MAXLENGTH OF CHAR;
  122.   f : Files.File;
  123.   r : Files.Rider;
  124.   i : INTEGER;
  125. BEGIN
  126.   tmpName := ""; modName := "";  line := "";
  127.   (* Open temp file *)
  128.   GenTempName("o2m", "tmp", tmpName);
  129.   GenTempFile(tmpName, r, f);
  131.   (* Read the Oberon source from standard input echo the lines tmp file *)
  132.   ProcessModuleDef(r, modName);
  134.   (* Write remainder of file to standard out *)
  135.   REPEAT
  136.     In.Line(line);
  137.     IF In.Done THEN
  138.       Out.String(line);Out.Ln();
  139.     END;
  140.   UNTIL In.Done # TRUE;
  142.   (* Write two new lines *)
  143.   Out.Ln(); Out.Ln();
  144.   (* Write heading `Source code for {NAME}` *)
  145.   ClearString(line);
  146.   line := "Source code for **";
  147.   Strings.Append(modName, line);
  148.   Strings.Append(".Mod**", line);
  149.   Out.String(line); Out.Ln();
  150.   FOR i := 0 TO Strings.Length(line) - 1 DO
  151.     Out.String("-");
  152.   END;
  153.   Out.Ln();
  154.   (* Write code fence *)
  155.   Out.Ln();Out.String("~~~");Out.Ln();
  156.   (* Reset rider to top of tmp file
  157.      Write temp file to standard out
  158.      cleanup demp file *)
  159.   WriteModuleDef(tmpName, r, f);
  160.   (* Write code fence *)
  161.   Out.Ln();Out.String("~~~");Out.Ln();
  162.   (* Write tailing line and exit procedure *)
  163.   Out.Ln();
  164. END OberonToMarkdown;
  166. BEGIN
  167.   endOfLine[0] := LF;
  168.   endOfLine[1] := 0X;
  169.   OberonToMarkdown();
  170. END ObnToMd.

Next, Previous