File: alog-facilities.ads

## Documentation

Table of Contents
Class Inheritance Tree

1.     --

2.     --  Copyright (c) 2008-2009,

3.     --  Reto Buerki, Adrian-Ken Rueegsegger

4.     --

5.     --  This file is part of Alog.

6.     --

7.     --  Alog is free software; you can redistribute it and/or modify

8.     --  it under the terms of the GNU Lesser General Public License as published

9.     --  by the Free Software Foundation; either version 2.1 of the License, or

10.     --  (at your option) any later version.

11.     --

12.     --  Alog is distributed in the hope that it will be useful,

13.     --  but WITHOUT ANY WARRANTY; without even the implied warranty of

14.     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

15.     --  GNU Lesser General Public License for more details.

16.     --

17.     --  You should have received a copy of the GNU Lesser General Public License

18.     --  along with Alog; if not, write to the Free Software

19.     --  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,

20.     --  MA  02110-1301  USA

21.     --

23.     with Ada.Strings.Bounded;

24.     with Ada.Strings.Unbounded;

25.     with Ada.Command_Line;

26.     with Ada.Calendar;

28.     with Alog.Log_RequestTo API docTo specTo body;

30.     --  Alog facilities package. Provides common data and methods used by all

31.     --  facilities.

32.     package Alog.FacilitiesTo API docTo specTo body is

34.        use Ada.Strings.Bounded;

35.        use Ada.Strings.Unbounded;

37.        type InstanceTo API docTo body is abstract tagged limited private;

38.        --  Abstract type facility instance. All facilities in the Alog framework

39.        --  must implement this type.

41.        subtype Class is InstanceTo API docTo specTo body'ClassTo API docTo spec;

43.        type Handle is access all ClassTo API docTo spec;

45.        function "="To API docTo body

46.          (Left  : HandleTo API docTo spec;

47.           Right : HandleTo API docTo spec) return Boolean;

48.        --  Equal function.

50.        procedure Set_NameTo API docTo body

51.          (Facility : in out ClassTo API docTo spec;

52.           Name     :        String);

53.        --  Set facility name.

55.        function Get_NameTo API docTo body (Facility : ClassTo API docTo spec) return String;

56.        --  Get facility name.

58.        function Get_TimestampTo API docTo body

59.          (Facility : ClassTo API docTo spec;

60.           Time     : Ada.Calendar.Time := Ada.Calendar.Clock)

61.           return String;

62.        --  Creates a timestamp and returns it as String. If no Time is given, the

63.        --  current time is used.

65.        procedure ProcessTo API docTo body

66.          (Facility : ClassTo API docTo spec;

67.           RequestTo API docTo body  : Log_Request.InstanceTo API docTo specTo body);

68.        --  Process a log request.

70.        procedure Write

71.          (Facility : InstanceTo API docTo specTo body;

72.           Level    : Log_LevelTo API docTo spec := Info;

73.           Msg      : String) is abstract;

74.        --  Write message with specified log level. This procedure must be

75.        --  implemented by all facilities.

77.        procedure Toggle_Write_TimestampTo API docTo body

78.          (Facility : in out ClassTo API docTo spec;

79.           State    :        Boolean);

80.        --  Enable/disable whether a timestamp is written for log messages.

82.        procedure Toggle_UTC_TimestampTo API docTo body

83.          (Facility : in out ClassTo API docTo spec;

84.           State    :        Boolean);

85.        --  Enable/disable UTC timestamps for log messages.

87.        function Is_Write_TimestampTo API docTo body (Facility : ClassTo API docTo spec) return Boolean;

88.        --  Returns the current value of Write_Timestamp.

90.        function Is_UTC_TimestampTo API docTo body (Facility : ClassTo API docTo spec) return Boolean;

91.        --  Returns True if the timestamp of the facility is written in UTC time.

93.        procedure Toggle_Write_LoglevelTo API docTo body

94.          (Facility : in out ClassTo API docTo spec;

95.           State    :        Boolean);

96.        --  Enable/disable whether the loglevel is written for log messages.

98.        function Is_Write_LoglevelTo API docTo body (Facility : ClassTo API docTo spec) return Boolean;

99.        --  Returns the current value of Write_Loglevel.

101.        procedure Toggle_Write_SourceTo API docTo body

102.          (Facility : in out ClassTo API docTo spec;

103.           State    :        Boolean);

104.        --  Enable/disable whether the source of the message is logged.

106.        function Is_Write_SourceTo API docTo body (Facility : ClassTo API docTo spec) return Boolean;

107.        --  Returns True if writing of log message sources is enabled.

109.        procedure Setup (Facility : in out InstanceTo API docTo specTo body) is null;

110.        --  Each facility must provide a Setup-procedure. These procedures are

111.        --  called by Logger instances when attaching Facilities. All needed

112.        --  operations prior to writing log messages should be done here.

114.        procedure Teardown (Facility : in out InstanceTo API docTo specTo body) is null;

115.        --  Each facility must provide a Teardown-procedure. These procedures are

116.        --  called by Logger instances when detaching Facilities or when the logger

117.        --  object gets out of scope.

119.        package BS_Path is new Generic_Bounded_Length (Max_Path_LengthTo API docTo spec);

120.        use BS_PathTo API docTo spec;

121.        --  Bounded string with length Max_Path_Length. Used in methods which

122.        --  involve filesystem operations.

124.     private

126.        type InstanceTo API docTo spec is abstract tagged limited record

127.           Name             : Unbounded_String :=

128.             To_Unbounded_String (Ada.Command_Line.Command_Name);

129.           --  Facility Name. Defaults to command-name (first argument). If multiple

130.           --  facilities are used, names must be set differently.

132.           Timestamp_Format : String (1 .. 11) := "%b %d %Y %T";

133.           --  Default timestamp format to use in this facility.

135.           Write_Timestamp  : Boolean := True;

136.           --  If True, a timestamp is written with the log message.

138.           UTC_Timestamp    : Boolean := False;

139.           --  If True, the timestamp is written in UTC time.

140.           --  (log message timestamps are written timezone-dependent).

142.           Write_Loglevel   : Boolean := False;

143.           --  If True, the loglevel associated with the log message is written.

145.           Write_Source     : Boolean := True;

146.           --  If True, the source of a log message is prepended to the message.

147.        end record;

149.     end Alog.FacilitiesTo API docTo specTo body;