View source for Inline-comment

== Introduction ==

The <tt>inline-comment</tt> filter in [[MU_FILTER_DECODE|decode mode]] removes [http://en.wikipedia.org/wiki/Inline_comment inline comments] from the input stream. 

In [[MU_FILTER_ENCODE|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 <tt>;</tt> (a semicolon).  The initialization of the <tt>inline-stream</tt> in this default mode is shown in the following example:

<syntaxhighlight lang="C">
  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);
</syntaxhighlight>

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 <tt>rem</tt>:

<syntaxhighlight lang="C">
  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);
</syntaxhighlight>

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

<pre>
rem A comment.
remark that should not be removed.
</pre>

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 
<tt>-S</tt> option to the filter. E.g.:

<syntaxhighlight lang="C">
  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);
</syntaxhighlight>

The following [[filter options|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 [[MU_FILTER_ENCODE|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 <tt>-S</tt>, which enables the ''whitespace-must-follow mode'', in which a single space character (ASCII 20) is output after each comment sequence.

[[Category:Filters]]
[[Category:C API]]