1. -- 
  2. -- Copyright (c) 2012 Kevin Wellwood 
  3. -- All rights reserved. 
  4. -- 
  5. -- This source code is distributed under the Modified BSD License. For terms and 
  6. -- conditions, see license.txt. 
  7. -- 
  8.  
  9. with Ada.Exceptions;                    use Ada.Exceptions; 
  10. with GNAT.Source_Info;                  use GNAT.Source_Info; 
  11. with Hashed_Strings;                    use Hashed_Strings; 
  12.  
  13. package Debugging is 
  14.  
  15.     ---------------------------------------------------------------------------- 
  16.     -- This package parses the command line arguments at elaboration time. The 
  17.     -- following are the recognized arguments: 
  18.     -- 
  19.     -- -DV=[verbosity]          (Debugging Verbosity) 
  20.     -- -DV[system]=[verbosity]  (Debugging Verbosity per system) 
  21.     -- 
  22.     --     Where: 
  23.     --     [verbosity] is the verbosity level. 
  24.     --         'e' : Errors only 
  25.     --         'w' : Warnings and errors only 
  26.     --         'i' : All info, warnings and errors 
  27.     -- 
  28.     --     [system] is the name of a specific debugging system. The standard 
  29.     --         systems names are predefined in the Engine_Debugging package. 
  30.     -- 
  31.     -- -DD=[decoration]         (Debugging Decoration) 
  32.     -- 
  33.     --     Where: 
  34.     --     [decoration] is the level of decoration for every line output by the 
  35.     --         debugging package. The decoration levels are: 
  36.     --         '0' : No decoration 
  37.     --         '1' : Prefixed with current task image 
  38.     --         '2' : Prefixed with calling source unit and current task image 
  39.     -- 
  40.     -- -DF=[filename]           (Debugging file) 
  41.     -- 
  42.     --     Where: 
  43.     --     [filename] is the file name or path to write debugging information. 
  44.     --         Debugging output will be appended to the file. If just a filename 
  45.     --         is given, the file will be written to the current working 
  46.     --         directory. This is usually the same directory as the executable. 
  47.     ---------------------------------------------------------------------------- 
  48.  
  49.     -- The form of the procedure where debugging output is directed. 
  50.     type Output_Proc is access procedure( str : String ); 
  51.  
  52.     -- Description of values: 
  53.     -- SILENT : Never ever display output with this level. 
  54.     -- ALWAYS : The default verbosity level, more verbose than SILENT but less 
  55.     --          verbose than displaying only error messages. This is used for 
  56.     --          temporary debugging output during source code development. 
  57.     -- ERROR  : Severe error messages and exceptions. 
  58.     -- WARNING: Minor warning messages that can be ignored. 
  59.     -- INFO   : Informational messages that describe what is happening. 
  60.     type Verbosity_Level is (SILENT, ALWAYS, ERROR, WARNING, INFO); 
  61.  
  62.     -- Description of values: 
  63.     -- NONE        : Display the text without decoration, as-is. 
  64.     -- TASK_IMAGE  : Prefix the text with the image of the current task. 
  65.     -- SOURCE_UNIT : Include the calling source unit with the task image. 
  66.     type Decoration_Level is (NONE, TASK_IMAGE, SOURCE_UNIT); 
  67.  
  68.     NO_SYSTEM : constant Hashed_String := To_Hashed_String( "" ); 
  69.  
  70.     ---------------------------------------------------------------------------- 
  71.  
  72.     -- Sends a line of text to the debugging output procedure. Do not specify 
  73.     -- entity and location; they are used to determine the calling location in 
  74.     -- the code. 
  75.     procedure Dbg( str      : String; 
  76.                    system   : Hashed_String := NO_SYSTEM; 
  77.                    level    : Verbosity_Level := ALWAYS; 
  78.                    entity   : String := GNAT.Source_Info.Enclosing_Entity; 
  79.                    location : String := GNAT.Source_Info.Source_Location ); 
  80.  
  81.     -- Sends debugging information from an exception to the output procedure. 
  82.     -- A stack traceback will also be displayed if available (Windows only.) Do 
  83.     -- not specify entity and location; they are used to determine the calling 
  84.     -- location in the code. 
  85.     procedure Dbg( e        : Exception_Occurrence; 
  86.                    system   : Hashed_String := NO_SYSTEM; 
  87.                    level    : Verbosity_Level := ALWAYS; 
  88.                    entity   : String := GNAT.Source_Info.Enclosing_Entity; 
  89.                    location : String := GNAT.Source_Info.Source_Location ); 
  90.  
  91.     -- Sets the global decoration level for output text. 
  92.     procedure Set_Decoration( level : Decoration_Level ); 
  93.  
  94.     -- Sets the path of the file to log debug output to. Output will be appended 
  95.     -- to the contents of the file, if it exists. Output will also be sent to 
  96.     -- the registered output procedure. 
  97.     procedure Set_Log_File( path : String ); 
  98.  
  99.     -- Sets the procedure to receive debugging output. Passing null will disable 
  100.     -- all debugging output except for the optional log file. 
  101.     procedure Set_Output( output : Output_Proc ); 
  102.  
  103.     -- Sets the global verbosity level. If an individual system has a higher 
  104.     -- level of verbosity set then it will be respected. The default global 
  105.     -- verbosity is WARNING for debug build and ALWAYS for a non-debug build. 
  106.     procedure Set_Verbosity( level : Verbosity_Level ); 
  107.  
  108.     -- Sets the maximum verbosity level per system. No output from 'system' with 
  109.     -- a verbosity level higher than this will be displayed unless it is still 
  110.     -- less than the global verbosity level. 
  111.     procedure Set_Verbosity( system : Hashed_String; level : Verbosity_Level ); 
  112.  
  113. end Debugging;