gulp-mu-build-filter/README.md

Filtering files by build commands.

### **Introduction**

The GULP module µBuildFilter allows you to define different source code
variations within a single source code and to switch between these
variations by commenting out or commenting in areas according to the
specifications.

### Installation

    npm install gulp-mu-build-filter

### Usage

    import µBuildFilter from 'gulp-mu-build-filter';

    gulp.task('SET_SOURCES_TO_V1_7', function (cb) {
        console.log('Set sources to V1.7...');
        gulp.src(["./src/*.js"])
           .pipe(µBuildFilter({
    				release: 'Development', 
    				client: 'MyCompany', 
    				version: '1.7', 
    				mode: "setupComments", 
    				protocol:true}))
           .pipe(gulp.dest('./eMPClient/js/'));
        gulp.src(["./index.html"])
           .pipe(µBuildFilter({
    				release: 'Development', 
    				client: '*', 
    				version: '1.7', 
    				mode: "setupComments", 
    				protocol:true}))
           .pipe(gulp.dest('./src/'));
        cb();
    })

or

    const µBuildFilter = require('gulp-mu-build-filter');

    gulp.task('SET_SOURCES_TO_V1_7', function (cb) {
        console.log('Set sources to V1.7...');
        gulp.src(["./src/*.js"])
           .pipe(µBuildFilter({
    				release: 'Development', 
    				client: 'MyCompany', 
    				version: '1.7', 
    				mode: "setupComments", 
    				protocol:true}))
           .pipe(gulp.dest('./eMPClient/js/'));
        gulp.src(["./index.html"])
           .pipe(µBuildFilter({
    				release: 'Development', 
    				client: '*', 
    				version: '1.7', 
    				mode: "setupComments", 
    				protocol:true}))
           .pipe(gulp.dest('./src/'));
        cb();
    })

### **Preparing the source code**

Comments can be used to define parts of the source code for the various
installation packages. The source code is filtered under Gulp using the
<https://www.npmjs.com/package/gulp-mu-build-filter> module. This makes
it possible to show or hide code areas for certain target systems,
clients or with certain versions. The definition is carried out with the
help of special comments, whereby the different comment notations are
supported:

**Notation \<!\-\-- \-\--\> (HTML)**\
active parentheses: \<!--- @\<X \-\-\--\\nCode\\n\-\-\-- @\>X \-\--\>\
inner parentheses -!--- @\<X \-\-\--\\nCode\\n\-\-\-- @\>X \-\-\--\

**Notation : /\*\-- \--\*/ (C#, Javascript, TypeScript, PHP, C, C++)**\
**active parentheses: /\*\-- @\<X \-\-\--\\nCode\\n\-\-\-- @\>X \--\*/\
inner parentheses //\--@\<X \-\-\--\\nCode\\n \-\-\-- @\>X \-\-\--\

**Notation \<%\-- \--%\> (ASPX)**\
**active parentheses: \<%\-- @\<X \-\-\--\\nCode\\n \-\-\-- @\>X \--%\>\
inner parentheses -%--- @\<X \-\-\--\\nCode\\n \-\-\-- @\>X \-\-\--\

An inactive parenthesis is present if the bracketed area is to be
active, an active parenthesis is present if the enclosed area is to be
inactive and an inner parenthesis is present if an area is excluded by
nesting.

The variation commands are inserted within the single-line comment, each
framed by a space:

    /*-- @<BUILD_NEVER_AT_RELEASES:Test --*/

**@\<** opens a code area, **@\>** closes a code area. A code area for a
build can, for example, be excluded with **BUILD_NEVER_AT_RELEASES** or
included with **BUILD_ONLY_AT_RELEASES**. Code areas can also be nested.

All comment commands must be on a separate line, leading spaces or tabs
are possible.

A colon separates the variation command from the parameters.

Optionally, the closing comment command can also contain the parameters
of the opening comment command. In this case, the system also checks the
correct nesting with regard to the parameters. Example:

    /*-- @<BUILD_NEVER_AT_RELEASES:Production,Test --*/
    var thisVariableIsNeverDefinedInReleasePackage=true;
    /*-- @>BUILD_NEVER_AT_RELEASES:Production,Test --*/

The following variation commands are permitted:

**Variation Command BUILD_ONLY_AT_RELEASES**

Parameter: Comma-separated designations of the package creation
determined by this variation area. These are usually Production, Test or
Development.

**Variation Command BUILD_NEVER_AT_RELEASES**

Parameter: Comma-separated designations of the package creation excluded
from this variation area. These are usually „Production", „Test" or
„Development".

**Variation Command BUILD_ONLY_AT_CLIENTS**

Parameter: Comma-separated designations of client designations of the
package creation determined by this variation area. These designations
depend on the respective project.

**Variation Command BUILD_NEVER_AT_CLIENTS**

Parameter: Comma-separated designations of client designations of the
package creation excluded from this variation range. These designations
depend on the respective project.

**Variation Command BUILD_ONLY_AT_VERSIONS**

Parameter: Comma-separated designations (without spaces) of version
numbers of the package creation determined by this variation range. These
version numbers must be specified in the form main.minor. An optional
following plus sign determines all version numbers equal to or greater
than the specified version, a following minus sign determines all
version numbers less than the specified version number.

**Variation Command BUILD_NEVER_AT_VERSIONS**

Parameter: Comma-separated designations (without spaces) of version
numbers of the package creation excluded from this variation range.
These version numbers must be specified in the form main.minor. An
optional following plus sign determines all version numbers equal to or
greater than the specified version, a following minus sign determines
all version numbers less than the specified version number.

**Variation Command BUILD_ONLY_AT_PLATFORMS**

Parameter: Comma-separated names (without spaces) of platforms (Windows,
MacOS, Andorid etc.) of the package creation determined by this
variation area.

**Variation Command BUILD_NEVER_AT_PLATFORMS**

Parameter: Comma-separated designations (without spaces) of platforms
(Windows, MacOS, Andorid etc.) of the package creation excluded from
this variation area. These designations depend on the respective
project.

**Variation Command BUILD_ONLY_AT_ANY_VARIANTS**

Parameter: Comma-separated variant names (without spaces). For this
comment area to be deactivated, one of the specified parameters must
match.

**Variation Command BUILD_NEVER_AT_ANY_VARIANTS**

Parameter: Comma-separated variant names (without spaces). For this
comment area to be activated, one of the specified parameters must
match.

**Variation Command BUILD_ONLY_AT_ALL_VARIANTS**

Parameter: Comma-separated variant names (without spaces). For this
comment area to be deactivated, all transferred parameters must match
the specified parameters.

**Variation Command BUILD_NEVER_AT_ALL_VARIANTS**

Parameter: Comma-separated variant names (without spaces). For this
comment area to be activated, all transferred parameters must match the
specified parameters.

**Examples:**

Javascript/PHP/C#:

    /*-- @<BUILD_NEVER_AT_RELEASES:Production,Test --*/
    thisVariableIsNeverDefinedInReleasePackage=1;
    /*-- @>BUILD_NEVER_AT_RELEASES --*/
    /*-- @<BUILD_NEVER_AT_RELEASES:Production,Test --*/
    thisVariableIsNeverDefinedInReleasePackage=1;
    /*-- @>BUILD_NEVER_AT_RELEASES:Production,Test --*/
    /*-- @<BUILD_ONLY_AT_RELEASES:Production,Test ----
    thisVariableIsOnlyDefinedInReleaseAndDebugPackage=1;
    ---- @>BUILD_ONLY_AT_RELEASES --*/

HTML:

    <!-- @<BUILD_NEVER_AT_RELEASES:Production --->
     <div>This text is never available in production release version.</div>
    <!-- @>BUILD_NEVER_AT_RELEASES --->
    <!-- @BUILD_ONLY_AT_RELEASES:Production,Test ----
     <div>This text is never available in development version.</div>
    ---- @>BUILD_ONLY_AT_RELEASES --->

ASPX:

    <%-- @<BUILD_NEVER_ON_RELEASES:Production --%>
    <%@ Page Language="C#" CodeFile="MyProgram.cs" Inherits="MyProgram" Debug="true" Async="true"%>
    <%-- @>BUILD_NEVER_ON_RELEASES --%>

### Functions

The module only has one function.

    µBuildFilter(_options);

### Parameter "option"**

The *options* parameter is a Javascript object that specifies the
options for the processing to be carried out:

Property Default Value Description

**Property „release"**

String with the release to be created.

Default value: "\*" (comment always active)

**Property „client"**

String of the client to be created.

Default value: "\*" (comment always active)

**Property „version"**

Version to be created. This have to be a string of form "main.minor".

Default value: "\*" (comment always active)

**Property „platform"**

Platform that is to be created.

Default value: "\*" (comment always active)

**Property „variants"**

An array of strings that specify the variants to be set.

Default value: "\*" (comment always active)

**Property „mode"**\
„remove": Default value. All areas of inactive comments are removed.

„setupComment": The entire source text is retained, the comments are
activated or deactivated according to their results.

**Property „text"**

Optional: Text (String) which have to use instead of the standard pipe
stream.

**Property „protocol"**

Boolean value: Output of the touched file names.

Default value: false

**Property „debug"**
Boolean value: Output of debug information (e.g. lines with comment
commands)

Default value: false