home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _70107d902c451c5e62691276628a3431 < prev    next >
Text File  |  2000-03-23  |  19KB  |  394 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>SGMLS - class for postprocessing the output from the B<sgmls> and
  5. B<nsgmls> parsers.</TITLE>
  6. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  7. <LINK REV="made" HREF="mailto:">
  8. </HEAD>
  9.  
  10. <BODY>
  11. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  12. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  13. <STRONG><P CLASS=block> SGMLS - class for postprocessing the output from the B<sgmls> and
  14. B<nsgmls> parsers.</P></STRONG>
  15. </TD></TR>
  16. </TABLE>
  17.  
  18. <A NAME="__index__"></A>
  19. <!-- INDEX BEGIN -->
  20.  
  21. <UL>
  22.  
  23.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  24.  
  25.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  26.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  27.     <UL>
  28.  
  29.         <LI><A HREF="#the sgmls class">The <CODE>SGMLS</CODE> class</A></LI>
  30.         <LI><A HREF="#the sgmls_event class">The <CODE>SGMLS_Event</CODE> class</A></LI>
  31.         <LI><A HREF="#the sgmls_element class">The <CODE>SGMLS_Element</CODE> class</A></LI>
  32.         <LI><A HREF="#the sgmls_attribute class">The <CODE>SGMLS_Attribute</CODE> class</A></LI>
  33.         <LI><A HREF="#the sgmls_notation class">The <CODE>SGMLS_Notation</CODE> class</A></LI>
  34.         <LI><A HREF="#the sgmls_entity class">The <CODE>SGMLS_Entity</CODE> class</A></LI>
  35.     </UL>
  36.  
  37.     <LI><A HREF="#author and copyright">AUTHOR AND COPYRIGHT</A></LI>
  38.     <LI><A HREF="#see also:">SEE ALSO:</A></LI>
  39. </UL>
  40. <!-- INDEX END -->
  41.  
  42. <HR>
  43. <P>
  44. <H1><A NAME="name">NAME</A></H1>
  45. <P>SGMLS - class for postprocessing the output from the <STRONG>sgmls</STRONG> and
  46. <STRONG>nsgmls</STRONG> parsers.</P>
  47. <P>
  48. <HR>
  49. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  50. <UL>
  51. <LI>Windows</LI>
  52. </UL>
  53. <HR>
  54. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  55. <PRE>
  56.   use SGMLS;</PRE>
  57. <PRE>
  58.   my $parse = new SGMLS(STDIN);</PRE>
  59. <PRE>
  60.   my $event = $parse->next_event;
  61.   while ($event) {</PRE>
  62. <PRE>
  63.     SWITCH: {</PRE>
  64. <PRE>
  65.       ($event->type eq 'start_element') && do {
  66.         my $element = $event->data;    # An object of class SGMLS_Element
  67.         [[your code for the beginning of an element]]
  68.         last SWITCH;
  69.       };</PRE>
  70. <PRE>
  71.       ($event->type eq 'end_element') && do {
  72.         my $element = $event->data;    # An object of class SGMLS_Element
  73.         [[your code for the end of an element]]
  74.         last SWITCH;
  75.       };</PRE>
  76. <PRE>
  77.       ($event->type eq 'cdata') && do {
  78.         my $cdata = $event->data;      # A string
  79.         [[your code for character data]]
  80.         last SWITCH;
  81.       };</PRE>
  82. <PRE>
  83.       ($event->type eq 'sdata') && do {
  84.         my $sdata = $event->data;      # A string
  85.         [[your code for system data]]
  86.         last SWITCH;
  87.       };</PRE>
  88. <PRE>
  89.       ($event->type eq 're') && do {
  90.         [[your code for a record end]]
  91.         last SWITCH;
  92.       };</PRE>
  93. <PRE>
  94.       ($event->type eq 'pi') && do {
  95.         my $pi = $event->data;         # A string
  96.         [[your code for a processing instruction]]
  97.         last SWITCH;
  98.       };</PRE>
  99. <PRE>
  100.       ($event->type eq 'entity') && do {
  101.         my $entity = $event->data;     # An object of class SGMLS_Entity
  102.         [[your code for an external entity]]
  103.         last SWITCH;
  104.       };</PRE>
  105. <PRE>
  106.       ($event->type eq 'start_subdoc') && do {
  107.         my $entity = $event->data;     # An object of class SGMLS_Entity
  108.         [[your code for the beginning of a subdoc entity]]
  109.         last SWITCH;
  110.       };</PRE>
  111. <PRE>
  112.       ($event->type eq 'end_subdoc') && do {
  113.         my $entity = $event->data;     # An object of class SGMLS_Entity
  114.         [[your code for the end of a subdoc entity]]
  115.         last SWITCH;
  116.       };</PRE>
  117. <PRE>
  118.       ($event->type eq 'conforming') && do {
  119.         [[your code for a conforming document]]
  120.         last SWITCH;
  121.       };</PRE>
  122. <PRE>
  123.       die "Internal error: unknown event type " . $event->type . "\n";
  124.     }</PRE>
  125. <PRE>
  126.     $event = $parse->next_event;
  127.   }</PRE>
  128. <P>
  129. <HR>
  130. <H1><A NAME="description">DESCRIPTION</A></H1>
  131. <P>The <STRONG>SGMLS</STRONG> package consists of several related classes: see
  132. <A HREF="#sgmls">SGMLS</A>, <A HREF="#sgmls_event">SGMLS_Event</A>, <A HREF="#sgmls_element">SGMLS_Element</A>,
  133. <A HREF="#sgmls_attribute">SGMLS_Attribute</A>, <A HREF="#sgmls_notation">SGMLS_Notation</A>, and <A HREF="#sgmls_entity">SGMLS_Entity</A>.  All
  134. of these classes are available when you specify</P>
  135. <PRE>
  136.   use SGMLS;</PRE>
  137. <P>Generally, the only object which you will create explicitly will
  138. belong to the <CODE>SGMLS</CODE> class; all of the others will then be created
  139. automatically for you over the course of the parse.  Much fuller
  140. documentation is available in the <CODE>.sgml</CODE> files in the <CODE>DOC/</CODE>
  141. directory of the <CODE>SGMLS.pm</CODE> distribution.</P>
  142. <P>
  143. <H2><A NAME="the sgmls class">The <CODE>SGMLS</CODE> class</A></H2>
  144. <P>This class holds a single parse.  When you create an instance of it,
  145. you specify a file handle as an argument (if you are reading the
  146. output of <STRONG>sgmls</STRONG> or <STRONG>nsgmls</STRONG> from a pipe, the file handle will
  147. ordinarily be <CODE>STDIN</CODE>):</P>
  148. <PRE>
  149.   my $parse = new SGMLS(STDIN);</PRE>
  150. <P>The most important method for this class is <A HREF="#item_next_event"><CODE>next_event</CODE></A>, which reads
  151. and returns the next major event from the input stream.  It is
  152. important to note that the <CODE>SGMLS</CODE> class deals with most <STRONG>ESIS</STRONG>
  153. events itself: attributes and entity definitions, for example, are
  154. collected and stored automatically and invisibly to the user.  The
  155. following list contains all of the methods for the <CODE>SGMLS</CODE> class:</P>
  156. <DL>
  157. <DT><STRONG><A NAME="item_next_event"><CODE>next_event()</CODE>: Return an <CODE>SGMLS_Event</CODE> object containing the
  158. next major event from the SGML parse.</A></STRONG><BR>
  159. <DD>
  160. <DT><STRONG><A NAME="item_element"><CODE>element()</CODE>: Return an <CODE>SGMLS_Element</CODE> object containing the
  161. current element in the document.</A></STRONG><BR>
  162. <DD>
  163. <DT><STRONG><A NAME="item_file"><CODE>file()</CODE>: Return a string containing the name of the current
  164. SGML source file (this will work only if the <CODE>-l</CODE> option was given to
  165. <STRONG>sgmls</STRONG> or <STRONG>nsgmls</STRONG>).</A></STRONG><BR>
  166. <DD>
  167. <DT><STRONG><A NAME="item_line"><CODE>line()</CODE>: Return a string containing the current line number
  168. from the source file (this will work only if the <CODE>-l</CODE> option was
  169. given to <STRONG>sgmls</STRONG> or <STRONG>nsgmls</STRONG>).</A></STRONG><BR>
  170. <DD>
  171. <DT><STRONG><A NAME="item_appinfo"><CODE>appinfo()</CODE>: Return a string containing the <CODE>APPINFO</CODE>
  172. parameter (if any) from the SGML declaration.</A></STRONG><BR>
  173. <DD>
  174. <DT><STRONG><A NAME="item_notation"><CODE>notation(NNAME)</CODE>: Return an <CODE>SGMLS_Notation</CODE> object
  175. representing the notation named <CODE>NNAME</CODE>.  With newer versions of
  176. <STRONG>nsgmls</STRONG>, all notations are available; otherwise, only the notations
  177. which are actually used will be available.</A></STRONG><BR>
  178. <DD>
  179. <DT><STRONG><A NAME="item_entity"><CODE>entity(ENAME)</CODE>: Return an <CODE>SGMLS_Entity</CODE> object representing
  180. the entity named <CODE>ENAME</CODE>.  With newer versions of <STRONG>nsgmls</STRONG>, all
  181. entities are available; otherwise, only external data entities and
  182. internal entities used as attribute values will be available.</A></STRONG><BR>
  183. <DD>
  184. <DT><STRONG><A NAME="item_ext"><CODE>ext()</CODE>: Return a reference to an associative array for
  185. user-defined extensions.</A></STRONG><BR>
  186. <DD>
  187. </DL>
  188. <P>
  189. <H2><A NAME="the sgmls_event class">The <CODE>SGMLS_Event</CODE> class</A></H2>
  190. <P>This class holds a single major event, as generated by the
  191. <A HREF="#item_next_event"><CODE>next_event</CODE></A> method in the <CODE>SGMLS</CODE> class.  It uses the following
  192. methods:</P>
  193. <DL>
  194. <DT><STRONG><A NAME="item_type"><CODE>type()</CODE>: Return a string describing the type of event:
  195. ``start_element'', ``end_element'', ``cdata'', ``sdata'', ``re'', ``pi'',
  196. ``entity'', ``start_subdoc'', ``end_subdoc'', and ``conforming''.  See
  197. <A HREF="#synopsis">SYNOPSIS</A>, above, for the values associated with each of these.</A></STRONG><BR>
  198. <DD>
  199. <DT><STRONG><A NAME="item_data"><CODE>data()</CODE>: Return the data associated with the current event (if
  200. any).  For ``start_element'' and ``end_element'', returns an
  201. <CODE>SGMLS_ELement</CODE> object; for ``entity'', ``start_subdoc'', and
  202. ``end_subdoc'', returns an <CODE>SGMLS_Entity</CODE> object; for ``cdata'', ``sdata'',
  203. and ``pi'', returns a string; and for ``re'' and ``conforming'', returns the
  204. empty string.  See <A HREF="#synopsis">SYNOPSIS</A>, above, for an example of this
  205. method's use.</A></STRONG><BR>
  206. <DD>
  207. <DT><STRONG><A NAME="item_key"><CODE>key()</CODE>: Return a string key to the event, such as an element
  208. or entity name (otherwise, the same as <A HREF="#item_data"><CODE>data()</CODE></A>).</A></STRONG><BR>
  209. <DD>
  210. <DT><STRONG><CODE>file()</CODE>: Return the current file name, as in the <CODE>SGMLS</CODE>
  211. class.</STRONG><BR>
  212. <DD>
  213. <DT><STRONG><CODE>line()</CODE>: Return the current line number, as in the <CODE>SGMLS</CODE>
  214. class.</STRONG><BR>
  215. <DD>
  216. <DT><STRONG><CODE>element()</CODE>: Return the current element, as in the <CODE>SGMLS</CODE>
  217. class.</STRONG><BR>
  218. <DD>
  219. <DT><STRONG><A NAME="item_parse"><CODE>parse()</CODE>: Return the <CODE>SGMLS</CODE> object which generated the
  220. event.</A></STRONG><BR>
  221. <DD>
  222. <DT><STRONG><CODE>entity(ENAME)</CODE>: Look up an entity, as in the <CODE>SGMLS</CODE> class.</STRONG><BR>
  223. <DD>
  224. <DT><STRONG><CODE>notation(ENAME)</CODE>: Look up a notation, as in the <CODE>SGMLS</CODE>
  225. class.</STRONG><BR>
  226. <DD>
  227. <DT><STRONG><CODE>ext()</CODE>: Return a reference to an associative array for
  228. user-defined extensions.</STRONG><BR>
  229. <DD>
  230. </DL>
  231. <P>
  232. <H2><A NAME="the sgmls_element class">The <CODE>SGMLS_Element</CODE> class</A></H2>
  233. <P>This class is used for elements, and contains all associated
  234. information (such as the element's attributes).  It recognises the
  235. following methods:</P>
  236. <DL>
  237. <DT><STRONG><A NAME="item_name"><CODE>name()</CODE>: Return a string containing the name, or Generic
  238. Identifier, of the element, in upper case.</A></STRONG><BR>
  239. <DD>
  240. <DT><STRONG><A NAME="item_parent"><CODE>parent()</CODE>: Return the <CODE>SGMLS_Element</CODE> object for the
  241. element's parent (if any).</A></STRONG><BR>
  242. <DD>
  243. <DT><STRONG><CODE>parse()</CODE>: Return the <CODE>SGMLS</CODE> object for the current parse.</STRONG><BR>
  244. <DD>
  245. <DT><STRONG><A NAME="item_attributes"><CODE>attributes()</CODE>: Return a reference to an associative array of
  246. attribute names and <CODE>SGMLS_Attribute</CODE> structures.  Attribute names
  247. will be all in upper case.</A></STRONG><BR>
  248. <DD>
  249. <DT><STRONG><A NAME="item_attribute_names"><CODE>attribute_names()</CODE>: Return an array of strings containing the
  250. names of all attributes defined for the current element, in upper
  251. case.</A></STRONG><BR>
  252. <DD>
  253. <DT><STRONG><A NAME="item_attribute"><CODE>attribute(ANAME)</CODE>: Return the <CODE>SGMLS_Attribute</CODE> structure for
  254. the attribute <CODE>ANAME</CODE>.</A></STRONG><BR>
  255. <DD>
  256. <DT><STRONG><A NAME="item_set_attribute"><CODE>set_attribute(ATTRIB)</CODE>: Add the <CODE>SGMLS_Attribute</CODE> object
  257. <CODE>ATTRIB</CODE> to the current element, replacing any other attribute
  258. structure with the same name.</A></STRONG><BR>
  259. <DD>
  260. <DT><STRONG><A NAME="item_in"><CODE>in(GI)</CODE>: Return <CODE>true</CODE> (ie. 1) if the string <CODE>GI</CODE> is the
  261. name of the current element's parent, or <CODE>false</CODE> (ie. 0) if it is
  262. not.</A></STRONG><BR>
  263. <DD>
  264. <DT><STRONG><A NAME="item_within"><CODE>within(GI)</CODE>: Return <CODE>true</CODE> (ie. 1) if the string <CODE>GI</CODE> is the
  265. name of any of the ancestors of the current element, or <CODE>false</CODE>
  266. (ie. 0) if it is not.</A></STRONG><BR>
  267. <DD>
  268. <DT><STRONG><CODE>ext()</CODE>: Return a reference to an associative array for
  269. user-defined extensions.</STRONG><BR>
  270. <DD>
  271. </DL>
  272. <P>
  273. <H2><A NAME="the sgmls_attribute class">The <CODE>SGMLS_Attribute</CODE> class</A></H2>
  274. <P>Each instance of an attribute for each <CODE>SGMLS_Element</CODE> is an object
  275. belonging to this class, which recognises the following methods:</P>
  276. <DL>
  277. <DT><STRONG><CODE>name()</CODE>: Return a string containing the name of the current
  278. attribute, all in upper case.</STRONG><BR>
  279. <DD>
  280. <DT><STRONG><CODE>type()</CODE>: Return a string containing the type of the current
  281. attribute, all in upper case.  Available types are ``IMPLIED'', ``CDATA'',
  282. ``NOTATION'', ``ENTITY'', and ``TOKEN''.</STRONG><BR>
  283. <DD>
  284. <DT><STRONG><A NAME="item_value"><CODE>value()</CODE>: Return the value of the current attribute, if any.
  285. This will be an empty string if the type is ``IMPLIED'', a string of
  286. some sort if the type is ``CDATA'' or ``TOKEN'' (if it is ``TOKEN'', you may
  287. want to split the string into a series of separate tokens), an
  288. <CODE>SGMLS_Notation</CODE> object if the type is ``NOTATION'', or an
  289. <CODE>SGMLS_Entity</CODE> object if the type is ``ENTITY''.  Note that if the
  290. value is ``CDATA'', it will <EM>not</EM> have escape sequences for 8-bit
  291. characters, record ends, or SDATA processed -- that will be your
  292. responsibility.</A></STRONG><BR>
  293. <DD>
  294. <DT><STRONG><A NAME="item_is_implied"><CODE>is_implied()</CODE>: Return <CODE>true</CODE> (ie. 1) if the value of the
  295. attribute is implied, or <CODE>false</CODE> (ie. 0) if it is specified in the
  296. document.</A></STRONG><BR>
  297. <DD>
  298. <DT><STRONG><A NAME="item_set_type"><CODE>set_type(TYPE)</CODE>: Change the type of the attribute to the
  299. string <CODE>TYPE</CODE> (which should be all in upper case).  Available types
  300. are ``IMPLIED'', ``CDATA'', ``NOTATION'', ``ENTITY'', and ``TOKEN''.</A></STRONG><BR>
  301. <DD>
  302. <DT><STRONG><A NAME="item_set_value"><CODE>set_value(VALUE)</CODE>: Change the value of the attribute to
  303. <CODE>VALUE</CODE>, which may be a string, an <CODE>SGMLS_Entity</CODE> object, or an
  304. <CODE>SGMLS_Notation</CODE> subject, depending on the attribute's type.</A></STRONG><BR>
  305. <DD>
  306. <DT><STRONG><CODE>ext()</CODE>: Return a reference to an associative array available
  307. for user-defined extensions.</STRONG><BR>
  308. <DD>
  309. </DL>
  310. <P>
  311. <H2><A NAME="the sgmls_notation class">The <CODE>SGMLS_Notation</CODE> class</A></H2>
  312. <P>All declared notations appear as objects belonging to this class,
  313. which recognises the following methods:</P>
  314. <DL>
  315. <DT><STRONG><CODE>name()</CODE>: Return a string containing the name of the notation.</STRONG><BR>
  316. <DD>
  317. <DT><STRONG><A NAME="item_sysid"><CODE>sysid()</CODE>: Return a string containing the system identifier of
  318. the notation, if any.</A></STRONG><BR>
  319. <DD>
  320. <DT><STRONG><A NAME="item_pubid"><CODE>pubid()</CODE>: Return a string containing the public identifier of
  321. the notation, if any.</A></STRONG><BR>
  322. <DD>
  323. <DT><STRONG><CODE>ext()</CODE>: Return a reference to an associative array available
  324. for user-defined extensions.</STRONG><BR>
  325. <DD>
  326. </DL>
  327. <P>
  328. <H2><A NAME="the sgmls_entity class">The <CODE>SGMLS_Entity</CODE> class</A></H2>
  329. <P>All declared entities appear as objects belonging to this class, which
  330. recognises the following methods:</P>
  331. <DL>
  332. <DT><STRONG><CODE>name()</CODE>: Return a string containing the name of the entity, in
  333. mixed case.</STRONG><BR>
  334. <DD>
  335. <DT><STRONG><CODE>type()</CODE>: Return a string containing the type of the entity, in
  336. upper case.  Available types are ``CDATA'', ``SDATA'', ``NDATA'' (external
  337. entities only), ``SUBDOC'', ``PI'' (newer versions of <STRONG>nsgmls</STRONG> only), or
  338. ``TEXT'' (newer versions of <STRONG>nsgmls</STRONG> only).</STRONG><BR>
  339. <DD>
  340. <DT><STRONG><CODE>value()</CODE>: Return a string containing the value of the entity,
  341. if it is internal.</STRONG><BR>
  342. <DD>
  343. <DT><STRONG><CODE>sysid()</CODE>: Return a string containing the system identifier of
  344. the entity (if any), if it is external.</STRONG><BR>
  345. <DD>
  346. <DT><STRONG><CODE>pubid()</CODE>: Return a string containing the public identifier of
  347. the entity (if any), if it is external.</STRONG><BR>
  348. <DD>
  349. <DT><STRONG><A NAME="item_filenames"><CODE>filenames()</CODE>: Return an array of strings containing any file
  350. names generated from the identifiers, if the entity is external.</A></STRONG><BR>
  351. <DD>
  352. <DT><STRONG><CODE>notation()</CODE>: Return the <CODE>SGMLS_Notation</CODE> object associated
  353. with the entity, if it is external.</STRONG><BR>
  354. <DD>
  355. <DT><STRONG><A NAME="item_data_attributes"><CODE>data_attributes()</CODE>: Return a reference to an associative array
  356. of data attribute names (in upper case) and the associated
  357. <CODE>SGMLS_Attribute</CODE> objects for the current entity.</A></STRONG><BR>
  358. <DD>
  359. <DT><STRONG><A NAME="item_data_attribute_names"><CODE>data_attribute_names()</CODE>: Return an array of data attribute
  360. names (in upper case) for the current entity.</A></STRONG><BR>
  361. <DD>
  362. <DT><STRONG><A NAME="item_data_attribute"><CODE>data_attribute(ANAME)</CODE>: Return the <CODE>SGMLS_Attribute</CODE> object
  363. for the data attribute named <CODE>ANAME</CODE> for the current entity.</A></STRONG><BR>
  364. <DD>
  365. <DT><STRONG><A NAME="item_set_data_attribute"><CODE>set_data_attribute(ATTRIB)</CODE>: Add the <CODE>SGMLS_Attribute</CODE> object
  366. <CODE>ATTRIB</CODE> to the current entity, replacing any other data attribute
  367. with the same name.</A></STRONG><BR>
  368. <DD>
  369. <DT><STRONG><CODE>ext()</CODE>: Return a reference to an associative array for
  370. user-defined extensions.</STRONG><BR>
  371. <DD>
  372. </DL>
  373. <P>
  374. <HR>
  375. <H1><A NAME="author and copyright">AUTHOR AND COPYRIGHT</A></H1>
  376. <P>Copyright 1994 and 1995 by David Megginson,
  377. <CODE>dmeggins@aix1.uottawa.ca</CODE>.  Distributed under the terms of the Gnu
  378. General Public License (version 2, 1991) -- see the file <CODE>COPYING</CODE>
  379. which is included in the <STRONG>SGMLS.pm</STRONG> distribution.</P>
  380. <P>
  381. <HR>
  382. <H1><A NAME="see also:">SEE ALSO:</A></H1>
  383. <P><A HREF="../../site/lib/SGMLS/Output.html">the SGMLS::Output manpage</A> and <A HREF="../../site/lib/SGMLS/Refs.html">the SGMLS::Refs manpage</A>.</P>
  384. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  385. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  386. <STRONG><P CLASS=block> SGMLS - class for postprocessing the output from the B<sgmls> and
  387. B<nsgmls> parsers.</P></STRONG>
  388. </TD></TR>
  389. </TABLE>
  390.  
  391. </BODY>
  392.  
  393. </HTML>
  394.