| blob | 577f04e3435fbb957682858a89654af45ad0c74d |
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- G N A T . A W K --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2000-2003 Ada Core Technologies, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
21 -- --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
28 -- --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
31 -- --
32 ------------------------------------------------------------------------------
34 -- This is an AWK-like unit. It provides an easy interface for parsing one
35 -- or more files containing formatted data. The file can be viewed seen as
36 -- a database where each record is a line and a field is a data element in
37 -- this line. In this implementation an AWK record is a line. This means
38 -- that a record cannot span multiple lines. The operating procedure is to
39 -- read files line by line, with each line being presented to the user of
40 -- the package. The interface provides services to access specific fields
41 -- in the line. Thus it is possible to control actions takn on a line based
42 -- on values of some fields. This can be achieved directly or by registering
43 -- callbacks triggered on programmed conditions.
44 --
45 -- The state of an AWK run is recorded in an object of type session.
46 -- The following is the procedure for using a session to control an
47 -- AWK run:
48 --
49 -- 1) Specify which session is to be used. It is possible to use the
50 -- default session or to create a new one by declaring an object of
51 -- type Session_Type. For example:
52 --
53 -- Computers : Session_Type;
54 --
55 -- 2) Specify how to cut a line into fields. There are two modes: using
56 -- character fields separators or column width. This is done by using
57 -- Set_Fields_Separators or Set_Fields_Width. For example by:
58 --
59 -- AWK.Set_Field_Separators (";,", Computers);
60 --
61 -- or by using iterators' Separators parameter.
62 --
63 -- 3) Specify which files to parse. This is done with Add_File/Add_Files
64 -- services, or by using the iterators' Filename parameter. For
65 -- example:
66 --
67 -- AWK.Add_File ("myfile.db", Computers);
68 --
69 -- 4) Run the AWK session using one of the provided iterators.
70 --
71 -- Parse
72 -- This is the most automated iterator. You can gain control on
73 -- the session only by registering one or more callbacks (see
74 -- Register).
75 --
76 -- Get_Line/End_Of_Data
77 -- This is a manual iterator to be used with a loop. You have
78 -- complete control on the session. You can use callbacks but
79 -- this is not required.
80 --
81 -- For_Every_Line
82 -- This provides a mixture of manual/automated iterator action.
83 --
84 -- Examples of these three approaches appear below
85 --
86 -- There is many ways to use this package. The following discussion shows
87 -- three approaches, using the three iterator forms, to using this package.
88 -- All examples will use the following file (computer.db):
89 --
90 -- Pluton;Windows-NT;Pentium III
91 -- Mars;Linux;Pentium Pro
92 -- Venus;Solaris;Sparc
93 -- Saturn;OS/2;i486
94 -- Jupiter;MacOS;PPC
95 --
96 -- 1) Using Parse iterator
97 --
98 -- Here the first step is to register some action associated to a pattern
99 -- and then to call the Parse iterator (this is the simplest way to use
100 -- this unit). The default session is used here. For example to output the
101 -- second field (the OS) of computer "Saturn".
102 --
103 -- procedure Action is
104 -- begin
105 -- Put_Line (AWK.Field (2));
106 -- end Action;
107 --
108 -- begin
109 -- AWK.Register (1, "Saturn", Action'Access);
110 -- AWK.Parse (";", "computer.db");
111 --
112 --
113 -- 2) Using the Get_Line/End_Of_Data iterator
114 --
115 -- Here you have full control. For example to do the same as
116 -- above but using a specific session, you could write:
117 --
118 -- Computer_File : Session_Type;
119 --
120 -- begin
121 -- AWK.Set_Current (Computer_File);
122 -- AWK.Open (Separators => ";",
123 -- Filename => "computer.db");
124 --
125 -- -- Display Saturn OS
126 --
127 -- while not AWK.End_Of_File loop
128 -- AWK.Get_Line;
129 --
130 -- if AWK.Field (1) = "Saturn" then
131 -- Put_Line (AWK.Field (2));
132 -- end if;
133 -- end loop;
134 --
135 -- AWK.Close (Computer_File);
136 --
137 --
138 -- 3) Using For_Every_Line iterator
139 --
140 -- In this case you use a provided iterator and you pass the procedure
141 -- that must be called for each record. You could code the previous
142 -- example could be coded as follows (using the iterator quick interface
143 -- but without using the current session):
144 --
145 -- Computer_File : Session_Type;
146 --
147 -- procedure Action (Quit : in out Boolean) is
148 -- begin
149 -- if AWK.Field (1, Computer_File) = "Saturn" then
150 -- Put_Line (AWK.Field (2, Computer_File));
151 -- end if;
152 -- end Action;
153 --
154 -- procedure Look_For_Saturn is
155 -- new AWK.For_Every_Line (Action);
156 --
157 -- begin
158 -- Look_For_Saturn (Separators => ";",
159 -- Filename => "computer.db",
160 -- Session => Computer_File);
161 --
162 -- Integer_Text_IO.Put
163 -- (Integer (AWK.NR (Session => Computer_File)));
164 -- Put_Line (" line(s) have been processed.");
165 --
166 -- You can also use a regular expression for the pattern. Let us output
167 -- the computer name for all computer for which the OS has a character
168 -- O in its name.
169 --
170 -- Regexp : String := ".*O.*";
171 --
172 -- Matcher : Regpat.Pattern_Matcher := Regpat.Compile (Regexp);
173 --
174 -- procedure Action is
175 -- begin
176 -- Text_IO.Put_Line (AWK.Field (2));
177 -- end Action;
178 --
179 -- begin
180 -- AWK.Register (2, Matcher, Action'Unrestricted_Access);
181 -- AWK.Parse (";", "computer.db");
182 --
190 -- Raised when a Session is reused but is not closed.
193 -- Raised when there is a file problem (see below).
196 -- Raised when an attempt is made to read beyond the end of the last
197 -- file of a session.
200 -- Raised when accessing a field value which does not exist.
203 -- Raised when it is not possible to convert a field value to a specific
204 -- type.
209 -- Used to store a set of columns widths.
214 -- Value used when no separator or filename is specified in iterators.
217 -- This is the main exported type. A session is used to keep the state of
218 -- a full AWK run. The state comprises a list of files, the current file,
219 -- the number of line processed, the current line, the number of fields in
220 -- the current line... A default session is provided (see Set_Current,
221 -- Current_Session and Default_Session above).
223 ----------------------------
224 -- Package initialization --
225 ----------------------------
227 -- To be thread safe it is not possible to use the default provided
228 -- session. Each task must used a specific session and specify it
229 -- explicitly for every services.
232 -- Set the session to be used by default. This file will be used when the
233 -- Session parameter in following services is not specified.
236 -- Returns the session used by default by all services. This is the
237 -- latest session specified by Set_Current service or the session
238 -- provided by default with this implementation.
241 -- Returns the default session provided by this package. Note that this is
242 -- the session return by Current_Session if Set_Current has not been used.
244 procedure Set_Field_Separators
247 -- Set the field separators. Each character in the string is a field
248 -- separator. When a line is read it will be split by field using the
249 -- separators set here. Separators can be changed at any point and in this
250 -- case the current line is split according to the new separators. In the
251 -- special case that Separators is a space and a tabulation
252 -- (Default_Separators), fields are separated by runs of spaces and/or
253 -- tabs.
255 procedure Set_FS
259 -- FS is the AWK abbreviation for above service.
261 procedure Set_Field_Widths
264 -- This is another way to split a line by giving the length (in number of
265 -- characters) of each field in a line. Field widths can be changed at any
266 -- point and in this case the current line is split according to the new
267 -- field lengths. A line split with this method must have a length equal or
268 -- greater to the total of the field widths. All characters remaining on
269 -- the line after the latest field are added to a new automatically
270 -- created field.
272 procedure Add_File
275 -- Add Filename to the list of file to be processed. There is no limit on
276 -- the number of files that can be added. Files are processed in the order
277 -- they have been added (i.e. the filename list is FIFO). If Filename does
278 -- not exist or if it is not readable, File_Error is raised.
280 procedure Add_Files
285 -- Add all files matching the regular expression Filenames in the specified
286 -- directory to the list of file to be processed. There is no limit on
287 -- the number of files that can be added. Each file is processed in
288 -- the same order they have been added (i.e. the filename list is FIFO).
289 -- The number of files (possibly 0) added is returned in
290 -- Number_Of_Files_Added.
292 -------------------------------------
293 -- Information about current state --
294 -------------------------------------
296 function Number_Of_Fields
300 -- Returns the number of fields in the current record. It returns 0 when
301 -- no file is being processed.
303 function NF
305 return Count
307 -- AWK abbreviation for above service.
309 function Number_Of_File_Lines
313 -- Returns the current line number in the processed file. It returns 0 when
314 -- no file is being processed.
316 function FNR
319 -- AWK abbreviation for above service.
321 function Number_Of_Lines
325 -- Returns the number of line processed until now. This is equal to number
326 -- of line in each already processed file plus FNR. It returns 0 when
327 -- no file is being processed.
329 function NR
331 return Count
333 -- AWK abbreviation for above service.
335 function Number_Of_Files
339 -- Returns the number of files associated with Session. This is the total
340 -- number of files added with Add_File and Add_Files services.
342 function File
345 -- Returns the name of the file being processed. It returns the empty
346 -- string when no file is being processed.
348 ---------------------
349 -- Field accessors --
350 ---------------------
352 function Field
356 -- Returns field number Rank value of the current record. If Rank = 0 it
357 -- returns the current record (i.e. the line as read in the file). It
358 -- raises Field_Error if Rank > NF or if Session is not open.
360 function Field
364 -- Returns field number Rank value of the current record as an integer. It
365 -- raises Field_Error if Rank > NF or if Session is not open. It
366 -- raises Data_Error if the field value cannot be converted to an integer.
368 function Field
372 -- Returns field number Rank value of the current record as a float. It
373 -- raises Field_Error if Rank > NF or if Session is not open. It
374 -- raises Data_Error if the field value cannot be converted to a float.
376 generic
378 function Discrete_Field
382 -- Returns field number Rank value of the current record as a type
383 -- Discrete. It raises Field_Error if Rank > NF. It raises Data_Error if
384 -- the field value cannot be converted to type Discrete.
386 --------------------
387 -- Pattern/Action --
388 --------------------
390 -- AWK defines rules like "PATTERN { ACTION }". Which means that ACTION
391 -- will be executed if PATTERN match. A pattern in this implementation can
392 -- be a simple string (match function is equality), a regular expression,
393 -- a function returning a boolean. An action is associated to a pattern
394 -- using the Register services.
395 --
396 -- Each procedure Register will add a rule to the set of rules for the
397 -- session. Rules are examined in the order they have been added.
400 -- This is a pattern function pointer. When it returns True the associated
401 -- action will be called.
404 -- A simple action pointer
408 -- An advanced action pointer used with a regular expression pattern. It
409 -- returns an array of all the matches. See GNAT.Regpat for further
410 -- information.
412 procedure Register
417 -- Register an Action associated with a Pattern. The pattern here is a
418 -- simple string that must match exactly the field number specified.
420 procedure Register
425 -- Register an Action associated with a Pattern. The pattern here is a
426 -- simple regular expression which must match the field number specified.
428 procedure Register
433 -- Same as above but it pass the set of matches to the action
434 -- procedure. This is useful to analyse further why and where a regular
435 -- expression did match.
437 procedure Register
441 -- Register an Action associated with a Pattern. The pattern here is a
442 -- function that must return a boolean. Action callback will be called if
443 -- the pattern callback returns True and nothing will happen if it is
444 -- False. This version is more general, the two other register services
445 -- trigger an action based on the value of a single field only.
447 procedure Register
450 -- Register an Action that will be called for every line. This is
451 -- equivalent to a Pattern_Callback function always returning True.
453 --------------------
454 -- Parse iterator --
455 --------------------
457 procedure Parse
461 -- Launch the iterator, it will read every line in all specified
462 -- session's files. Registered callbacks are then called if the associated
463 -- pattern match. It is possible to specify a filename and a set of
464 -- separators directly. This offer a quick way to parse a single
465 -- file. These parameters will override those specified by Set_FS and
466 -- Add_File. The Session will be opened and closed automatically.
467 -- File_Error is raised if there is no file associated with Session, or if
468 -- a file associated with Session is not longer readable. It raises
469 -- Session_Error is Session is already open.
471 -----------------------------------
472 -- Get_Line/End_Of_Data Iterator --
473 -----------------------------------
476 -- These mode are used for Get_Line/End_Of_Data and For_Every_Line
477 -- iterators. The associated semantic is:
478 --
479 -- None
480 -- callbacks are not active. This is the default mode for
481 -- Get_Line/End_Of_Data and For_Every_Line iterators.
482 --
483 -- Only
484 -- callbacks are active, if at least one pattern match, the associated
485 -- action is called and this line will not be passed to the user. In
486 -- the Get_Line case the next line will be read (if there is some
487 -- line remaining), in the For_Every_Line case Action will
488 -- not be called for this line.
489 --
490 -- Pass_Through
491 -- callbacks are active, for patterns which match the associated
492 -- action is called. Then the line is passed to the user. It means
493 -- that Action procedure is called in the For_Every_Line case and
494 -- that Get_Line returns with the current line active.
495 --
497 procedure Open
501 -- Open the first file and initialize the unit. This must be called once
502 -- before using Get_Line. It is possible to specify a filename and a set of
503 -- separators directly. This offer a quick way to parse a single file.
504 -- These parameters will override those specified by Set_FS and Add_File.
505 -- File_Error is raised if there is no file associated with Session, or if
506 -- the first file associated with Session is no longer readable. It raises
507 -- Session_Error is Session is already open.
509 procedure Get_Line
512 -- Read a line from the current input file. If the file index is at the
513 -- end of the current input file (i.e. End_Of_File is True) then the
514 -- following file is opened. If there is no more file to be processed,
515 -- exception End_Error will be raised. File_Error will be raised if Open
516 -- has not been called. Next call to Get_Line will return the following
517 -- line in the file. By default the registered callbacks are not called by
518 -- Get_Line, this can activated by setting Callbacks (see Callback_Mode
519 -- description above). File_Error may be raised if a file associated with
520 -- Session is not readable.
521 --
522 -- When Callbacks is not None, it is possible to exhaust all the lines
523 -- of all the files associated with Session. In this case, File_Error
524 -- is not raised.
525 --
526 -- This procedure can be used from a subprogram called by procedure Parse
527 -- or by an instantiation of For_Every_Line (see below).
529 function End_Of_Data
533 -- Returns True if there is no more data to be processed in Session. It
534 -- means that the latest session's file is being processed and that
535 -- there is no more data to be read in this file (End_Of_File is True).
537 function End_Of_File
541 -- Returns True when there is no more data to be processed on the current
542 -- session's file.
545 -- Release all associated data with Session. All memory allocated will
546 -- be freed, the current file will be closed if needed, the callbacks
547 -- will be unregistered. Close is convenient in reestablishing a session
548 -- for new use. Get_Line is no longer usable (will raise File_Error)
549 -- except after a successful call to Open, Parse or an instantiation
550 -- of For_Every_Line.
552 -----------------------------
553 -- For_Every_Line iterator --
554 -----------------------------
556 generic
558 procedure For_Every_Line
563 -- This is another iterator. Action will be called for each new
564 -- record. The iterator's termination can be controlled by setting Quit
565 -- to True. It is by default set to False. It is possible to specify a
566 -- filename and a set of separators directly. This offer a quick way to
567 -- parse a single file. These parameters will override those specified by
568 -- Set_FS and Add_File. By default the registered callbacks are not called
569 -- by For_Every_Line, this can activated by setting Callbacks (see
570 -- Callback_Mode description above). The Session will be opened and
571 -- closed automatically. File_Error is raised if there is no file
572 -- associated with Session. It raises Session_Error is Session is already
573 -- open.
575 private