← Back to branch summary

~ubuntu-branches/ubuntu/karmic/gnustep-base/karmic

« back to all changes in this revision

Viewing changes to Documentation/gsdoc/GSXMLParser.gsdoc

  • Committer: Bazaar Package Importer
  • Author(s): Eric Heintzmann
  • Date: 2005-04-17 00:14:38 UTC
  • mfrom: (1.2.1 upstream) (2.1.2 hoary)
  • Revision ID: james.westby@ubuntu.com-20050417001438-enf0y07c9tku85z1
Tags: 1.10.3-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/gsdoc/GSXMLParser.gsdoc
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
3
 
<gsdoc base="GSXMLParser" prev="GSXMLAttribute" up="GSXML" next="GSSAXHandler">
4
 
  <head>
5
 
    <title>GSXMLParser</title>
6
 
    <author name="Michael Pakhantsov">
7
 
      <email address="mishel@berest.dp.ua"/>
8
 
    </author>
9
 
    <author name="Richard Frith-Macdonald">
10
 
      <email address="rfm@gnu.org"/>
11
 
    </author>
12
 
    <version>$Revision: 1.9 $</version>
13
 
    <date>$Date: 2001/03/03 09:58:53 $</date>
14
 
  </head>
15
 
 
16
 
  <body>
17
 
    <chapter>
18
 
      <heading>GSXMLParser</heading>
19
 
      <class name="GSXMLParser" super="NSObject">
20
 
        <declared>GSXML.h</declared>
21
 
          <desc>
22
 
            <p>
23
 
              The XML parser object is the pivotal part of parsing an XML
24
 
              document - it will either build a tree representing the
25
 
              document (if initialized without a GSSAXHandler), or will
26
 
              cooperate with a GSSAXHandler object to provide parsing
27
 
              without the overhead of building a tree.
28
 
            </p>
29
 
            <p>
30
 
              The parser may be initialized with an input source (in which
31
 
              case it will expect to be asked to parse the entire input in
32
 
              a single operation), or without.  If it is initialised without
33
 
              an input source, incremental parsing can be done by feeding
34
 
              successive parts of the XML document into the parser as
35
 
              NSData objects.
36
 
            </p>
37
 
          </desc>
38
 
 
39
 
        <method type="NSString*" factory="yes">
40
 
          <sel>loadEntity:</sel>
41
 
          <arg type="NSString*">publicID</arg>
42
 
          <sel>at:</sel>
43
 
          <arg type="NSString*">locationURL</arg>
44
 
          <desc>
45
 
            <p>
46
 
              This method controls the loading of external entities into
47
 
              the system.  If it returns an empty string, the entity is not
48
 
              loaded.  If it returns a filename, the entity is loaded from
49
 
              that file.  If it returns nil, the default entity loading
50
 
              mechanism is used.
51
 
            </p>
52
 
            <p>
53
 
              The default entity loading mechanism is to construct a file
54
 
              name from the locationURL, by replacing all path separators
55
 
              with underscores, then attempt to locate that file in the DTDs
56
 
              resource directory of the main bundle, and all the standard
57
 
              system locations.
58
 
            </p>
59
 
            <p>
60
 
              As a special case, the default loader examines the publicID
61
 
              and if it is a GNUstep DTD, the loader constructs a special
62
 
              name from the ID (by replacing dots with underscores and
63
 
              spaces with hyphens) and looks for a file with that name
64
 
              and a '.dtd' extension in the GNUstep bundles.
65
 
            </p>
66
 
            <p>
67
 
              NB. This method will only be called if there is no SAX
68
 
              handler in use, or if the corresponding method in the
69
 
              SAX handler returns nil.
70
 
            </p>
71
 
          </desc>
72
 
        </method>
73
 
 
74
 
        <method type="GSXMLParser*" factory="yes">
75
 
          <sel>parser</sel>
76
 
          <desc>
77
 
            <p>
78
 
              Creation of a new Parser (for incremental parsing)
79
 
              by calling initWithSAXHandler:
80
 
            </p>
81
 
          </desc>
82
 
        </method>
83
 
 
84
 
        <method type="GSXMLParser*" factory="yes">
85
 
          <sel>parserWithContentsOfFile:</sel>
86
 
          <arg type="NSString*">path</arg>
87
 
          <desc>
88
 
            <p>
89
 
              Creation of a new Parser by calling
90
 
              initWithSAXHandler:withContentsOfFile:
91
 
            </p>
92
 
            <example>
93
 
  GSXMLParser       *p = [GSXMLParser parserWithContentsOfFile: @"macos.xml"];
94
 
 
95
 
  if ([p parse])
96
 
    {
97
 
      [[p doc] dump];
98
 
    }
99
 
  else
100
 
    {
101
 
      printf("error parse file\n");
102
 
    }
103
 
 
104
 
            </example>
105
 
          </desc>
106
 
        </method>
107
 
 
108
 
        <method type="GSXMLParser*" factory="yes">
109
 
          <sel>parserWithContentsOfURL:</sel>
110
 
          <arg type="NSURL*">url</arg>
111
 
          <desc>
112
 
            <p>
113
 
              Creation of a new Parser by calling
114
 
              initWithSAXHandler:withContentsOfURL:
115
 
            </p>
116
 
          </desc>
117
 
        </method>
118
 
 
119
 
        <method type="GSXMLParser*" factory="yes">
120
 
          <sel>parserWithData:</sel>
121
 
          <arg type="NSData*">data</arg>
122
 
          <desc>
123
 
            <p>Creation of a new Parser by calling
124
 
              initWithSAXHandler:withData:
125
 
            </p>
126
 
          </desc>
127
 
        </method>
128
 
 
129
 
        <method type="GSXMlParser*" factory="yes">
130
 
          <sel>parserWithSAXHandler:</sel>
131
 
          <arg type="GSSAXHandler*">handler</arg>
132
 
          <desc>
133
 
            <p>
134
 
              Creation of a new Parser by calling initWithSAXHandler:
135
 
            </p>
136
 
            <p>
137
 
              If the handler object supplied is nil, the parser will build
138
 
              a tree representing the parsed file rather than attempting
139
 
              to get the handler to deal with the parsed elements and entities.
140
 
            </p>
141
 
          </desc>
142
 
        </method>
143
 
 
144
 
        <method type="GSXMlParser*" factory="yes">
145
 
          <sel>parserWithSAXHandler:</sel>
146
 
          <arg type="GSSAXHandler*">handler</arg>
147
 
          <sel>withContentsOfFile:</sel>
148
 
          <arg type="NSString*">path</arg>
149
 
          <desc>
150
 
            <p>
151
 
              Creation of a new Parser by calling
152
 
              initWithSAXHandler:withContentsOfFile:
153
 
            </p>
154
 
            <example>
155
 
  NSAutoreleasePool *arp = [[NSAutoreleasePool alloc] init];
156
 
  GSSAXHandler *h = [GSDebugSAXHandler handler];
157
 
  GSXMLParser       *p = [GSXMLParser parserWithSAXHandler: h
158
 
                                        withContentsOfFile: @"macos.xml"];
159
 
 
160
 
  if ([p parse])
161
 
    {
162
 
       printf("ok\n");
163
 
    }
164
 
 
165
 
 
166
 
  [arp release];
167
 
            </example>
168
 
          </desc>
169
 
        </method>
170
 
 
171
 
        <method type="GSXMlParser*" factory="yes">
172
 
          <sel>parserWithSAXHandler:</sel>
173
 
          <arg type="GSSAXHandler*">handler</arg>
174
 
          <sel>withContentsOfURL:</sel>
175
 
          <arg type="NSURL*">url</arg>
176
 
          <desc>
177
 
            <p>
178
 
              Creation of a new Parser by calling
179
 
              initWithSAXHandler:withContentsOfURL:
180
 
            </p>
181
 
          </desc>
182
 
        </method>
183
 
 
184
 
        <method type="GSXMlParser*" factory="yes">
185
 
          <sel>parserWithSAXHandler:</sel>
186
 
          <arg type="GSSAXHandler*">handler</arg>
187
 
          <sel>withData:</sel>
188
 
          <arg type="NSData*">data</arg>
189
 
          <desc>
190
 
            <p>
191
 
              Creation of a new Parser by calling
192
 
              initWithSAXHandler:withData:
193
 
            </p>
194
 
          </desc>
195
 
        </method>
196
 
 
197
 
        <method type="NSString*" factory="yes">
198
 
          <sel>xmlEncodingStringForStringEncoding:</sel>
199
 
          <arg type="NSStringEncoding">encoding</arg>
200
 
          <desc>
201
 
            Return the name of the string encoding (for XML) to use for the
202
 
            specified OpenStep encoding.
203
 
          </desc>
204
 
        </method>
205
 
 
206
 
        <method type="id" init="yes">
207
 
          <sel>initWithSAXHandler:</sel>
208
 
          <arg type="GSSAXHandler*">handler</arg>
209
 
          <desc>
210
 
            <p>
211
 
               Initialisation of a new Parser with SAX handler (if not nil).
212
 
            </p>
213
 
            <p>
214
 
              If the handler object supplied is nil, the parser will build
215
 
              a tree representing the parsed file rather than attempting
216
 
              to get the handler to deal with the parsed elements and entities.
217
 
            </p>
218
 
            <p>
219
 
              The source for the parsing process is not specified - so
220
 
              parsing must be done incrementally by feeding data to the
221
 
              parser.
222
 
            </p>
223
 
          </desc>
224
 
        </method>
225
 
 
226
 
        <method type="id">
227
 
          <sel>initWithSAXHandler:</sel>
228
 
          <arg type="GSSAXHandler*">handler</arg>
229
 
          <sel>withContentsOfFile:</sel>
230
 
          <arg type="NSString*">path</arg>
231
 
          <desc>
232
 
            <p>
233
 
              Initialisation of a new Parser with SAX handler (if not nil)
234
 
              by calling initWithSAXHandler:
235
 
            </p>
236
 
            <p>
237
 
              Sets the input source for the parser to be the specified file -
238
 
              so parsing of the entire file will be performed rather than
239
 
              incremental parsing.
240
 
            </p>
241
 
          </desc>
242
 
        </method>
243
 
 
244
 
        <method type="id">
245
 
          <sel>initWithSAXHandler:</sel>
246
 
          <arg type="GSSAXHandler*">handler</arg>
247
 
          <sel>withContentsOfURL:</sel>
248
 
          <arg type="NSURL*">url</arg>
249
 
          <desc>
250
 
            <p>
251
 
              Initialisation of a new Parser with SAX handler (if not nil)
252
 
              by calling initWithSAXHandler:
253
 
            </p>
254
 
            <p>
255
 
              Sets the input source for the parser to be the specified URL -
256
 
              so parsing of the entire document will be performed rather than
257
 
              incremental parsing.
258
 
            </p>
259
 
          </desc>
260
 
        </method>
261
 
 
262
 
        <method type="id">
263
 
          <sel>initWithSAXHandler:</sel>
264
 
          <arg type="GSSAXHandler*">handler</arg>
265
 
          <sel>withData:</sel>
266
 
          <arg type="NSData*">data</arg>
267
 
          <desc>
268
 
            <p>
269
 
              Initialisation of a new Parser with SAX handler (if not nil)
270
 
              by calling initWithSAXHandler:
271
 
            </p>
272
 
            <p>
273
 
              Sets the input source for the parser to be the specified data
274
 
              object (which must contain an XML document), so parsing of the
275
 
              entire document will be performed rather than incremental parsing.
276
 
            </p>
277
 
          </desc>
278
 
        </method>
279
 
 
280
 
        <method type="void*">
281
 
          <sel>lib</sel>
282
 
          <desc>
283
 
            <p>Return pointer to xmlParserCtxt structure.
284
 
            </p>
285
 
          </desc>
286
 
        </method>
287
 
 
288
 
        <method type="GSXMLDocument*">
289
 
          <sel>doc</sel>
290
 
          <desc>
291
 
            <p>
292
 
              Return GSXMLDocument object.
293
 
            </p>
294
 
          </desc>
295
 
        </method>
296
 
 
297
 
        <method type="BOOL">
298
 
          <sel>parse</sel>
299
 
          <desc>
300
 
            <p>
301
 
              Parse source. Return YES if parsed, otherwise NO.
302
 
              This method should be called once to parse the entire document.
303
 
            </p>
304
 
            <example>
305
 
  GSXMLParser       *p = [GSXMLParser parserWithContentsOfFile:@"macos.xml"];
306
 
 
307
 
  if ([p parse])
308
 
    {
309
 
      [[p doc] dump];
310
 
    }
311
 
  else
312
 
    {
313
 
      printf("error parse file\n");
314
 
    }
315
 
 
316
 
            </example>
317
 
          </desc>
318
 
        </method>
319
 
 
320
 
        <method type="BOOL">
321
 
          <sel>parse:</sel>
322
 
          <arg type="NSData*">data</arg>
323
 
          <desc>
324
 
            <p>
325
 
              Pass data to the parser for incremental parsing.  This method
326
 
              should be called many times, with each call passing another
327
 
              block of data from the same document.  After the whole of the
328
 
              document has been parsed, the method should be called with
329
 
              an empty or nil data object to indicate end of parsing.
330
 
              On this final call, the return value indicates whether the
331
 
              document was valid or not.
332
 
            </p>
333
 
            <example>
334
 
  GSXMLParser       *p = [GSXMLParser parserWithSAXHandler: nil source: nil];
335
 
 
336
 
  while ((data = getMoreData()) != nil)
337
 
    {
338
 
      if ([p parse: data] == NO)
339
 
        {
340
 
          NSLog(@"parse error");
341
 
        }
342
 
    }
343
 
    // Do something with document parsed
344
 
 
345
 
    [p parse: nil];  // Completed parsing of document.
346
 
 
347
 
            </example>
348
 
          </desc>
349
 
        </method>
350
 
 
351
 
        <method type="BOOL">
352
 
          <sel>substituteEntites:</sel>
353
 
          <arg type="BOOL">yesno</arg>
354
 
          <desc>
355
 
          <p>
356
 
            Set and return the previous value for entity support.
357
 
            Initially the parser always keeps entity references instead
358
 
            of substituting entity values in the output.
359
 
          </p>
360
 
          </desc>
361
 
        </method>
362
 
 
363
 
        <method type="BOOL">
364
 
          <sel>keepBlanks:</sel>
365
 
          <arg type="BOOL">yesno</arg>
366
 
          <desc>
367
 
            <p>
368
 
              Set and return the previous value for blank text nodes support.
369
 
              ignorableWhitespace() are only generated when running
370
 
              the parser in validating mode and when the current element
371
 
              doesn't allow CDATA or mixed content.
372
 
            </p>
373
 
          </desc>
374
 
        </method>
375
 
 
376
 
        <method type="BOOL">
377
 
          <sel>getWarnings:</sel>
378
 
          <arg type="BOOL">yesno</arg>
379
 
          <desc>
380
 
          </desc>
381
 
        </method>
382
 
 
383
 
        <method type="BOOL">
384
 
          <sel>doValidityChecking:</sel>
385
 
          <arg type="BOOL">yesno</arg>
386
 
          <desc>
387
 
            <p>
388
 
              Sets whether the document needs to be validated.
389
 
            </p>
390
 
          </desc>
391
 
        </method>
392
 
 
393
 
        <method type="int">
394
 
          <sel>errNo</sel>
395
 
          <desc>
396
 
            <p>
397
 
              Return error code for last parse operation.
398
 
            </p>
399
 
          </desc>
400
 
        </method>
401
 
      </class>
402
 
    </chapter>
403
 
  </body>
404
 
</gsdoc>
405