cvs: peardoc /en/package/structures/structures-bibtex warnings.xml

From: Date: Sat, 15 Jul 2006 16:09:20 +0000
Subject: cvs: peardoc /en/package/structures/structures-bibtex warnings.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-8149@lists.php.net to get a copy of this message
hugoki Sat Jul 15 16:09:20 2006 UTC Added files: /peardoc/en/package/structures/structures-bibtex warnings.xml Log: - Doc about Warnings http://cvs.php.net/viewvc.cgi/peardoc/en/package/structures/structures-bibtex/warnings.xml?view=markup&rev=1.1 Index: peardoc/en/package/structures/structures-bibtex/warnings.xml +++ peardoc/en/package/structures/structures-bibtex/warnings.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <refentry id="package.structures.structures-bibtex.warnings"> <refnamediv> <refname>Warnings</refname> <refpurpose> Usage of warnings when using <classname>Structures_BibTex</classname> </refpurpose> </refnamediv> <refsect1 id="package.structures.structures-bibtex.warnings.overview"> <title>Overview</title> <para> The class <classname>Structures_BibTex</classname> introduces a system to collect warnings that may happen during parsing. Warnings are things in the BibTex source which are not correct but do not cause the parser to fail. One example would be a double cite entry. These warnings should help to improve the quality of your BibTex code. Whether warnings are generated or not is controlled by the option validate. Per default warnings are generated. If you want to not generate warnings you should use the <function>setOption</function> method like this. <example> <title>Switching off creation of warnings</title> <programlisting role="php"> <![CDATA[ require_once ('Structures/BibTex.php'); $foo = new Structures_BibTex(); $foo->setOption('validate', false); ]]> </programlisting> </example> </para> </refsect1> <refsect1 id="package.structures.structures-bibtex.warnings.usage"> <title>Usage</title> <para> The warnings are stored in an array called warnings which is public accessible. To check is a warning exists you can use the method <function>hasWarning</function>. This method returns true if there are warnings and false otherwise. <example> <title>Checking for warnings</title> <programlisting role="php"> <![CDATA[ require_once ('Structures/BibTex.php'); $foo = new Structures_BibTex(); $ret=$foo->loadFile('foo.bib'); if (PEAR::isError($ret)) { print $ret->getMessage(); die(); } $foo->parse(); if ($foo->hasWarning()) { print 'There are warnings!<br />'; } ]]> </programlisting> </example> Every warning itself is hash table with the following keys: <itemizedlist> <listitem> <para> <parameter>warning</parameter> - Type of the warning </para> </listitem> <listitem> <para> <parameter>entry</parameter> - The line that caused the warning </para> </listitem> <listitem> <para> <parameter>wholeentry</parameter> - The whole entry in which the warning occurred </para> </listitem> </itemizedlist> To print every warning with type and line that caused the warning you could do something like this: <example> <title>Checking for warnings</title> <programlisting role="php"> <![CDATA[ require_once ('Structures/BibTex.php'); $foo = new Structures_BibTex(); $ret=$foo->loadFile('foo.bib'); if (PEAR::isError($ret)) { print $ret->getMessage(); die(); } $foo->parse(); if ($foo->hasWarning()) { foreach($foo->warnings as $warning) { print 'Warning: '.$warning['warning'].'<br />'; print 'Line: '.$warning['entry'].'<hr />'; } } ]]> </programlisting> </example> Finally if you want to clear all warnings you can use the method <function>clearWarnings</function>. </para> </refsect1> <refsect1 id="package.structures.structures-bibtex.warnings.wanringtypes"> <title>Types of Warnings</title> <para> The following Warnings are known: <itemizedlist> <listitem> <para> <parameter>WARNING_AT_IN_BRACES</parameter> - A Value is delimited by Braces. Then inside a @ is not allowed. </para> </listitem> <listitem> <para> <parameter>WARNING_ESCAPED_DOUBLE_QUOTE_INSIDE_DOUBLE_QUOTES</parameter> - A Value is delimited by Braces. Then inside no escaped double quote is allowed. </para> </listitem> <listitem> <para> <parameter>WARNING_UNBALANCED_AMOUNT_OF_BRACES</parameter> - he amount of braces inside a value is not equal (opening and closing). The parses fails if in the complete entry this amount is not correct. But if only on an entry it is not correct then this is only a warning. As a matter of fact of the parser does not fail but there is an unbalanced amount of braces in an entry this warning has to be generated something times two. </para> </listitem> <listitem> <para> <parameter>WARNING_MULTIPLE_ENTRIES</parameter> - Every entry is identified by a unique string. This warning is created if there are at least two entries with the same identification. </para> </listitem> </itemizedlist> </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->

« previous php.pear.doc (#8149) next »