[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 &mdash; 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> &mdash; 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