Copyright: © Kevin Duffy


Source Filter
Source Filter	© Kevin Duffy, 19/09/02, 19:23
Source Filter strips comments or other delimited text from Windows source files.

It also

1.	creates a new version of the source file, and

2.	keeps a backup of the input file by renaming it - appending the extension .bak to its original file name (so you can retrieve it if you've made a mistake).

3.	can optionally amend the file creation and modification dates of the output file to match the input file date or other requirements.

4.	reduces successive blank lines in the output to a single or small set of blank lines.

Delimited text is identified in any of two ways:

a.	by a pair of strings, Delete From and Delete To delimiters which open and close off the delimited text.

b.	by a single string that identifies the rest of the line as text to be deleted.

Either form of delimiting deleted text can be disabled.

Source Filter is an Visual C++ MFC application which runs on Windows 32 bit platforms (Win95, 98, NT, 2000 and XP).


User Dialog Defaults

Source Filter presents a simple dialog user interface, which presents the default program parameters, and allows user customization of them.

The Select Files and Filter button activates a Select Files for Filtering dialog which allows one or more source file to be selected for processing with the prevailing parameters.

Although primarily designed to selectively strip comments from C++ programs, it can be used for any simple MS-DOS ascii source file.

By default, Source Filters will selectively remove C++ comments that are delimited by /** and **/, and will remove the rest of line comments delimited by ///.

If you wish to remove all C++ comments, change the delimiters to /*,  */ and //.


Delete From Delimiter

The Specifies the text which delimits the beginning of text to be deleted. The Delete To delimiter indicates the end of the text to be deleted

By default this is /** - Change this to /* if you wish to delete all C++ comments.

The specified text is considered to delimit the text only if the next character after it is not the same as the delimiters last character.

For example, with the default of /**, a source string beginning with /*** does not match the delimiter and trigger a deletion. This means a string like /**/  would not be deleted, nor would one like /************/ which programmers often use to separate sections of source code.

If the Delete From text is empty, the deletion of text between paired delimiters is disabled.

Example:

If the default Delete From and Delete To delimiters are used with input like

/* comment stays */ /** but this one goes **/

/** this also

    	goes

    **/

/*** but this one

     	stays ***/

/***/ /* and this whole line stays too */

results in output like

/* comment stays */

/*** but this one

     	stays ***/

/***/ /* and this whole line stays too */


Delete To Delimiter

Specifies the delimiter which ends the text to be deleted.  The beginning of text is identified from the Delete From Delimiter.

The delimiter string can have any length.

The Delete to Delimiter is matched only if the character which precedes it is not the same as the first character of the delimiter string.


Delete to End of Line Delimiter

Text between the Delete to End of Line delimiter and the end of line will be deleted, provided the next character after the delimiter's end character is different.

The default for this is ///.

Using the delimiter // will cause all C++ rest-of-line comments to be deleted.

If the default delimiter /// is used, input like

///////////////////// declarations /////////////////////	 this won't be deleted.

int iTest ; 	/// just a test variable	this will be deleted

// initialisations....

results in output like

///////////////////// declarations /////////////////////	 this won't be deleted.

int iTest ;

// initialisations....


Log File

Source Filter logs a summary of its activity to a text file.

By default, this file is named sfilter.log and is written to the same directory as the input files.

You can override the default with a name of your choice, and include a windows directory path if you wish to have it saved in a different directory.

If the log file already exists in the specified (or default) directory, successive runs of Source Filter will write to the end of the file (appending to the existing entries).


Output File Date Options

Source Filter provides a drop down list of three options for setting the created and modified date on the output files.

1.	Input File Time+1 min to Output File(s)	Output file dates are assigned by adding one minute to the input file dates. This is the default. The addition of one minute will enable Visual Studio or other make utilities to recognize the files as being out of date and trigger rebuilding. The purpose of preserving an output file time like the input is to preserve an indication of the historical sequence of source file changes.
2.	Current Time for Output File(s)	Output file dates assigned by using current system time.
3.	Specified New Date and Time for Output Files	User specifies date and time to use on output files. Selection of this option presents the optional New Date and Time edit boxes. This option can be used to simply redate any Windows source file (disable the Delete From and Delete to End of Line features first).

Select one of these values according to your needs.


New Date

The New Date picker box appears if the Specified New Date and Time for Output Files option is selected in the Output File Date Options combination box.

The box opens with a default value showing the current date.

Use the up-arrow and down arrow to change the date value, and tab to move between the day, month and year.

Alternatively, enter the new date as a text string with delimiters, for example 12/09/2002


New Time

The New Time picker box appears if the Specified New Date and Time for Output Files option is selected in the Output File Date Options combination box.

Time is displayed and entered in 24-hour clock format.

The box is initialised with the current system time.

Use the up-arrow and down arrow to change the time value, and tab to move between the hour, minute and second.

Alternatively, enter the new time as a text string with delimiters, for example 16:20:00


Confirm Each File

Check this box if you wish to confirm processing before each selected file.

If this box is ticked, Source Filter reports the results for the previous file, and requests whether the user wishes to proceed with the next file. This confirmation step allows the user to skip the next file, or skip processing of all the remaining selected files, if the results of the previous file are unexpected.


Maximum Blank Lines

Enter the number of consecutive blank lines allowed in the output file. The default is 1, meaning any  2nd, 3rd etc.,. blank consecutive blank line is deleted from the output.

If the deleted delimited text (typically comments) are preceded or followed by blank lines, deletion of the consecutive blank lines usually formats the output better,.

Choose a large number (e.g. 50) if you want all blank lines left in the output.

Choose 0 if you wish all blank lines to be removed from the output

The minimum value is 0 and the maximum is 99.


Select Files and Filter

Click this button to initiate the source file selection and filtering process.

A Select Files for Filtering Diaog is presented. This is standard Windows File Open dialog that allow the user to browse to the required directory and select one or more files.

Browse to the required directory by using the Look in: combo box and/or the Up Folder toolbar button. Alternatively, enter a full path name in the File name text box.

Left click on a file to select it, then ctrl/left-click on any additional files you wish to select from the directory.

Alternatively, shift/left click can be used to multiply select between the first file and the last in a set.

Then click the Open button in the Select Files for Filtering dialog to initiate filtering of the selected files.

When processing is complete, the Source Filtering Done message box is presented:

Click OK to acknowledge the message box. If desired, review the Log File to confirm processing occurred as intended.

If you click the Cancel button in the Select Files for Filtering  Dialog, no processing occurs.


Finish

Click the Finish button to exit from the Source Filter application.


Help

Click the Help button to open this help file.

To get help on a particular dialog entry box, move the cursor to the box and hit F1. This opens the help file on the relevant topic.


Updating Help

This help file was built using Help & Manual.

It was necessary to change the Project properties to add the following section to the extended help project settings for Winhelp.

[MAP]

#include <SourceFilter.hm>

#include ..\resource.hm

It was also necessary to modify the makehelp.bat file to get the help identifiers created for the HIDC_ identifiers:

...

makehm IDD_,HIDD_,0x20000 resource.h >>"hlp\SourceFilter.hm"

echo. >>"hlp\SourceFilter.hm"

echo // Frame Controls (IDW_*) >>"hlp\SourceFilter.hm"

makehm IDW_,HIDW_,0x50000 resource.h >>"hlp\SourceFilter.hm"

echo // Dialog Controls (IDC_*) >>"hlp\SourceFilter.hm"

makehm IDC_,HIDC_,0x80660000 resource.h >>"hlp\SourceFilter.hm"

copy "hlp\SourceFilter.hm" "SourceFilter.hm"

goto :done

rem -- bypass the help compilation and file copy steps as H & M used for this.

I think VS invokes the makehelp.bat - but I'm not sure what the trigger is.

It seems that Visual Studio makes the dialog control Help ID's with an 0x80660000 offset, but I could not find any MS documentation that explained or indicated this.

Technical Note 028  (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmfc98/html/_mfcnotes_tn028.asp) is the closest MS get to explaining this.

MSDN code center has a dlghlp example, but it uses a manual approach (dlgres.h) to build the HIDC identifiers - in place of the help mapping file.

I used the following steps to build the help file:

1) Create a makehm3.bat in the main source directory (where the .cpp etc.,. are)  containing:

@echo off

: MakeHM3

:   Makes a Windows 32 help file from the Help & Manual .hm3 file

:   .hm3 read from hlp sub-folder, output built in main source directory

:   output .hlp file and .cnt files then copied to the Debug or Release directory

:

:  Parameters

:    1 -  Debug or Release, to indicate destination for .hlp and .cnt files

:

:

:  K Duffy Sep 2002

:

echo ====

echo Using Help & Manual to Build Windows hlp file to %1% Directory

echo ====

path = ""

path="c:\windows\command;d:\Program Files\Helpman3\;F:\Microsoft Visual Studio\Tools\"

echo Utilities and Tools are expected on Path %PATH%

path

: start is a dos command

start /wait helpman.exe "hlp\SourceFilter.hm3" /hlp

if errorlevel 1 goto :Error1

if not exist "SourceFilter.hlp" goto :Error2

echo on

copy "SourceFilter.hlp" "%1%"

copy "SourceFilter.cnt" "%1%"

@echo off

goto :done

:Error1

echo *** Error(1) *** Error Running Helpman on hlp\SourceFilter.hm3

echo Check that Help&Manual not open already (must be closed before this is run)

echo ***          ***

type "hlp\SourceFilter.log"

echo *** ignore any complaints from help compiler after this point in build

:Error2

echo hlp\SourceFilter.hlp does not exist

:done

echo %1%\SourceFilter.hlp now made

If Help & Manual is open interactively when this is run, the helpman.exe run fails, and it seems that VS tries then to use another help compiler to make the .hlp file. This complained that AfxDlg.rtf was missing (because I'd deleted it, as I'd rather not have the crap it produces overwriting my last good help file).

2)  In Visual Studio 6, select the File View, Add the SourceFilter.hm3 file under the Source folder

3) Now right click on SourceFilter.hm3 and select Project Settings option for it...

4)  Now edit the Commands and Outputs boxes as follows:

   Click the Dependencies, and Add an entry to give this:

HPJ.LOG is written by the HPJ build  (see next step). I'm hoping this dependency will mean that changes to the help project file written by Visual Studio will now trigger builds of the hm3. But I'm hoping it doesn't get build unnecessariily - not sure how VS updates the hpj file...

5) Similarly, select the SourceFilter.hpj file settings and edit as follows:

This stops Visual Studio from invoking the help file compiler directly

I also deleted the AfxDlg.rtf file from the help files folder. I'm not sure if that had the makehelp.bat invoking step in it before I deleted it !

6) Select the Release configuration of the Project, and repeat the above steps to change the build settings.