File : marks.ads

-- Marks (decl)
--
-- Managing the context and options for the mark-scanning process.
--
-- Copyright (c) 2009 Tidorum Ltd.
--
-- This file is part of Find_Marks.
--
-- Find_Marks is free software: you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation, either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program.  If not, see <http://www.gnu.org/licenses/>.


with Ada.Text_IO;


package Marks is


   --
   ---   Utilities for self and children
   --


   function Trim (Item : String) return String;
   --
   -- The given string, with leading and trailing blanks removed.


   function To_Lower (Item : String) return String;
   --
   -- The given string with all letters converted to lower case form.


   --
   ---   Interface to the main procedure
   --


   procedure Note_Option (Text : in String);
   --
   -- Takes note of the given option Text, which may choose
   -- the scanner to use for the following input files, or
   -- may have some other function.


   procedure Define_File (Name : in String);
   --
   -- Defines the Name of the source file to be scanned next.
   -- If the proper scanner is not chosen by an option, the
   -- file-name suffix is used to choose a scanner.


   procedure Scan (
      Line   : in String;
      Number : in Ada.Text_IO.Positive_Count);
   --
   -- Scans this Line from the current file.
   -- The Line Number is also given.


   procedure Note_End_Of_File;
   --
   -- Signals that scanning has reached the end of the current source
   -- file.


   procedure Report_Error (Text : in String);
   --
   -- Reports an error (on Standard Error). Includes the current
   -- source-file and current source-line number, if defined.


   --
   ---   Properties of marks
   --


   type Part_T is (Any, Subprogram, Luup, Call);
   --
   -- A mark definition can specify the kind of program part
   -- that it marks. "Any" means "unspecified".


   type Position_T is (Any, Here, Above, Below);
   --
   -- A mark definition can specify the positional relation between
   -- the marked source-code line and the program part that will be
   -- identified by the mark.
   --
   -- Any
   --    Positional relation not specified (in the mark definition; it
   --    can still be specified in an assertion that uses the marker).
   -- Here
   --    The mark line itself.
   -- Above
   --    The last markable line before the mark line.
   -- Below
   --    The next markable line after the mark line.


   type Relation_T is (Any, This, Contain, Span);
   --
   -- A mark definition can specify the logical relation between the
   -- mark line and the marked part.
   --
   -- Any
   --    Logical relation not specified (in the mark definition; it
   --    can still be specified in an assertion that uses the marker).
   -- This
   --    The marked part coincides with or consists of the marked line.
   -- Contain
   --    The marked part contains the instruction(s) (flow-graph steps)
   --    marked by this marker. At present, the containing part
   --    can only be a loop.
   -- Span
   --    The marked part spans the marked line, in the sense that the
   --    number of the marked line is in the range of line numbers
   --    connected to the instructions in this program part. At present,
   --    the spanning part can only be a loop.


   type Properties_T is record
      Part     : Part_T;
      Position : Position_T;
      Relation : Relation_T;
   end record;
   --
   -- Three properties of a mark, wrapped up.


   Any_Properties : constant Properties_T := (Any, Any, Any);
   --
   -- Unspecified properies.


   --
   ---   Interface to the language-specific scanners
   --


   procedure Define (
      Marker     : in String;
      Properties : in Properties_T);
   --
   -- Defines a mark that was detected on the current line (current
   -- invocation of Scan (Line, ..)). The mark is identified by its
   -- Marker name and the Properties may specify a marked Part, the
   -- Position of the marked line, and/or the Relation between the
   -- marked line and the marked Part.
   --
   -- The source-file name and the line-number are known internally
   -- to the Marks package (from the last invocations of Define_File
   -- and Scan (Line, Number), respectively).
   --
   -- Note that if the Position is Above or Below, the marked line
   -- will be the last markable line before or after the current line,
   -- not the current line itself. If Position is Above, but no earlier
   -- markable lines have been found, an error is reported. If Position
   -- is Below, the mark definition remains incomplete; it will be
   -- completed when the next markable line is found.


end Marks;