| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT COMPILER COMPONENTS -- |
| -- -- |
| -- G N A T . A W K -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 2000-2011, AdaCore -- |
| -- -- |
| -- GNAT is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. -- |
| -- -- |
| -- As a special exception under Section 7 of GPL version 3, you are granted -- |
| -- additional permissions described in the GCC Runtime Library Exception, -- |
| -- version 3.1, as published by the Free Software Foundation. -- |
| -- -- |
| -- You should have received a copy of the GNU General Public License and -- |
| -- a copy of the GCC Runtime Library Exception along with this program; -- |
| -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- |
| -- <http://www.gnu.org/licenses/>. -- |
| -- -- |
| -- GNAT was originally developed by the GNAT team at New York University. -- |
| -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
| -- -- |
| ------------------------------------------------------------------------------ |
| |
| -- This is an AWK-like unit. It provides an easy interface for parsing one |
| -- or more files containing formatted data. The file can be viewed seen as |
| -- a database where each record is a line and a field is a data element in |
| -- this line. In this implementation an AWK record is a line. This means |
| -- that a record cannot span multiple lines. The operating procedure is to |
| -- read files line by line, with each line being presented to the user of |
| -- the package. The interface provides services to access specific fields |
| -- in the line. Thus it is possible to control actions taken on a line based |
| -- on values of some fields. This can be achieved directly or by registering |
| -- callbacks triggered on programmed conditions. |
| -- |
| -- The state of an AWK run is recorded in an object of type session. |
| -- The following is the procedure for using a session to control an |
| -- AWK run: |
| -- |
| -- 1) Specify which session is to be used. It is possible to use the |
| -- default session or to create a new one by declaring an object of |
| -- type Session_Type. For example: |
| -- |
| -- Computers : Session_Type; |
| -- |
| -- 2) Specify how to cut a line into fields. There are two modes: using |
| -- character fields separators or column width. This is done by using |
| -- Set_Fields_Separators or Set_Fields_Width. For example by: |
| -- |
| -- AWK.Set_Field_Separators (";,", Computers); |
| -- |
| -- or by using iterators' Separators parameter. |
| -- |
| -- 3) Specify which files to parse. This is done with Add_File/Add_Files |
| -- services, or by using the iterators' Filename parameter. For |
| -- example: |
| -- |
| -- AWK.Add_File ("myfile.db", Computers); |
| -- |
| -- 4) Run the AWK session using one of the provided iterators. |
| -- |
| -- Parse |
| -- This is the most automated iterator. You can gain control on |
| -- the session only by registering one or more callbacks (see |
| -- Register). |
| -- |
| -- Get_Line/End_Of_Data |
| -- This is a manual iterator to be used with a loop. You have |
| -- complete control on the session. You can use callbacks but |
| -- this is not required. |
| -- |
| -- For_Every_Line |
| -- This provides a mixture of manual/automated iterator action. |
| -- |
| -- Examples of these three approaches appear below |
| -- |
| -- There are many ways to use this package. The following discussion shows |
| -- three approaches to using this package, using the three iterator forms. |
| -- All examples will use the following file (computer.db): |
| -- |
| -- Pluton;Windows-NT;Pentium III |
| -- Mars;Linux;Pentium Pro |
| -- Venus;Solaris;Sparc |
| -- Saturn;OS/2;i486 |
| -- Jupiter;MacOS;PPC |
| -- |
| -- 1) Using Parse iterator |
| -- |
| -- Here the first step is to register some action associated to a pattern |
| -- and then to call the Parse iterator (this is the simplest way to use |
| -- this unit). The default session is used here. For example to output the |
| -- second field (the OS) of computer "Saturn". |
| -- |
| -- procedure Action is |
| -- begin |
| -- Put_Line (AWK.Field (2)); |
| -- end Action; |
| -- |
| -- begin |
| -- AWK.Register (1, "Saturn", Action'Access); |
| -- AWK.Parse (";", "computer.db"); |
| -- |
| -- |
| -- 2) Using the Get_Line/End_Of_Data iterator |
| -- |
| -- Here you have full control. For example to do the same as |
| -- above but using a specific session, you could write: |
| -- |
| -- Computer_File : Session_Type; |
| -- |
| -- begin |
| -- AWK.Set_Current (Computer_File); |
| -- AWK.Open (Separators => ";", |
| -- Filename => "computer.db"); |
| -- |
| -- -- Display Saturn OS |
| -- |
| -- while not AWK.End_Of_File loop |
| -- AWK.Get_Line; |
| -- |
| -- if AWK.Field (1) = "Saturn" then |
| -- Put_Line (AWK.Field (2)); |
| -- end if; |
| -- end loop; |
| -- |
| -- AWK.Close (Computer_File); |
| -- |
| -- |
| -- 3) Using For_Every_Line iterator |
| -- |
| -- In this case you use a provided iterator and you pass the procedure |
| -- that must be called for each record. You could code the previous |
| -- example could be coded as follows (using the iterator quick interface |
| -- but without using the current session): |
| -- |
| -- Computer_File : Session_Type; |
| -- |
| -- procedure Action (Quit : in out Boolean) is |
| -- begin |
| -- if AWK.Field (1, Computer_File) = "Saturn" then |
| -- Put_Line (AWK.Field (2, Computer_File)); |
| -- end if; |
| -- end Action; |
| -- |
| -- procedure Look_For_Saturn is |
| -- new AWK.For_Every_Line (Action); |
| -- |
| -- begin |
| -- Look_For_Saturn (Separators => ";", |
| -- Filename => "computer.db", |
| -- Session => Computer_File); |
| -- |
| -- Integer_Text_IO.Put |
| -- (Integer (AWK.NR (Session => Computer_File))); |
| -- Put_Line (" line(s) have been processed."); |
| -- |
| -- You can also use a regular expression for the pattern. Let us output |
| -- the computer name for all computer for which the OS has a character |
| -- O in its name. |
| -- |
| -- Regexp : String := ".*O.*"; |
| -- |
| -- Matcher : Regpat.Pattern_Matcher := Regpat.Compile (Regexp); |
| -- |
| -- procedure Action is |
| -- begin |
| -- Text_IO.Put_Line (AWK.Field (2)); |
| -- end Action; |
| -- |
| -- begin |
| -- AWK.Register (2, Matcher, Action'Unrestricted_Access); |
| -- AWK.Parse (";", "computer.db"); |
| -- |
| |
| with Ada.Finalization; |
| with GNAT.Regpat; |
| |
| package GNAT.AWK is |
| |
| Session_Error : exception; |
| -- Raised when a Session is reused but is not closed |
| |
| File_Error : exception; |
| -- Raised when there is a file problem (see below) |
| |
| End_Error : exception; |
| -- Raised when an attempt is made to read beyond the end of the last |
| -- file of a session. |
| |
| Field_Error : exception; |
| -- Raised when accessing a field value which does not exist |
| |
| Data_Error : exception; |
| -- Raised when it is impossible to convert a field value to a specific type |
| |
| type Count is new Natural; |
| |
| type Widths_Set is array (Positive range <>) of Positive; |
| -- Used to store a set of columns widths |
| |
| Default_Separators : constant String := " " & ASCII.HT; |
| |
| Use_Current : constant String := ""; |
| -- Value used when no separator or filename is specified in iterators |
| |
| type Session_Type is limited private; |
| -- This is the main exported type. A session is used to keep the state of |
| -- a full AWK run. The state comprises a list of files, the current file, |
| -- the number of line processed, the current line, the number of fields in |
| -- the current line... A default session is provided (see Set_Current, |
| -- Current_Session and Default_Session below). |
| |
| ---------------------------- |
| -- Package initialization -- |
| ---------------------------- |
| |
| -- To be thread safe it is not possible to use the default provided |
| -- session. Each task must used a specific session and specify it |
| -- explicitly for every services. |
| |
| procedure Set_Current (Session : Session_Type); |
| -- Set the session to be used by default. This file will be used when the |
| -- Session parameter in following services is not specified. |
| |
| function Current_Session return not null access Session_Type; |
| -- Returns the session used by default by all services. This is the |
| -- latest session specified by Set_Current service or the session |
| -- provided by default with this implementation. |
| |
| function Default_Session return not null access Session_Type; |
| -- Returns the default session provided by this package. Note that this is |
| -- the session return by Current_Session if Set_Current has not been used. |
| |
| procedure Set_Field_Separators |
| (Separators : String := Default_Separators; |
| Session : Session_Type); |
| procedure Set_Field_Separators |
| (Separators : String := Default_Separators); |
| -- Set the field separators. Each character in the string is a field |
| -- separator. When a line is read it will be split by field using the |
| -- separators set here. Separators can be changed at any point and in this |
| -- case the current line is split according to the new separators. In the |
| -- special case that Separators is a space and a tabulation |
| -- (Default_Separators), fields are separated by runs of spaces and/or |
| -- tabs. |
| |
| procedure Set_FS |
| (Separators : String := Default_Separators; |
| Session : Session_Type) |
| renames Set_Field_Separators; |
| procedure Set_FS |
| (Separators : String := Default_Separators) |
| renames Set_Field_Separators; |
| -- FS is the AWK abbreviation for above service |
| |
| procedure Set_Field_Widths |
| (Field_Widths : Widths_Set; |
| Session : Session_Type); |
| procedure Set_Field_Widths |
| (Field_Widths : Widths_Set); |
| -- This is another way to split a line by giving the length (in number of |
| -- characters) of each field in a line. Field widths can be changed at any |
| -- point and in this case the current line is split according to the new |
| -- field lengths. A line split with this method must have a length equal or |
| -- greater to the total of the field widths. All characters remaining on |
| -- the line after the latest field are added to a new automatically |
| -- created field. |
| |
| procedure Add_File |
| (Filename : String; |
| Session : Session_Type); |
| procedure Add_File |
| (Filename : String); |
| -- Add Filename to the list of file to be processed. There is no limit on |
| -- the number of files that can be added. Files are processed in the order |
| -- they have been added (i.e. the filename list is FIFO). If Filename does |
| -- not exist or if it is not readable, File_Error is raised. |
| |
| procedure Add_Files |
| (Directory : String; |
| Filenames : String; |
| Number_Of_Files_Added : out Natural; |
| Session : Session_Type); |
| procedure Add_Files |
| (Directory : String; |
| Filenames : String; |
| Number_Of_Files_Added : out Natural); |
| -- Add all files matching the regular expression Filenames in the specified |
| -- directory to the list of file to be processed. There is no limit on |
| -- the number of files that can be added. Each file is processed in |
| -- the same order they have been added (i.e. the filename list is FIFO). |
| -- The number of files (possibly 0) added is returned in |
| -- Number_Of_Files_Added. |
| |
| ------------------------------------- |
| -- Information about current state -- |
| ------------------------------------- |
| |
| function Number_Of_Fields |
| (Session : Session_Type) return Count; |
| function Number_Of_Fields |
| return Count; |
| pragma Inline (Number_Of_Fields); |
| -- Returns the number of fields in the current record. It returns 0 when |
| -- no file is being processed. |
| |
| function NF |
| (Session : Session_Type) return Count |
| renames Number_Of_Fields; |
| function NF |
| return Count |
| renames Number_Of_Fields; |
| -- AWK abbreviation for above service |
| |
| function Number_Of_File_Lines |
| (Session : Session_Type) return Count; |
| function Number_Of_File_Lines |
| return Count; |
| pragma Inline (Number_Of_File_Lines); |
| -- Returns the current line number in the processed file. It returns 0 when |
| -- no file is being processed. |
| |
| function FNR (Session : Session_Type) return Count |
| renames Number_Of_File_Lines; |
| function FNR return Count |
| renames Number_Of_File_Lines; |
| -- AWK abbreviation for above service |
| |
| function Number_Of_Lines |
| (Session : Session_Type) return Count; |
| function Number_Of_Lines |
| return Count; |
| pragma Inline (Number_Of_Lines); |
| -- Returns the number of line processed until now. This is equal to number |
| -- of line in each already processed file plus FNR. It returns 0 when |
| -- no file is being processed. |
| |
| function NR (Session : Session_Type) return Count |
| renames Number_Of_Lines; |
| function NR return Count |
| renames Number_Of_Lines; |
| -- AWK abbreviation for above service |
| |
| function Number_Of_Files |
| (Session : Session_Type) return Natural; |
| function Number_Of_Files |
| return Natural; |
| pragma Inline (Number_Of_Files); |
| -- Returns the number of files associated with Session. This is the total |
| -- number of files added with Add_File and Add_Files services. |
| |
| function File (Session : Session_Type) return String; |
| function File return String; |
| -- Returns the name of the file being processed. It returns the empty |
| -- string when no file is being processed. |
| |
| --------------------- |
| -- Field accessors -- |
| --------------------- |
| |
| function Field |
| (Rank : Count; |
| Session : Session_Type) return String; |
| function Field |
| (Rank : Count) return String; |
| -- Returns field number Rank value of the current record. If Rank = 0 it |
| -- returns the current record (i.e. the line as read in the file). It |
| -- raises Field_Error if Rank > NF or if Session is not open. |
| |
| function Field |
| (Rank : Count; |
| Session : Session_Type) return Integer; |
| function Field |
| (Rank : Count) return Integer; |
| -- Returns field number Rank value of the current record as an integer. It |
| -- raises Field_Error if Rank > NF or if Session is not open. It |
| -- raises Data_Error if the field value cannot be converted to an integer. |
| |
| function Field |
| (Rank : Count; |
| Session : Session_Type) return Float; |
| function Field |
| (Rank : Count) return Float; |
| -- Returns field number Rank value of the current record as a float. It |
| -- raises Field_Error if Rank > NF or if Session is not open. It |
| -- raises Data_Error if the field value cannot be converted to a float. |
| |
| generic |
| type Discrete is (<>); |
| function Discrete_Field |
| (Rank : Count; |
| Session : Session_Type) return Discrete; |
| generic |
| type Discrete is (<>); |
| function Discrete_Field_Current_Session |
| (Rank : Count) return Discrete; |
| -- Returns field number Rank value of the current record as a type |
| -- Discrete. It raises Field_Error if Rank > NF. It raises Data_Error if |
| -- the field value cannot be converted to type Discrete. |
| |
| -------------------- |
| -- Pattern/Action -- |
| -------------------- |
| |
| -- AWK defines rules like "PATTERN { ACTION }". Which means that ACTION |
| -- will be executed if PATTERN match. A pattern in this implementation can |
| -- be a simple string (match function is equality), a regular expression, |
| -- a function returning a boolean. An action is associated to a pattern |
| -- using the Register services. |
| -- |
| -- Each procedure Register will add a rule to the set of rules for the |
| -- session. Rules are examined in the order they have been added. |
| |
| type Pattern_Callback is access function return Boolean; |
| -- This is a pattern function pointer. When it returns True the associated |
| -- action will be called. |
| |
| type Action_Callback is access procedure; |
| -- A simple action pointer |
| |
| type Match_Action_Callback is |
| access procedure (Matches : GNAT.Regpat.Match_Array); |
| -- An advanced action pointer used with a regular expression pattern. It |
| -- returns an array of all the matches. See GNAT.Regpat for further |
| -- information. |
| |
| procedure Register |
| (Field : Count; |
| Pattern : String; |
| Action : Action_Callback; |
| Session : Session_Type); |
| procedure Register |
| (Field : Count; |
| Pattern : String; |
| Action : Action_Callback); |
| -- Register an Action associated with a Pattern. The pattern here is a |
| -- simple string that must match exactly the field number specified. |
| |
| procedure Register |
| (Field : Count; |
| Pattern : GNAT.Regpat.Pattern_Matcher; |
| Action : Action_Callback; |
| Session : Session_Type); |
| procedure Register |
| (Field : Count; |
| Pattern : GNAT.Regpat.Pattern_Matcher; |
| Action : Action_Callback); |
| -- Register an Action associated with a Pattern. The pattern here is a |
| -- simple regular expression which must match the field number specified. |
| |
| procedure Register |
| (Field : Count; |
| Pattern : GNAT.Regpat.Pattern_Matcher; |
| Action : Match_Action_Callback; |
| Session : Session_Type); |
| procedure Register |
| (Field : Count; |
| Pattern : GNAT.Regpat.Pattern_Matcher; |
| Action : Match_Action_Callback); |
| -- Same as above but it pass the set of matches to the action |
| -- procedure. This is useful to analyse further why and where a regular |
| -- expression did match. |
| |
| procedure Register |
| (Pattern : Pattern_Callback; |
| Action : Action_Callback; |
| Session : Session_Type); |
| procedure Register |
| (Pattern : Pattern_Callback; |
| Action : Action_Callback); |
| -- Register an Action associated with a Pattern. The pattern here is a |
| -- function that must return a boolean. Action callback will be called if |
| -- the pattern callback returns True and nothing will happen if it is |
| -- False. This version is more general, the two other register services |
| -- trigger an action based on the value of a single field only. |
| |
| procedure Register |
| (Action : Action_Callback; |
| Session : Session_Type); |
| procedure Register |
| (Action : Action_Callback); |
| -- Register an Action that will be called for every line. This is |
| -- equivalent to a Pattern_Callback function always returning True. |
| |
| -------------------- |
| -- Parse iterator -- |
| -------------------- |
| |
| procedure Parse |
| (Separators : String := Use_Current; |
| Filename : String := Use_Current; |
| Session : Session_Type); |
| procedure Parse |
| (Separators : String := Use_Current; |
| Filename : String := Use_Current); |
| -- Launch the iterator, it will read every line in all specified |
| -- session's files. Registered callbacks are then called if the associated |
| -- pattern match. It is possible to specify a filename and a set of |
| -- separators directly. This offer a quick way to parse a single |
| -- file. These parameters will override those specified by Set_FS and |
| -- Add_File. The Session will be opened and closed automatically. |
| -- File_Error is raised if there is no file associated with Session, or if |
| -- a file associated with Session is not longer readable. It raises |
| -- Session_Error is Session is already open. |
| |
| ----------------------------------- |
| -- Get_Line/End_Of_Data Iterator -- |
| ----------------------------------- |
| |
| type Callback_Mode is (None, Only, Pass_Through); |
| -- These mode are used for Get_Line/End_Of_Data and For_Every_Line |
| -- iterators. The associated semantic is: |
| -- |
| -- None |
| -- callbacks are not active. This is the default mode for |
| -- Get_Line/End_Of_Data and For_Every_Line iterators. |
| -- |
| -- Only |
| -- callbacks are active, if at least one pattern match, the associated |
| -- action is called and this line will not be passed to the user. In |
| -- the Get_Line case the next line will be read (if there is some |
| -- line remaining), in the For_Every_Line case Action will |
| -- not be called for this line. |
| -- |
| -- Pass_Through |
| -- callbacks are active, for patterns which match the associated |
| -- action is called. Then the line is passed to the user. It means |
| -- that Action procedure is called in the For_Every_Line case and |
| -- that Get_Line returns with the current line active. |
| -- |
| |
| procedure Open |
| (Separators : String := Use_Current; |
| Filename : String := Use_Current; |
| Session : Session_Type); |
| procedure Open |
| (Separators : String := Use_Current; |
| Filename : String := Use_Current); |
| -- Open the first file and initialize the unit. This must be called once |
| -- before using Get_Line. It is possible to specify a filename and a set of |
| -- separators directly. This offer a quick way to parse a single file. |
| -- These parameters will override those specified by Set_FS and Add_File. |
| -- File_Error is raised if there is no file associated with Session, or if |
| -- the first file associated with Session is no longer readable. It raises |
| -- Session_Error is Session is already open. |
| |
| procedure Get_Line |
| (Callbacks : Callback_Mode := None; |
| Session : Session_Type); |
| procedure Get_Line |
| (Callbacks : Callback_Mode := None); |
| -- Read a line from the current input file. If the file index is at the |
| -- end of the current input file (i.e. End_Of_File is True) then the |
| -- following file is opened. If there is no more file to be processed, |
| -- exception End_Error will be raised. File_Error will be raised if Open |
| -- has not been called. Next call to Get_Line will return the following |
| -- line in the file. By default the registered callbacks are not called by |
| -- Get_Line, this can activated by setting Callbacks (see Callback_Mode |
| -- description above). File_Error may be raised if a file associated with |
| -- Session is not readable. |
| -- |
| -- When Callbacks is not None, it is possible to exhaust all the lines |
| -- of all the files associated with Session. In this case, File_Error |
| -- is not raised. |
| -- |
| -- This procedure can be used from a subprogram called by procedure Parse |
| -- or by an instantiation of For_Every_Line (see below). |
| |
| function End_Of_Data |
| (Session : Session_Type) return Boolean; |
| function End_Of_Data |
| return Boolean; |
| pragma Inline (End_Of_Data); |
| -- Returns True if there is no more data to be processed in Session. It |
| -- means that the latest session's file is being processed and that |
| -- there is no more data to be read in this file (End_Of_File is True). |
| |
| function End_Of_File |
| (Session : Session_Type) return Boolean; |
| function End_Of_File |
| return Boolean; |
| pragma Inline (End_Of_File); |
| -- Returns True when there is no more data to be processed on the current |
| -- session's file. |
| |
| procedure Close (Session : Session_Type); |
| -- Release all associated data with Session. All memory allocated will |
| -- be freed, the current file will be closed if needed, the callbacks |
| -- will be unregistered. Close is convenient in reestablishing a session |
| -- for new use. Get_Line is no longer usable (will raise File_Error) |
| -- except after a successful call to Open, Parse or an instantiation |
| -- of For_Every_Line. |
| |
| ----------------------------- |
| -- For_Every_Line iterator -- |
| ----------------------------- |
| |
| generic |
| with procedure Action (Quit : in out Boolean); |
| procedure For_Every_Line |
| (Separators : String := Use_Current; |
| Filename : String := Use_Current; |
| Callbacks : Callback_Mode := None; |
| Session : Session_Type); |
| generic |
| with procedure Action (Quit : in out Boolean); |
| procedure For_Every_Line_Current_Session |
| (Separators : String := Use_Current; |
| Filename : String := Use_Current; |
| Callbacks : Callback_Mode := None); |
| -- This is another iterator. Action will be called for each new |
| -- record. The iterator's termination can be controlled by setting Quit |
| -- to True. It is by default set to False. It is possible to specify a |
| -- filename and a set of separators directly. This offer a quick way to |
| -- parse a single file. These parameters will override those specified by |
| -- Set_FS and Add_File. By default the registered callbacks are not called |
| -- by For_Every_Line, this can activated by setting Callbacks (see |
| -- Callback_Mode description above). The Session will be opened and |
| -- closed automatically. File_Error is raised if there is no file |
| -- associated with Session. It raises Session_Error is Session is already |
| -- open. |
| |
| private |
| type Session_Data; |
| type Session_Data_Access is access Session_Data; |
| |
| type Session_Type is new Ada.Finalization.Limited_Controlled with record |
| Data : Session_Data_Access; |
| Self : not null access Session_Type := Session_Type'Unchecked_Access; |
| end record; |
| |
| procedure Initialize (Session : in out Session_Type); |
| procedure Finalize (Session : in out Session_Type); |
| |
| end GNAT.AWK; |
