Inline-comment

Introduction

The inline-comment filter in decode mode removes inline comments from the input stream.

In encode mode it outputs a given byte sequence at the beginning of each output line.

Decode mode

In decode mode, the filter removes all lines beginning with a comment sequence from the input. The default comment sequence is ; (a semicolon). The initialization of the inline-stream in this default mode is shown in the following example:

  int rc;          /* Return code */
  mu_stream_t flt; /* Filter stream */
  mu_stream_t input; /* Input stream */

  initialize_input_stream (&input);
  rc = mu_filter_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);

To change the comment sequence supply the new sequence as the first argument. For example, the following filter will remove any lines starting with a rem:

  int rc;          /* Return code */
  mu_stream_t flt; /* Filter stream */
  mu_stream_t input; /* Input stream */
  char *argv[] = { "inline-comment", "rem", NULL },

  initialize_input_stream (&input);
  rc = mu_filter_create_args (&flt, input, "inline-comment", 2, argv, MU_FILTER_DECODE, MU_STREAM_READ);

Notice that the above filter will remove any line starting with the rem characters, for example:

rem A comment.
remark that should not be removed.

Removing of the second line seems wrong in most cases, therefore the filter supports a special whitespace-must-follow mode, in which it recognizes the comment sequence only when it is immediatly followed by a whitespace character. This mode is enabled by the -S option to the filter. E.g.:

  int rc;          /* Return code */
  mu_stream_t flt; /* Filter stream */
  mu_stream_t input; /* Input stream */
  char *argv[] = { "inline-comment", "rem", "-S", NULL },

  initialize_input_stream (&input);
  rc = mu_filter_create_args (&flt, input, "inline-comment", 3, argv, MU_FILTER_DECODE, MU_STREAM_READ);

The following options modify the default behavior:

-i STR

Emit line number information after each contiguous sequence of removed lines. STR supplies "information starter" -- a sequence of characters which is output before the actual line number.

-r

Remove empty lines, i.e. the ones that contain only whitespace characters.

-s

Squeeze whitespace. Each sequence of two or more whitespace characters encountered on input is replaced by a single space character on output.

-S

A whitespace-must-follow mode. A comment sequence is recognized only if followed by a whitespace character. The character itself is retained on output.

Encode mode

In encode mode the inline-comment filter adds a comment-starter sequence at the beginning of each line. As previously, the default comment-starter is ';', which can be changed by specifying the desired comment starter as the first argument to the filter creation sequence.

The only option supported in this mode is -S, which enables the whitespace-must-follow mode, in which a single space character (ASCII 20) is output after each comment sequence.