Reference:User Message Directives - Revision history

Clipka: Indexentries fix

2016-12-16T15:19:10Z

Indexentries fix

Clipka: indexentry fix

2016-05-03T23:32:29Z

indexentry fix

Jholsenback: moved misplaced quote

2013-04-22T11:35:12Z

moved misplaced quote

Jholsenback: 1 revision: Reference Migration Initial Load

2012-03-15T19:09:13Z

1 revision: Reference Migration Initial Load

Jholsenback: link repair

2012-03-15T14:42:57Z

link repair

New page

[[Category:Language Directives]]
{{#indexentry:Directives, language, user messages}}
With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an actual programming language. This means that it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen. You have a choice of five
different text streams to use including the ability to generate a fatal error if you find it necessary. Limited formatting is available for strings output by this method.
{{#indexentry:#debug|#error|#warning|#render|#statistics}}
{{#indexentry:statistics|debug|error|warning|render}}
{{#indexentry:Directives, language, #debug}}
{{#indexentry:Directives, language, #error}}
{{#indexentry:Directives, language, #warning}}
==Text Message Streams==
The syntax for a text message is any of the following:
<pre>
TEXT_STREAM_DIRECTIVE:
#debug STRING | #error STRING | #warning STRING
</pre>

Where STRING is any valid string of text including string
identifiers or functions which return strings. For example:
<pre>
#switch (clock*360)
#range (0,180)
#debug "Clock in 0 to 180 range\n"
#break
#range (180,360)
#debug "Clock in 180 to 360 range\n"
#break
#else
#warning "Clock outside expected range\n"
#warning concat("Value is:",str(clock*360,5,0),"\n")
#end
</pre>

There are seven distinct [[Reference:Text Output Options#Text Streams|text streams]] that POV-Ray uses for output. You
may output only to three of them. On some versions of POV-Ray, each stream is
designated by a particular color. Text from these streams are displayed
whenever it is appropriate so there is often an intermixing of the text. The
distinction is only important if you choose to turn some of the streams off
or to direct some of the streams to text files. On some systems you may be
able to review the streams separately in their own scroll-back buffer. See
[[Reference:Text Output Options#Directing Text Streams to Files|Directing Text Streams to Files]] for details on re-directing the
streams to a text file.

Here is a description of how POV-Ray uses each stream. You may use them for
whatever purpose you want except note that use of the <code>#error</code>
stream causes a fatal error after the text is displayed.

 Debug: This stream displays debugging messages. It was
primarily designed for developers but this and other streams may also be used
by the user to display messages from within their scene files.

Error: This stream displays fatal error messages. After
displaying this text, POV-Ray will terminate. When the error is a scene
parsing error, you may be shown several lines of scene text that leads up to
the error.

Warning: This stream displays warning messages during the
parsing of scene files and other warnings. Despite the warning, POV-Ray can
continue to render the scene.

{{#indexentry:Directives, language, #render}}
{{#indexentry:Directives, language, #statistics}}
{{#indexentry:Directives, language, #debug}}
{{#indexentry:Directives, language, #status}}
{{#indexentry:Directives, language, #banner}}
The <code>#render</code> and <code>#statistsics</code> could be accessed in previous versions.
Their output is now redirected to the <code>#debug</code> stream.
The <code>#banner</code> and <code>#status</code> streams can not be accessed by the user.

==Text Formatting==
Some escape sequences are available to include non-printing control
characters in your text. These sequences are similar to those used in string
literals in the C programming language. The sequences are:

<table SUMMARY="All character escape sequences" width="100%">
<tr>
<td width="25%"><code>"\a"</code></td>

<td width="65%">Bell or alarm,</td>

<td width="10%">0x07</td>
</tr>

<tr>
<td><code>"\b"</code></td>

<td>Backspace,</td>

<td>0x08</td>
</tr>

<tr>
<td><code>"\f"</code></td>

<td>Form feed,</td>

<td>0x0C</td>
</tr>

<tr>
<td><code>"\n"</code></td>

<td>New line (line feed)</td>

<td>0x0A</td>
</tr>

<tr>
<td><code>"\r"</code></td>

<td>Carriage return</td>

<td>0x0D</td>
</tr>

<tr>
<td><code>"\t"</code></td>

<td>Horizontal tab</td>

<td>0x09</td>
</tr>

<tr>
<td><code>"\uNNNN"</code></td>

<td>Unicode character code NNNN</td>

<td>0xNNNN</td>
</tr>

<tr>
<td><code>"\v"</code></td>

<td>Vertical tab</td>

<td>0x0B</td>
</tr>

<tr>
<td><code>"\0"</code></td>

<td>Null</td>

<td>0x00</td>
</tr>

<tr>
<td><code>"\\"</code></td>

<td>Backslash</td>

<td>0x5C</td>
</tr>

<tr>
<td><code>"\'"</code></td>

<td>Single quote</td>

<td>0x27</td>
</tr>

<tr>
<td><code>"\""</code></td>

<td>Double quote</td>

<td>0x22</td>
</tr>
</table>

For example:
<pre>
#debug "This is one line.\nBut this is another"\n
</pre>

Depending on what platform you are using, they may not be fully supported
for console output. However they will appear in any text file if you
re-direct a stream to a file.

@@ Line 3: / Line 3: @@
 <p>With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an actual programming language. This means that it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen. You have a choice of five
 different text streams to use including the ability to generate a fatal error if you find it necessary. Limited formatting is available for strings output by this method.</p>
 {{#indexentry:#debug}}
 {{#indexentry:#error}}
@@ Line 16: / Line 18: @@
 {{#indexentry:Directives, language, #error}}
 {{#indexentry:Directives, language, #warning}}
 <p>The syntax for a text message is any of the following:</p>
 <pre>

@@ Line 3: / Line 3: @@
 <p>With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an actual programming language. This means that it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen. You have a choice of five
 different text streams to use including the ability to generate a fatal error if you find it necessary. Limited formatting is available for strings output by this method.</p>
-{{#indexentry:#debug|#error|#warning|#render|#statistics}}
+{{#indexentry:#debug}}
-{{#indexentry:statistics|debug|error|warning|render}}
+{{#indexentry:#error}}
 {{#indexentry:Directives, language, #debug}}
 {{#indexentry:Directives, language, #error}}

@@ Line 172: / Line 172: @@
 <p>For example:</p>
 <pre>
-#debug &quot;This is one line.\nBut this is another&quot;\n
+#debug &quot;This is one line.\nBut this is another\n&quot;
 </pre>

← Older revision	Revision as of 19:09, 15 March 2012
(No difference)