Inline-comment - Revision history

Gray at 13:24, 16 October 2023

2023-10-16T13:24:56Z

Gray at 13:24, 16 October 2023

2023-10-16T13:24:36Z

Gray at 19:09, 5 September 2015

2015-09-05T19:09:42Z

Gray at 12:25, 26 October 2011

2011-10-26T12:25:21Z

Gray at 07:13, 25 August 2011

2011-08-25T07:13:52Z

Gray: Initial revision

2010-12-15T15:22:16Z

Initial revision

New page

== 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 encode 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:

<source lang="C">
int rc; /* Return code */
mu_stream_t flt; /* Filter stream */
mu_stream_t input; /* Input stream */

initialize_input_stream (&stream);
rc = mu_filter_stream_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);
</source>

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>:

<source 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 (&stream);
rc = mu_filter_stream_create_args (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ, 2, argv);
</source>

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.:

<source 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 (&stream);
rc = mu_filter_stream_create_args (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ, 3, argv);
</source>

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]]

@@ Line 9: / Line 9: @@
 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:
-<source lang="C">
+<syntaxhighlight lang="C">
    int rc;          /* Return code */
    mu_stream_t flt; /* Filter stream */
@@ Line 16: / Line 16: @@
    initialize_input_stream (&input);
    rc = mu_filter_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);
-</source>
+</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>:
-<source lang="C">
+<syntaxhighlightlang="C">
    int rc;          /* Return code */
    mu_stream_t flt; /* Filter stream */
@@ Line 28: / Line 28: @@
    initialize_input_stream (&input);
    rc = mu_filter_create_args (&flt, input, "inline-comment", 2, argv, MU_FILTER_DECODE, MU_STREAM_READ);
-</source>
+</syntaxhighlight>
 Notice that the above filter will remove any line starting with the <tt>rem</tt> characters, for example:
@@ Line 40: / Line 40: @@
 <tt>-S</tt> option to the filter. E.g.:
-<source lang="C">
+<syntaxhighlight lang="C">
    int rc;          /* Return code */
    mu_stream_t flt; /* Filter stream */
@@ Line 48: / Line 48: @@
    initialize_input_stream (&input);
    rc = mu_filter_create_args (&flt, input, "inline-comment", 3, argv, MU_FILTER_DECODE, MU_STREAM_READ);
-</source>
+</syntaxhighlight>
 The following [[filter options|options]] modify the default behavior:

← Older revision		Revision as of 12:25, 26 October 2011
Line 68:		Line 68:

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

@@ Line 14: / Line 14: @@
    mu_stream_t input; /* Input stream */
-   initialize_input_stream (&stream);
+   initialize_input_stream (&input);
-   rc = mu_filter_stream_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);
+   rc = mu_filter_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);
 </source>
@@ Line 26: / Line 26: @@
    char *argv[] = { "inline-comment", "rem", NULL },
-   initialize_input_stream (&stream);
+   initialize_input_stream (&input);
    rc = mu_filter_create_args (&flt, input, "inline-comment", 2, argv, MU_FILTER_DECODE, MU_STREAM_READ);
 </source>
@@ Line 46: / Line 46: @@
    char *argv[] = { "inline-comment", "rem", "-S", NULL },
-   initialize_input_stream (&stream);
+   initialize_input_stream (&input);
    rc = mu_filter_create_args (&flt, input, "inline-comment", 3, argv, MU_FILTER_DECODE, MU_STREAM_READ);
 </source>