![]() |
![]() |
![]() |
Cattle Reference Manual | ![]() |
---|
I/O HandlingI/O Handling — Explanation of the way Cattle performs I/O |
Cattle uses an I/O mechanism which allows for a huge degree of flexibility while remaining relatively simple.
The I/O mechanism is based on callbacks: every time a CattleInterpreter 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.
Default I/O handlers are provided, so usually there is no need to define a custom handler.
Since I/O is not guaranteed to always be succesful, handlers are provided a mean to report errors to the caller.
All handlers are passed a GError as last argument: if a handler fails, it is required to return FALSE and to fill the error with detailed information.
If the hanler returns TRUE, 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.
Implementing an output handler is pretty straightforward: the handler is passed a single gchar and has to display it to the user in some way.
As an example, here is an handler which shows the output of a Brainfuck program on a GtkTextView:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
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, &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, &iter, text, 1); g_object_unref (buffer); return TRUE; } |
The code assumes a GtkTextView has been provided when the signal handler has been assigned to the interpreter, like in the following code:
1 2 3 4 5 6 7 8 9 |
CattleInterpreter *interpreter; GtkWidget *view; interpreter = cattle_interpreter_new (); view = gtk_text_view_new (); cattle_interpreter_set_output_handler (interpreter, output_handler, (gpointer) view); |
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.
Here is an input handler which uses readline to fetch input from the user:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
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; } |
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.
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.
When the whole input has been consumed (EOF condition), the handler must feed the interpreter a NULL pointer to let it know no more input is available.
The debug handler is called whenever a #
instruction is executed; the interpreter can be configured
to ignore this instruction, since it's not (strictly
speaking) part of the Brainfuck language.
The handler must display useful debugging information to the developer; usually, this means dumping the contents of the memory tape.
The following handler appends the contents of the tape to a log file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
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 >= 33 && value <= 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; } |
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 cattle_tape_push_bookmark() at the beginning of the handler and cattle_tape_pop_bookmark() at the end.