# *************************************************************** #
# GrepIt                                                          #
# ------                                                          #
# Author : Mahlon R. Smith - The Software Samurai                 #
# Copyright (c) 2026-2027 Mahlon R. Smith, The Software Samurai   #
#                    - - - - - - - - - -                          #
# This document describes version 0.0.03 of GrepIt (gpit.pl).     #
# Developed under: Perl v:5.42.3                                  #
# *************************************************************** #
# Copyright Notice:                                               #
# -----------------                                               #
# This program is free software: you can redistribute it and/or   #
# modify it under the terms of the GNU General Public License     #
# as published by the Free Software Foundation, either            #
# version 3 of the License, or (at your option) any later version.#
#                                                                 #
# This program is distributed in the hope that it will be useful, #
# but WITHOUT ANY WARRANTY; without even the implied warranty of  #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.            #
# See the GNU General Public License for more details.            #
#                <http://www.gnu.org/licenses/>.                  #
# *************************************************************** #
# This package includes the gpit.pl Perl script which demonstrates#
# demonstrates some simple Perl concepts in the context of using  #
# the 'grep' utility to scan source code for specific tokens.     #
#                                                                 #
# 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 Convert(" << cval << 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                                        #
#                                                                 #
# When preparing the distribution archive, 'gpit.pl' is used to   #
# identify these smelly constructs, so they can be removed:       #
#                    - - - - - - - - - -                          #
#                                                                 #
# Unpack the Archive:                                             #
# -------------------                                             #
# 1) Navigate to the base directory where package will be         #
#    installed (example):                                         #
#       cd ~/Software                                             #
# 2) Move the archive file to the base directory:                 #
#       mv ~/Dowloads/grepit-0.0.03.tar.bz2 &nbsp; ./.            #
# 3) Unpack the tar archive:                                      #
#       tar -xjvf grepit-0.0.03.tar.bz2</span>                    #
# 4) Navigate to the target directory:                            #
#       cd GrepIt                                                 #
# 5) 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.                             #
#                    - - - - - - - - - -                          #
# Package Contents:                                               #
# -----------------                                               #
# gpit.pl            - Perl script demonstrating grep scans       #
# Test1.cpp          - Sample source code modules                 #
# Test2.hpp                                                       #
# README             - Release notes (this file)                  #
#                    - - - - - - - - - -                          #
# To access the utility from any current-working-directory (CWD), #
# do one of the following:                                        #
# 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&nbsp; gpit                                          #
#                                                                 #
# *************************************************************** #
# gpit.pl Command Line Options:                                   #
# -----------------------------                                   #
# Usage: gpit.pl SCAN_TOKEN [OPTIONS]                             #
#                                                                 #
# An option which does not begin with a dash ('-') character      #
# is assumed to be a filename.                                    #
#                                                                 #
# Scan Token                                                      #
# ----------                                                      #
# 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.                                  #
#                                                                 #
# The SCAN_TOKEN character is required. If not specified, then    #
# command-line help will be displayed.                            #
# All other options are optional.                                 #
#                                                                 #
# 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 the    #
#         "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)                                               #
#                                                                 #
# *************************************************************** #
# Tech Notes:                                                     #
# -----------                                                     #
# The functionality available in any Perl script depends heavily  #
# upon the version of Perl installed and the modules loaded.      #
# This script uses the standard modules available by default      #
# for the version currently installed.                            #
# (experimental code is not used)                                 #
# The version used for development of this project is: v5.42.3    #
# The pragma used at the top of the file is: "use v5.40"          #
#                                                                 #
#                                                                 #
#                                                                 #
#                                                                 #
# *************************************************************** #
