/usr/share/gtk-doc/html/cattle-1.0/io-handling.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Cattle Reference Manual: I/O Handling</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Cattle Reference Manual">
<link rel="up" href="ch04.html" title="Miscellaneous Topics">
<link rel="prev" href="ch04.html" title="Miscellaneous Topics">
<link rel="next" href="api-index-full.html" title="API Index">
<meta name="generator" content="GTK-Doc V1.21 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="ch04.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ch04.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="api-index-full.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="io-handling"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">I/O Handling</span></h2>
<p>I/O Handling — 
			Explanation of the way Cattle performs I/O
		</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect2">
<a name="id-1.5.2.3"></a><h3>I/O Basics</h3>
<p>
			Cattle uses an I/O mechanism which allows for a huge degree
			of flexibility while remaining relatively simple.
		</p>
<p>
			The I/O mechanism is based on callbacks: every time a
			<a class="link" href="CattleInterpreter.html" title="CattleInterpreter">CattleInterpreter</a>
			executes a Brainfuck instruction which requires some sort of
			I/O, it invokes a user provided handler, and expects it to
			perform the I/O operation.
		</p>
<p>
			Default I/O handlers are built into Cattle, so usually there
			is no need to define a custom handler.
		</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.5.2.4"></a><h3>Error reporting</h3>
<p>
			Since I/O is not guaranteed to always be succesful, handlers
			are provided a mean to report errors to the caller.
		</p>
<p>
			All handlers are passed a <a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError">GError</a>
			as last argument: if a handler fails, it is required to return
			<a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a> and to fill the
			error with detailed information.
		</p>
<p>
			If the hanler returns <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS">TRUE</a>, but
			the error is set, the operation is not considered succesful;
			this is because handlers written in languages other than C might
			not be able to both return a value and fill the error at the
			same time.
		</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.5.2.5"></a><h3>Output handler</h3>
<p>
			Implementing an output handler is pretty straightforward: the
			handler is passed a single gint8
			and has to display it to the user in some way.
		</p>
<p>
			As an example, here is an handler which shows the output of
			a Brainfuck program on a
			GtkTextView:
		</p>
<div class="informalexample"><pre class="programlisting">
			gboolean
			output_handler (CattleInterpreter  *interpreter,
			                gint8               output,
			                gpointer            data,
			                GError            **error)
			{
				GtkTextView   *view;
				GtkTextBuffer *buffer;
				GtkTextIter    iter;
				gchar          text[2];

				view = GTK_TEXT_VIEW (data);

				/* Get the buffer used by the GtkTextView */
				buffer = gtk_text_view_get_buffer (view);
				g_object_ref (buffer);

				/* Get a reference to the end of the buffer */
				gtk_text_buffer_get_end_iter (buffer, &amp;iter);

				/* Create a string */
				text[0] = (gchat) output;
				text[1] = '\0';

				/* Insert the char at the end of the buffer */
				gtk_text_buffer_insert (buffer, &amp;iter, text, 1);

				g_object_unref (buffer);

				return TRUE;
			}
		</pre></div>
<p>
			The code assumes a GtkTextView
			has been provided when the signal handler has been assigned to
			the interpreter, like in the following code:
		</p>
<div class="informalexample"><pre class="programlisting">
				CattleInterpreter *interpreter;
				GtkWidget         *view;

				interpreter = cattle_interpreter_new ();
				view = gtk_text_view_new ();

				cattle_interpreter_set_output_handler (interpreter,
				                                       output_handler,
				                                       (gpointer) view);
		</pre></div>
<p>
			Depending on the case, it may make sense for the application
			to buffer an entire line of output, or even the whole output,
			before sending it to its intended destination.
		</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.5.2.6"></a><h3>Input handler</h3>
<p>
			Here is an input handler which uses readline to fetch input
			from the user:
		</p>
<div class="informalexample"><pre class="programlisting">
			gboolean
			input_handler (CattleInterpreter  *interpreter,
			               gpointer            data,
			               GError            **error)
			{
				CattleBuffer *buffer;
				gchar        *input;
				gulong        size;

				/* Read an input line using readline (no prompt) */
				input = readline (NULL);

				if (input != NULL)
				{
					/* A line of input has been read successfully, but it
					 * needs to be copied into a CattleBuffer before
					 * feeding it to the interpreter. */

					/* Calculate the size of the CattleBuffer. readline
					 * returns a null-terminated string with the trailing
					 * newline stripped; a CattleBuffer doesn't need to be
					 * null-terminated, but stripping the newline would mean
					 * losing part of the input. We can just create a
					 * CattleBuffer as big as the string, and replace the
					 * trailing null byte with a newline. */
					size = strlen (input) + 1;

					buffer = cattle_buffer_new (size);
					cattle_buffer_set_contents (buffer, input);
					cattle_buffer_set_value (buffer, size - 1, '\n');

					/* The CattleBuffer now contains a copy of the input, so
					 * the string returned by readline can be safely freed */
					free (input);

					cattle_interpreter_feed (interpreter, buffer);
				}
				else
				{
					/* readline returns NULL when the end of input has
					 * been reached; to let the interpreter know no more
					 * input is available, feed it an empty buffer */

					buffer = cattle_buffer_new (0);

					cattle_interpreter_feed (interpreter, buffer);
				}

				g_object_unref (buffer);

				return TRUE;
			}
		</pre></div>
<p>
			Input works on a per-line basis: the handler must retrieve
			a full line of input, including the trailing newline character,
			and feed it to the interpreter.
		</p>
<p>
			If it is not possible to retrieve the whole line in a single
			step, a part of it can be passed to the interpreter.
		</p>
<p>
			When the whole input has been consumed, the handler must feed
			the interpreter an empty
			<a class="link" href="CattleBuffer.html" title="CattleBuffer">CattleBuffer</a> to let it
			know no more input is available.
		</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.5.2.7"></a><h3>Debug</h3>
<p>
			The debug handler is called whenever a <code class="code">#</code>
			instruction is executed; the interpreter can be configured
			to ignore this instruction, since it's not (strictly
			speaking) part of the Brainfuck language.
		</p>
<p>
			The handler must display useful debugging information to
			the developer; usually, this means dumping the contents of
			the memory tape.
		</p>
<p>
			The following handler appends the contents of the tape to
			a log file:
		</p>
<div class="informalexample"><pre class="programlisting">
			gboolean
			debug_handler (CattleInterpreter  *interpreter,
			               gpointer            data,
			               GError            **error)
			{
				CattleTape *tape;
				gint8       value;
				FILE*       fp;

				tape = cattle_interpreter_get_tape (interpreter);

				/* Save the current tape position */
				cattle_tape_push_bookmark (tape);

				fp = fopen (LOG_FILE, "a");

				if (fp == NULL) {

					/* Set the error, release resources and return */
					g_set_error_literal (error,
					                     CATTLE_INTERPRETER_ERROR,
					                     CATTLE_INTERPRETER_ERROR_IO,
					                     strerror (errno));
					cattle_tape_pop_bookmark (tape);
					g_object_unref (tape);

					return FALSE;
				}

				/* Rewind to the beginning of the tape */
				while (!cattle_tape_is_at_beginning (tape)) {

					cattle_tape_move_left (tape);
				}

				fprintf (fp, "[ ");

				/* Repeat until the end of the tape is reached */
				while (!cattle_tape_is_at_end (tape)) {

					/* Get the current value */
					value = cattle_tape_get_current_value (tape);

					/* Show printable values directly and non-printable
					 * values as their decimal ASCII value */
					if (value &gt;= 33 &amp;&amp; value &lt;= 126) {
						fprintf (fp, "%c ", value);
					}
					else {
						fprintf (fp, "\\%d ", (gint) value);
					}

					cattle_tape_move_right (tape);
				}

				fprintf (fp, "]\n");
				fclose (fp);

				/* Restore the original tape position */
				cattle_tape_pop_bookmark (tape);

				g_object_unref (tape);

				return TRUE;
			}
		</pre></div>
<p>
			After the handler has run, the tape must be in the same exact
			state it was before the signal emission, including the
			position. The best way to ensure it is to use
			<a class="link" href="CattleTape.html#cattle-tape-push-bookmark" title="cattle_tape_push_bookmark ()">cattle_tape_push_bookmark()</a>
			at the beginning of the handler and
			<a class="link" href="CattleTape.html#cattle-tape-pop-bookmark" title="cattle_tape_pop_bookmark ()">cattle_tape_pop_bookmark()</a>
			at the end.
		</p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.21</div>
</body>
</html>
libcattle-1.0-doc 1.2.0-1 / usr / share / gtk-doc / html / cattle-1.0 / io-handling.html
