GrepIt - Release Notes

Copyright 2026-2027 by The Software Samurai.
On the web: http://www.SoftwareSam.us/
Software released under GNU GPL3, and documentation released under FDL1.3

   GrepIt (gpit.pl): version 0.0.03
   Developed under : Perl v:5.42.3

Description

GrepIt (gpit.pl) is a Perl program which uses the “grep” system utility to scan source code for specific constructs used during project development. The data are captured to a temporary file, then the 'less' utility is used to display the results.

The author uses 'gpit.pl' when preparing distribution archives to ensure that all temporary code has been removed, all debugging code is disabled, and that conditional-compilation directives are configured for a production build.

For instance, this author writes temporary debugging messages and experimental code in this general style:
/* TEMP */ wcout << L"Call nckpConvert( " << conv_val << L" )" << endl ; #if 1 // EXPERIMENTAL - Truncate to window width gString gsRec ; this->ReadRecord ( gsRec ) this->FormatRecord ( gsRec ) ; if ( (gsRec.gscols()) > TermWidth ) { gsRec.limitCols( TermWidth - 4 ) ; gsRec.append( "..." ) ; wcout << gsRec << endl ; } #endif // EXPERIMENTAL

Clearly, this kind of hack should not be included in a production build, so when preparing the distribution archive, 'gpit.pl' is used to identify these smelly constructs, so they can be removed:

 ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
 │  [EarthPoints]$ gpit.pl a -src="EarthPoints.cpp EpParse.cpp"                                     │
 │     yields the report:                                                                           │
 │   EarthPoints.cpp:1262:/* TEMP */ wcout << L"Call nckpConvert( " << conv_val << L" )" << endl ;  │
 │   EpParse.cpp:598:#if 1    // EXPERIMENTAL - Truncate to window width                            │
 │   EpParse.cpp:943:#endif   // EXPERIMENTAL                                                       │
 └──────────────────────────────────────────────────────────────────────────────────────────────────┘

Customizing the Scan

Every experienced software designer will have developed their own style for placing markers in their code to indicate work-in-progress, so please modify  gpit.pl to match your own, personal style.

Download and unpack the distribution archive.

• Navigate to the base directory where package will be installed (example):
     cd  ~/Software
• Move the archive file to the base directory:
     mv  ~/Dowloads/grepit-0.0.03.tar.bz2   ./.
• Unpack the tar archive:
     tar -xjvf grepit-0.0.03.tar.bz2
• Navigate to the target directory:
     cd  GrepIt The expanded archive should include the following files:

     gpit.pl              - Perl script for scanning source code files
     Test1.cpp            - Sample source code
     Test2.hpp
     README               - Release notes (this file)

• Check the version of the Perl compiler currently installed on the system:
     perl  ‐‐version
  If the installed version is earlier that v:5.36, then an upgrade is strongly recommended.
• If you plan to use gpit.pl on a regular basis, it should be visible on the system path.
  This can be accomplished is several different ways:
  • Copy the Perl script to a directory on the execution path.
       cp ‐‐preserve=all  ./gpit.pl  ~/bin/.
  • Create a symlink in a directory on the execution path.
       cp ‐‐symbolic-link  ./gpit.pl  ~/bin/gpit
  • Create a shell script to reference the Perl script.
    #!/bin/bash
    ~/SoftwareDesign/GrepIt/gpit.pl $1 $2 $3 $4 $5 $6 $7 $8
    Save to a convenient name. Example: '~/bin/gpit'
    Be sure to set the shell script as executable.
       chmod  +x  gpit

Command-line Options for ‘gpit.pl’

Usage: gpit.pl SCAN_TOKEN [OPTIONS]

• SCAN_TOKEN  —  Specify the token (or token group) for which to scan.
  This is a single, case-sensitive ASCII character indicating the token for which to search.
  
  

  Scan Token	Token Text	Description
  c	CZONE	Construction Zone – unfinished or untested code
  e	EXPERIMENTAL	Experimental code – Sherlocking a problem
  t	TEMP	Temporary code – report interim results
  a	(all of the above)	Scan for and report all of the above tokens
  d	#define DEBUG_	Report all references to debugging code which is under conditional compile.
  D	#define	Report all conditional compile directives.

  
  Note that the ‘d’ and ‘D’ options recognize an optional argument which applies a filter to report instances of the token only in a desired context:
  d – Report all instances of directives which include “DEBUG_” token.
  Examples: #if DEBUG_GCLA != 0
#endif // DEBUG_GCLA
#define DEBUG_GCLA (1)
d0 – Report only “DEBUG_” directives defined as zero (0).
  Example: #define DEBUG_ILOOP (0) // code block disabled
d1 – Report only “DEBUG_” directives defined as non-zero.
  Example: #define DEBUG_ILOOP (1) // code block enabled
D – Report all instances of all directives.
  Examples: #define PATH_MAX (1024)
#define DLG_ROWS (16)
#define HIDDEN_TREASURE "Dead Man's Cove"
D0 – Report only instances of directives which are defined as zero (0).
  Examples: #define ENABLE_VERBOSE_OUTPUT (0)
#define ENABLE_CURSES_BUG_FIX (0)
D1 – Report only instances of directives which are defined as non-zero.
  Examples: #define ENABLE_VERBOSE_OUTPUT (1)
#define FILEDLG_INCLUDED
#define appVersion "1.2.14"
  

Optional Parameters

Optional parameters are identified by one (or two) leading dash (hyphen) characters.
Parameters which require arguments are constructed using an ‘equals’ character: ‘=’ as shown in the examples below. Arguments which include whitespace must be enclosed within single or double quotes so the shell program will interpret the argument as a single token.

• –src="FILES" Source Files To Be Scanned (optional)
  Specify any regex sequence which specifies the file(s) to be scanned.
  The default specification is  “*.[hc]pp”  which indicates a scan of all files in the CWD (current working directory) with a filename extension of either: ".cpp" or ".hpp".
  Examples: gpit.pl a -src="FileDlg*.cpp"
  gpit.pl c -src="Ansi*.[hc]pp Makefile"
  gpit.pl t -src="HelloWorldApp.java"
  gpit.pl t -src="Take Out the Trash.pl"
  


• –incl="TOKEN" Inclusion Secondary Filter (optional)
  Data collected during the primary scan are subjected to a second scan so that only data which
  matches both tokens are reported.
  Examples: gpit.pl D -incl='Media'
  (Include all matches with both "#define" and "Media" tokens.)
  gpit.pl t -incl='EXPERIMENTAL'
  (Include all matches with both "TEMP" and "EXPERIMENTAL" tokens.)


• –excl="TOKEN" Exclusion Secondary Filter (optional)
  Data collected during the primary scan are subjected to a second scan so that only data which
  matches the first token but not the second token are reported.
  Examples: gpit.pl a -excl='FileDlgMedia.cpp'
  (Include all matches found except those found in the specified file.)
  gpit.pl t -excl='jpeg files'
  (Include all "TEMP" matches which do not include the "jpeg files" token.)


• –cnt Report only a count of matching substrings. (optional)
  By default, the source line which contain matching substrings are displayed; however, this option reports not the text of the lines matching the token, but rather a count of the matches found in each source file. As an example, scanning the two sample source files included in the distribution package:
  gpit.pl a -cnt
  would yield:
  

      'CZONE' tokens:
      Test1.cpp:3
      Test2.hpp:3
      'EXPERIMENTAL' tokens:
      Test1.cpp:3
      Test2.hpp:3
      'TEMP' tokens:
      Test1.cpp:3
      Test2.hpp:3

  In each test source file, there are three instances of each token for which the data were scanned.


• –case Perform a case-insensitive scan. (optional)
  By default, the source scan is case-sensitive. Use this option to make the primary scan and the secondary inclusion/exclusion scans (if specified) case-insensitive.


• –stdout Output results directly to “stdout” (optional)
  Bypass the ‘less’ utility and write directly to ‘stdout’.
  Useful when invoking from inside another script, or when the output is known to be small.


• –save Save captured data to a log file. (optional)
  Save captured data to a file in the CWD named: “gpit.log”. The temporary file to which the display data were captured is renamed and moved to the current working directory.


• –version Report application and version and copyright info. (optional)
  If available, the Perl version and copyright info. are also reported.


• –help Display application Help ‐ list command-line options. (optional)