cvs: peardoc /en/package/structures/structures-bibtex warnings.xml
| From: | Elmar Pitschke | 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
-->