[docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Mar 8 13:15:51 EST 2005
User: docelic
Date: 2005-03-08 18:15:51 GMT
Modified: refs catch.tag try.tag
Log:
2 more done. Seven hundred and five million to go.
Revision Changes Path
1.2 +94 -1 xmldocs/refs/catch.tag
rev 1.2, prev_rev 1.1
Index: catch.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/catch.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- catch.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ catch.tag 8 Mar 2005 18:15:51 -0000 1.2
@@ -1,7 +1,32 @@
+__NAME__ purpose
+handle failed 'try' blocks
+__END__
+
__NAME__ synopsis
<row>
<entry>
+ label
+ </entry>
+ <entry>
+ 1
+ </entry>
+ <entry>
+ 1
+ </entry>
+ <entry>
+ <literal>default</literal>
+ </entry>
+ <entry>
+ Name to assign to the &tag-try; block. The name is later used by
+ &tag-cache; (or some custom code) to refer to the proper &tag-try;
+ block.
+ </entry>
+
+</row>
+<row>
+
+ <entry>
exact
</entry>
<entry>
@@ -96,4 +121,72 @@
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+
+__NAME__ see also
+try
+__END__
+
+
+__NAME__ description
+The page content contained within <code>[catch
+<replaceable>label_name</replaceable>] ... [/catch]</code> block will
+be executed if the correspondingly labelled &tag-try; block fails.
+This kind of error handling is common in some general-purpose programming
+languages, such as Java,
+<ulink url="http://www.hprog.org/fhp/MlLanguage">SML</ulink> or even
+&PERL;.
+</para><para>
+Except providing just a general error handling mechanism, &IC; implementation
+can take different code paths, depending on the specific error that occurred.
+That is achieved by matching the error message using &glos-regexp;s.
+__END__
+
+__NAME__ notes
+Note that the &tag-catch; block executes <emphasis role='bold'>at place of
+occurence</emphasis> in place the page (if it is triggered), and not in place
+of the failed &tag-try; block. This gives great flexiblity but must be
+taken into account.
+</para><para>
+&tag-catch; block must always <emphasis role='bold'>follow</emphasis>
+&tag-try;, that is — be executed after the
+<literal>$Session->{try}{<replaceable>label</replaceable>}</literal>
+structure has been initialized.
+</para><para>
+You might wonder, what will the actual error messages be, and how will
+you know which &glos-regexp;s to use in matching them?
+The error messages "raised" will usually be those that are also placed
+in the error logs. See <xref linkend="catch_examples"/> for clarification.
+__END__
+
+
+__NAME__ example: Raising and handling "division by zero" Perl error
+In &PERL;, division by zero might result with the following error reported
+in the error log:
+<errortext>
+ 127.0.0.1 4cU3Pgsh:127.0.0.1 - [24/May/2001:14:45:07 -0400] tag /cgi-bin/tag72/tag Safe: Illegal division by zero at (eval 526) line 2
+</errortext>. Or it may be something like <errortext>127.0.0.1 G5vRfC9B:127.0.0.1 - [08/March/2005:18:25:17 +0100] tutorial /cgi-bin/ic/tutorial/catch Safe: 'eval "string"' trapped by operation mask at (tag 'perl') line 2</errortext>.
+</para><para>
+The proper way to provide error handling is something like this:
+<programlisting>
+[set divisor]0[/set]
+
+[try label=div]
+ [calc] eval(1 / [scratch divisor]) [/calc]
+[/try]
+
+[catch div]
+ [/Illegal division by zero/]
+ 0
+ [/Illegal division by zero/]
+
+ [/trapped by operation mask/]
+ Perl Safe error
+ [/trapped by operation mask/]
+
+ Other division error
+[/catch]
+</programlisting>
+__END__
+
1.2 +98 -15 xmldocs/refs/try.tag
rev 1.2, prev_rev 1.1
Index: try.tag
===================================================================
RCS file: /var/cvs/xmldocs/refs/try.tag,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- try.tag 17 Feb 2005 23:25:39 -0000 1.1
+++ try.tag 8 Mar 2005 18:15:51 -0000 1.2
@@ -1,61 +1,144 @@
+__NAME__ purpose
+safely execute a code block and test for errors
+__END__
+
__NAME__ synopsis
<row>
<entry>
- status
+ label
</entry>
<entry>
- <!-- POS -->
+ 1
</entry>
<entry>
- <!-- REQ -->
+ 1
</entry>
<entry>
- <!-- DFL -->
+ <literal>default</literal>
</entry>
<entry>
- <!-- DSC -->
+ Name to assign to the &tag-try; block. The name is later used by
+ &tag-cache; (or some custom code) to refer to the proper &tag-try;
+ block.
</entry>
</row>
<row>
<entry>
+ status
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ Suppresses normal &tag-try; block output and only return 1 for no error,
+ or 0 when the error happens.
+ The corresponding &tag-catch; block is executed if there's an error.
+ </entry>
+</row>
+<row>
+
+ <entry>
hide
</entry>
<entry>
- <!-- POS -->
+0
</entry>
<entry>
- <!-- REQ -->
+0
</entry>
<entry>
- <!-- DFL -->
+0
</entry>
<entry>
- <!-- DSC -->
+ Suppresses normal &tag-try; block output, regardless of its evaluation
+ success or failure.
+ The corresponding &tag-catch; block is executed if there's an error.
</entry>
</row>
<row>
-
<entry>
clean
</entry>
<entry>
- <!-- POS -->
+0
</entry>
<entry>
- <!-- REQ -->
+0
</entry>
<entry>
- <!-- DFL -->
+0
</entry>
<entry>
- <!-- DSC -->
+ Cause the &tag-try; block to suppress its output only if it has an error.
+ Otherwise the block will return whatever partial output it has completed
+ before the error.
+ The corresponding &tag-catch; block is executed if there's an error.
</entry>
</row>
&ROW_INTERPOLATE_0;
&ROW_REPARSE_1;
-__END__
\ No newline at end of file
+__END__
+
+__NAME__ see also
+catch
+__END__
+
+__NAME__ description
+The &tag-try; block allows you to trap execution errors. &IC; processes the
+body of the tag and normally parses and evaluates the block. If no errors are
+raised during execution of the block, the parsing procedure continues as if
+&tag-try; wasn't there. If the error does get generated, however, &IC; will
+execute the correspondingly named &tag-catch; block. "Corresponding names" are
+determined by using <emphasis>labels</emphasis> — arbitrary strings that
+must match at both sides.
+</para><para>
+The &tag-try; tag will place execution result in the
+<literal>$Session</literal> object. See <xref linkend='try_examples'/> for
+clarification.
+__END__
+
+
+__NAME__ notes
+See &tag-catch; for more examples and further discussion.
+</para><para>
+__END__
+
+__NAME__ example: Simple 'try' block in action
+<programlisting>
+[set divisor]0[/set]
+
+[try label=div]
+ [calc] 1 / [scratch divisor] [/calc]
+[/try]
+
+[catch div]Division error[/catch]
+</programlisting>
+__END__
+
+
+__NAME__ example: Triggering an illegal division by zero and watching the error message
+As we've mentioned above, a &tag-try; block labeled <literal>divide</literal>
+creates the <literal>$Session->{try}{divide}</literal> entry in &PERL;
+data structures:
+
+<programlisting>
+[try label=divide][calc] 1 / [scratch divisor] [/calc][/try]
+
+[catch divide]
+ Verbatim error message is: [calc]$Session->{try}{divide}[/calc]
+[/catch]
+</programlisting>
+__END__
+
+
More information about the docs
mailing list