Re: Ada and Literate Programming

[sb463ba@unidui.uni-duisburg.de (Georg Bauhaus)]

Robert Dewar (robert_dewar@my-deja.com) wrote:

: Seeing as the substance of literate programming is very little
: more than writing code that is properly documented,

Well some people in c.l.literate would strongly object.
Noweb, by default, produces no pretty printing of source lines,
though you can plug in a filter. But the main points of LP have
often been said to be these:

- a way of reordering pieces of code according to the way you
  prefer thinking about them, not in the sequence the computer
  needs its sources, without using subprograms.
  (much of this can be done using declare and pragma Inline in Ada,
  I suppose)

- automatic and semiautomatic indexing of identifiers or anything
  you wish.

If the compiler supports repeated [[#line]] directives, in the Ada case
repeated occurences of [[pragma Source_Reference]] in one source file,
working with WEBs can be fun :)

@ An ad hoc scrambled eggs non-exciting example of noweb code, hardly working
at best, just to give an impression. Here is the main routine, having some
vague similarities with a FSM, hobbyist's work, mind you.
(If you are reading the WEB sources: Note that [[<<]] does not introduce
Ada labels.)
<<test.adb>>=
<<with some used units>>
procedure Test is
   Symbol: Character;  -- one symbol from input
begin
   loop
      <<read a symbol and switch state>>
   end loop;
end Test;

@ Now read [[input symbols]], one by one, and according to whether a
symbol is a digit, a letter, or something else, go on and further
distinguish what needs to be done for each character in its category.
<<read a symbol and switch state>>=
Text_IO.Get(Symbol);
if Is_Digit(Symbol) then
   <<cases for digits>>
elsif Is_Letter(Symbol) then
   <<cases for letters>>
else
   <<cases for other characters>>
end if;

@ You are maybe thinking about digits already (because they appear
first in the above conditional), but first, I have to tell you
about letters, because then some things about digits will become
clear more easily.

Characters are categorized to be vowels, consonants, punctuation,
candidates for the start of a sentecnce, ...
<<cases for letters>>=
case Symbol is
   when 'a' .. 'z' =>
      -- ...
      null;
   when 'A'|'E'|'I'|'O'|'U' =>
      -- ...
      null;
   when '.'|',' =>
      -- ...
      null;
   when others =>
      -- ...
      raise Programmer_s_Error;
end case;

@ So, here is the promised section about digits.
Digits can either be [[< 5]] or otherwise [[< 9]] ...
In that case ...
<<cases for digits>>=
case Symbol is
   when '0'|'1'|'2'|'3'|'4' =>
      -- ...
      null;
   when '5'|'6'|'7'|'8'|'9' =>
      -- ...
      null;
   when others =>
      -- ...
      raise Programmer_s_Error;
end case;

@ Some symbols remain. Each of these has a special meaning.
For example, [['*']] introduces a comment iff it is the
first character on a line,...
<<cases for other characters>>=
  -- ...
  null;

@ Maybe unexpectedly, the list of units this program needs, appears in
The End. :)
<<with some used units>>=
with Ada.Characters.Handling, Ada.Text_IO;
use Ada.Characters.Handling, Ada;

><snip><
Now here is the same untangled, i.e. with original comments included.
Note that this is not what you would work with.

-- An ad hoc scrambled eggs non-exciting example of noweb code, hardly working
-- at best, just to give an impression. Here is the main routine, having some
-- vague similarities with a FSM, hobbyist's work, mind you.
-- (If you are reading the WEB sources: Note that [[<<]] does not introduce
-- Ada labels.)
--
-- <test.adb>=
-- Maybe unexpectedly, the list of units this program needs, appears in
-- The End. :)
--
-- <with some used units>=
with Ada.Characters.Handling, Ada.Text_IO;
use Ada.Characters.Handling, Ada;
procedure Test is
   Symbol: Character;  -- one symbol from input
begin
   loop
      -- Now read [[input symbols]], one by one, and according to whether a
      -- symbol is a digit, a letter, or something else, go on and further
      -- distinguish what needs to be done for each character in its category.
      --
      -- <read a symbol and switch state>=
      Text_IO.Get(Symbol);
      if Is_Digit(Symbol) then
         -- So, here is the promised section about digits.
         -- Digits can either be [[< 5]] or otherwise [[< 9]] ...
         -- In that case ...
         --
         -- <cases for digits>=
         case Symbol is
            when '0'|'1'|'2'|'3'|'4' =>
               -- ...
               null;
            when '5'|'6'|'7'|'8'|'9' =>
               -- ...
               null;
            when others =>
               -- ...
               raise Programmer_s_Error;
         end case;

      elsif Is_Letter(Symbol) then
         -- You are maybe thinking about digits already (because they appear
         -- first in the above conditional), but first, I have to tell you
         -- about letters, because then some things about digits will become
         -- clear more easily.
         --
         -- Characters are categorized to be vowels, consonants, punctuation,
         -- candidates for the start of a sentecnce, ...
         --
         -- <cases for letters>=
         case Symbol is
            when 'a' .. 'z' =>
               -- ...
               null;
            when 'A'|'E'|'I'|'O'|'U' =>
               -- ...
               null;
            when '.'|',' =>
               -- ...
               null;
            when others =>
               -- ...
               raise Programmer_s_Error;
         end case;

      else
         -- Some symbols remain. Each of these has a special meaning.
         -- For example, [['*']] introduces a comment iff it is the
         -- first character on a line,...
         --
         -- <cases for other characters>=
           -- ...
           null;

      end if;

   end loop;
end Test;

Hope this wasn't too long (though so much is missing ...;-).

-# Georg Bauhaus