LatexilaPostProcessor: LaTeXila Reference Manual

## LatexilaPostProcessor LatexilaPostProcessor — post-processor base class |

## Functions

const gchar * | latexila_post_processor_get_name_from_type ()
gboolean | latexila_post_processor_get_type_from_name ()
void | latexila_post_processor_process_async ()
void | latexila_post_processor_process_finish ()
void | latexila_post_processor_start ()
void | latexila_post_processor_process_line ()
void | latexila_post_processor_end ()
const GList * | latexila_post_processor_get_messages ()
GQueue * | latexila_post_processor_take_messages ()

## Properties

gboolean | has-details | Read / Write / Construct

## Types and Values

| LatexilaPostProcessor
enum | LatexilaPostProcessorType

## Object Hierarchy

        GObject
        ╰── LatexilaPostProcessor
            ├── LatexilaPostProcessorAllOutput
            ├── LatexilaPostProcessorLatex
            ╰── LatexilaPostProcessorLatexmk

## Includes

    #include <latexila.h>

## Description

When running a build tool, a post-processor is used to filter the output to display only the relevant messages. The output can come from the stdout/stderr of a build job command, or the contents of a log file, etc. In LaTeXila only the former is currently used, but it would be more robust to read the LaTeX log file.

For the no-output post-processor type, you should not need to create a LatexilaPostProcessor object, since the result is empty.

The implementations sometimes assume that a post-processor can be used at most one time.

## Functions

### latexila_post_processor_get_name_from_type ()

    const gchar *
    latexila_post_processor_get_name_from_type
                                   (LatexilaPostProcessorType type);

#### Parameters

type | the post-processor type. |

#### Returns

the post-processor name.

### latexila_post_processor_get_type_from_name ()

    gboolean
    latexila_post_processor_get_type_from_name
                                   (const gchar *name,
                                    LatexilaPostProcessorType *type);

#### Parameters

name | the name of the post-processor. |
type | the output post-processor type. | [out]

#### Returns

`TRUE` on success, `FALSE` otherwise.

### latexila_post_processor_process_async ()

    void
    latexila_post_processor_process_async (LatexilaPostProcessor *pp,
                                           GFile *file,
                                           GInputStream *stream,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Asynchronously process an input stream. The input stream can for example come from the output of a command launched with GSubprocess, or it can be the input stream of a file (e.g. the LaTeX log file), etc.

`callback` will be called when the operation is finished. You can then call `latexila_post_processor_process_finish()`.

#### Parameters

pp | a post-processor. |
file | the GFile on which the build tool is run. |
stream | the input stream to process. |
cancellable | a GCancellable. |
callback | the callback to call when the operation is finished. |
user_data | the data to pass to the callback. |

### latexila_post_processor_process_finish ()

    void
    latexila_post_processor_process_finish
                                   (LatexilaPostProcessor *pp,
                                    GAsyncResult *result,
                                    gboolean succeeded);

Finishes an operation started with `latexila_post_processor_process_async()`. After calling this function, you can get the filtered messages with `latexila_post_processor_get_messages()`.

#### Parameters

pp | a post-processor. |
result | a GAsyncResult. |
succeeded | whether the subprocess has succeeded. |

### latexila_post_processor_start ()

    void
    latexila_post_processor_start (LatexilaPostProcessor *pp,
                                   GFile *file);

Manually starts the post-processor.

Not needed if you use `latexila_post_processor_process_async()`.

#### Parameters

pp | a LatexilaPostProcessor. |
file | the GFile on which the build tool is run. |

### latexila_post_processor_process_line ()

    void
    latexila_post_processor_process_line (LatexilaPostProcessor *pp,
                                          gchar *line);

Manually processes a line. This function takes ownership of `line` . Free with `g_free()` if you don't reuse the content.

Not needed if you use `latexila_post_processor_process_async()`.

#### Parameters

pp | a LatexilaPostProcessor. |
line | a line, without the newline character(s). | [transfer full]

### latexila_post_processor_end ()

    void
    latexila_post_processor_end (LatexilaPostProcessor *pp,
                                 gboolean succeeded);

Manually ends the processing.

Not needed if you use `latexila_post_processor_process_async()`.

#### Parameters

pp | a LatexilaPostProcessor. |
succeeded | whether the subprocess has succeeded. |

### latexila_post_processor_get_messages ()

    const GList *
    latexila_post_processor_get_messages (LatexilaPostProcessor *pp,
                                          gboolean show_details);

Gets the filtered messages. Call this function only after calling `latexila_post_processor_process_finish()` or `latexila_post_processor_end()`.

Another solution would have been to pass the LatexilaBuildView to the post-processor, so the filtered messages can directly be outputed to the build view as they come. But some post-processors don't know what to output directly. The latexmk post-processor can have a simplified output with only the LaTeX messages, in which case the detailed messages are also available, but this can be known only when all the stream has been processed.

Obviously if the build view is passed to the post-processor, the latexmk post-processor can output its messages only at the end. But another reason to not pass the build view is for the unit tests. It is easier for the unit tests to check the returned GList than analyzing a GtkTreeView. Of course it would be possible to keep also the messages in a GList and have this function only for the unit tests, but it takes more memory (unless a custom GtkTreeModel is implemented), or another function is needed to configure whether a GList is kept in memory or not... It becomes a little too complicated, and doesn't really worth the effort as most users use latexmk.

The current solution is "good enough". And "good enough" is... "good enough".

#### Parameters

pp | a post-processor. |
show_details | whether to show the details. Has no effect if “has-details” is `FALSE`. |

#### Returns

the tree of filtered messages.

[transfer none][element-type LatexilaBuildMsg]

### latexila_post_processor_take_messages ()

    GQueue *
    latexila_post_processor_take_messages (LatexilaPostProcessor *pp);

Takes ownership of all the messages. Since GQueue is not reference counted, `pp` is emptied and is thus useless after calling this function.

[skip]

#### Parameters

pp | a LatexilaPostProcessor. |

#### Returns

the tree of filtered messages, or `NULL`. Element types: LatexilaBuildMsg.

[transfer full][nullable]

## Types and Values

### LatexilaPostProcessor

    typedef struct _LatexilaPostProcessor LatexilaPostProcessor;

### enum LatexilaPostProcessorType

Types of post-processors.

#### Members

LATEXILA_POST_PROCESSOR_TYPE_NO_OUTPUT | no output. |
LATEXILA_POST_PROCESSOR_TYPE_ALL_OUTPUT | all output. |
LATEXILA_POST_PROCESSOR_TYPE_LATEX | for a LaTeX command. |
LATEXILA_POST_PROCESSOR_TYPE_LATEXMK | for the latexmk command. |
LATEXILA_POST_PROCESSOR_TYPE_NB_TYPES | number of post-processor types. |

## Property Details

### The `“has-details”` property

      “has-details”              gboolean

Flags: Read / Write / Construct

Default value: FALSE