/usr/share/gtk-doc/html/cattle/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>I/O Handling</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.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.18 (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="2"><tr valign="middle">
<td><a accesskey="p" href="ch04.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="ch04.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cattle Reference Manual</th>
<td><a accesskey="n" href="api-index-full.html"><img src="right.png" width="24" height="24" 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 valign="top" align="right"></td>
</tr></table></div>
<div class="refsect2">
<a name="idp51815340"></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 provided, so usually there is no
			need to define a custom handler.
		</p>
</div>
<hr>
<div class="refsect2">
<a name="idp53472636"></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="idp51418908"></a><h3>Output handler</h3>
<p>
			Implementing an output handler is pretty straightforward: the
			handler is passed a single <a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gchar">gchar</a>
			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,
			                gchar               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] = output;
				text[1] = (gchar) 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="idp51779468"></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)
			{
				char *input;
				char *temp;

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

				if (input != NULL) {

					/* A line of input has been read: since readline
					 * strips the trailing newline but the interpreter
					 * needs it, a new string with a trailing newline is
					 * created and fed the interpreter */
					temp = g_strdup_printf ("%s\n", input);

					cattle_interpreter_feed (interpreter,
					                         temp);

					/* The interpreter keeps a copy of the input around,
					 * so any allocated buffer can be freed */
					g_free (temp);
					free (input);
				}
				else {

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

				return TRUE;
			}
		</pre></div>
<p>
			Input works on a per-line basis: the handler must
			retrieve a full, null-terminated 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. The
			string still needs to be null-terminated.
		</p>
<p>
			When the whole input has been consumed (EOF condition), the
			handler must feed the interpreter a
			<a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a> pointer to let it know
			no more input is available.
		</p>
</div>
<hr>
<div class="refsect2">
<a name="idp54047204"></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;
				gchar 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.18</div>
</body>
</html>
libcattle-1.0-doc 1.0.1-1ubuntu1 / usr / share / gtk-doc / html / cattle / io-handling.html
