1------------------------------------------------------------------------------
2--                                                                          --
3--                            Matreshka Project                             --
4--                                                                          --
5--                               XML Processor                              --
6--                                                                          --
7--                        Runtime Library Component                         --
8--                                                                          --
9------------------------------------------------------------------------------
10--                                                                          --
11-- Copyright © 2011-2012, Vadim Godunko <vgodunko@gmail.com>                --
12-- All rights reserved.                                                     --
13--                                                                          --
14-- Redistribution and use in source and binary forms, with or without       --
15-- modification, are permitted provided that the following conditions       --
16-- are met:                                                                 --
17--                                                                          --
18--  * Redistributions of source code must retain the above copyright        --
19--    notice, this list of conditions and the following disclaimer.         --
20--                                                                          --
21--  * Redistributions in binary form must reproduce the above copyright     --
22--    notice, this list of conditions and the following disclaimer in the   --
23--    documentation and/or other materials provided with the distribution.  --
24--                                                                          --
25--  * Neither the name of the Vadim Godunko, IE nor the names of its        --
26--    contributors may be used to endorse or promote products derived from  --
27--    this software without specific prior written permission.              --
28--                                                                          --
29-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS      --
30-- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT        --
31-- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR    --
32-- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT     --
33-- HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   --
34-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED --
35-- TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR   --
36-- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF   --
37-- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING     --
38-- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS       --
39-- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.             --
40--                                                                          --
41------------------------------------------------------------------------------
42--  $Revision: 3157 $ $Date: 2012-10-08 21:07:31 +0400 (Mon, 08 Oct 2012) $
43------------------------------------------------------------------------------
44--  This package provides implementation of SAX events handler to load XML
45--  Catalogs data into internal representation.
46------------------------------------------------------------------------------
47private with League.Strings;
48private with XML.SAX.Attributes;
49with XML.SAX.Content_Handlers;
50with XML.SAX.Error_Handlers;
51with XML.SAX.Lexical_Handlers;
52private with XML.SAX.Locators;
53private with XML.SAX.Parse_Exceptions;
54
55with Matreshka.XML_Catalogs.Entry_Files;
56
57package Matreshka.XML_Catalogs.Handlers is
58
59   type XML_Catalog_Handler is
60     limited new XML.SAX.Content_Handlers.SAX_Content_Handler
61       and XML.SAX.Error_Handlers.SAX_Error_Handler
62       and XML.SAX.Lexical_Handlers.SAX_Lexical_Handler with private;
63
64   function Get_Catalog_Entry_File
65    (Self : XML_Catalog_Handler)
66       return Matreshka.XML_Catalogs.Entry_Files.Catalog_Entry_File_Access;
67
68   procedure Set_Default_Prefer_Mode
69    (Self : in out XML_Catalog_Handler'Class;
70     Mode : Matreshka.XML_Catalogs.Entry_Files.Prefer_Mode);
71
72private
73
74   type XML_Catalog_Handler is
75     limited new XML.SAX.Content_Handlers.SAX_Content_Handler
76       and XML.SAX.Error_Handlers.SAX_Error_Handler
77       and XML.SAX.Lexical_Handlers.SAX_Lexical_Handler with
78   record
79      Default_Prefer_Mode  : Matreshka.XML_Catalogs.Entry_Files.Prefer_Mode
80        := Matreshka.XML_Catalogs.Entry_Files.Public;
81      --  Default prefer mode.
82
83      Current_Prefer_Mode  : Matreshka.XML_Catalogs.Entry_Files.Prefer_Mode;
84      Previous_Prefer_Mode : Matreshka.XML_Catalogs.Entry_Files.Prefer_Mode;
85      --  Preference mode can be defined for two grouping elements: "catalog"
86      --  and "group". Current_Preference_Mode is active preference mode, and
87      --  Previous_Preference_Mode is used to save preference mode of "catalog"
88      --  element when "group" element is processed.
89
90      Entry_File :
91        Matreshka.XML_Catalogs.Entry_Files.Catalog_Entry_File_Access;
92      --  Constructed catalog entry file.
93
94      Locator : XML.SAX.Locators.SAX_Locator;
95      --  Document's locator. It is used to obtain base URI when necessary.
96
97      Diagnosis : League.Strings.Universal_String;
98      --  Error message of the last detected error.
99   end record;
100
101   overriding procedure End_Element
102    (Self           : in out XML_Catalog_Handler;
103     Namespace_URI  : League.Strings.Universal_String;
104     Local_Name     : League.Strings.Universal_String;
105     Qualified_Name : League.Strings.Universal_String;
106     Success        : in out Boolean);
107   --  The reader calls this function when it has parsed an end element tag
108   --  with the qualified name Qualified_Name, the local name Local_Name and
109   --  the namespace URI Namespace_URI. It is called even when element is
110   --  empty.
111   --
112   --  Namespace_URI and Local_Name is provided only when namespace handling
113   --  is enabled, otherwise they are an empty strings.
114   --
115   --  If this subprogram sets Success to False the reader stops parsing and
116   --  reports an error. The reader uses the function Error_String to get the
117   --  error message.
118
119   overriding procedure Error
120    (Self       : in out XML_Catalog_Handler;
121     Occurrence : XML.SAX.Parse_Exceptions.SAX_Parse_Exception;
122     Success    : in out Boolean);
123
124   overriding function Error_String
125    (Self : XML_Catalog_Handler) return League.Strings.Universal_String;
126   --  The reader calls this function to get an error string, e.g. if any of
127   --  the handler subprograms sets Success to False.
128
129   overriding procedure Fatal_Error
130    (Self       : in out XML_Catalog_Handler;
131     Occurrence : XML.SAX.Parse_Exceptions.SAX_Parse_Exception);
132
133   overriding procedure Set_Document_Locator
134    (Self    : in out XML_Catalog_Handler;
135     Locator : XML.SAX.Locators.SAX_Locator);
136   --  The reader calls this subprogram before is starts parsing the document.
137   --  Argument Locator is object which allows the application to get the
138   --  parsing position within the document.
139   --
140   --  The locator allows the application to determine the end position of any
141   --  document-related event, even if the parser is not reporting an error.
142   --  Typically, the application will use this information for reporting its
143   --  own errors (such as character content that does not match an
144   --  application's business rules). The information returned by the locator
145   --  is probably not sufficient for use with a search engine.
146   --
147   --  Note that the locator will return correct information only during the
148   --  invocation SAX event callbacks after Start_Document returns and before
149   --  End_Document is called. The application should not attempt to use it at
150   --  any other time.
151
152   overriding procedure Start_Document
153    (Self    : in out XML_Catalog_Handler;
154     Success : in out Boolean);
155   --  The reader calls this subprogram when it starts parsing the document.
156   --  The reader calls this subprogram just once, after the call to
157   --  Set_Document_Locator, and before and other subprogram in this
158   --  interface or in the SAX_DTD_Handler interface are called.
159   --
160   --  If this subprogram sets Success to False the reader stops parsing and
161   --  reports an error. The reader uses the function Error_String to get the
162   --  error message.
163
164   overriding procedure Start_DTD
165    (Self      : in out XML_Catalog_Handler;
166     Name      : League.Strings.Universal_String;
167     Public_Id : League.Strings.Universal_String;
168     System_Id : League.Strings.Universal_String;
169     Success   : in out Boolean);
170   --  The reader calls this subprogram to report the start of a DTD
171   --  declaration, if any. It reports the name of the document type in Name,
172   --  the public identifier in Public_Id and the system identifier in
173   --  System_Id.
174   --
175   --  If the public identifier is missing, Public_Id is set to an empty
176   --  string. If the system identifier is missing, System_Id is set to an
177   --  empty string. Note that it is not valid XML to have a public identifier
178   --  but no system identifier; in such cases a parse error will occur.
179   --
180   --  This subprogram is intended to report the beginning of the DOCTYPE
181   --  declaration; if the document has no DOCTYPE declaration, this subprogram
182   --  will not be invoked.
183   --
184   --  All declarations reported through SAX_DTD_Handler or SAX_Decl_Handler
185   --  appear between the Start_DTD and End_DTD calls. Declarations belong to
186   --  the internal DTD subsets unless they appear between Start_Entity and
187   --  End_Entity calls. Comments and processing instructions from the DTD also
188   --  are reported between the Start_DTD and End_DTD calls, in their original
189   --  order of (logical) occurrence; they are not appear in their correct
190   --  locations relative to others calls of SAX_DTD_Handler or
191   --  SAX_Decl_Handler, however.
192   --
193   --  Note that the Start_DTD/End_DTD calls will appear within the
194   --  Start_Document/End_Document calls from SAX_Content_Handler and before
195   --  the first Start_Element event.
196   --
197   --  If this subprogram sets Success to False the reader stops parsing and
198   --  reports an error. The reader uses the function Error_String to get the
199   --  error message.
200
201   overriding procedure Start_Element
202    (Self           : in out XML_Catalog_Handler;
203     Namespace_URI  : League.Strings.Universal_String;
204     Local_Name     : League.Strings.Universal_String;
205     Qualified_Name : League.Strings.Universal_String;
206     Attributes     : XML.SAX.Attributes.SAX_Attributes;
207     Success        : in out Boolean);
208   --  The reader calls this subprogram when it has parsed a start element tag.
209   --
210   --  There is a corresponding End_Element call when the corresponding and
211   --  element tag is read. The Start_Element and End_Element calls are always
212   --  nested correctly. Empty element tags (e.g. <x/>) cause a Start_Element
213   --  call to be immediately followed by and End_Element call.
214   --
215   --  The attribute list provided only contains attributes with explicit
216   --  values (specified or defaulted): #IMPLIED attributes will be omitted.
217   --  The attribute list contains attributes used for namespace
218   --  declaration (i.e. attributes starting with xmlns) only if the
219   --  http://xml.org/sax/features/namespace-prefixes property of the reader is
220   --  true.
221   --
222   --  The argument Namespace_URI is the namespace URI, or an empty string if
223   --  the element has no namespace URI or if no namespace processing is done.
224   --  Local_Name is the local name (without prefix), or an empty string if no
225   --  namespace processing is done, Qualified_Name is the qualified name (with
226   --  prefix) and Attributes are the attributes attached to the element. If
227   --  there are no attributes, Attributes is an empty attributes object.
228   --
229   --  If this subprogram sets Success to False the reader stops parsing and
230   --  reports an error. The reader uses the function Error_String to get the
231   --  error message.
232
233   overriding procedure Warning
234    (Self       : in out XML_Catalog_Handler;
235     Occurrence : XML.SAX.Parse_Exceptions.SAX_Parse_Exception;
236     Success    : in out Boolean);
237
238end Matreshka.XML_Catalogs.Handlers;
239