# ********************************************************************* #
# CrYears.pl                                                            #
# ----------                                                            #
# Author : Mahlon R. Smith - The Software Samurai                       #
# Copyright (c) 2026 - 2027 Mahlon R. Smith, The Software Samurai       #
# On the web: https://www.SoftwareSam.us/                               #
#                    - - - - - - - - - -                                #
# Developed under: Perl v:5.42.3                                        #
#                  grep v:3.12                                          #
#                    - - - - - - - - - -                                #
# Note that this Read-Me file is basically just a spell-checked version #
# of the source file comments. Sorry for the duplication.               #
# ********************************************************************* #
# 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/>.                        #
# ********************************************************************* #
# Introduction:                                                         #
# -------------                                                         #
# This package includes the Perl script 'cryr.pl' which                 #
# demonstrates the use of grep to simplify updating of source           #
# code in preparation for creating a distribution package.              #
# Coincidentally, it also demonstrates some basic (and not-so-basic)    #
# Perl functionality and syntax.                                        #
#                                                                       #
# The author uses this program to scan for strings which represent a    #
# range of years, primarily in connection with copyright notices;       #
# hence, the name: CopyrightYears.pl                                    #
#                                                                       #
# It is also used to identify date ranges used in screenshots, diagrams #
# and other instances which may occasionally become stale when each     #
# new year arrives.                                                     #
# - - - - -                                                             #
# Also included in the package are some sample source code files        #
# in various programming languages. These may be used to test           #
# the functionality of 'cryr.pl'.                                       #
#   Example: cryr.pl -path='./1_TestData'      (see invocation options) #
# Note that 'test.cpp' is a fully-functional (but brain-damaged)        #
# application created in response to a student request and modified     #
# slightly for this package. The application can be built using the     #
# included 'Makefile'.                                                  #
#   cd 1_TestData                                                       #
#   gmake                                                               #
#   ./test --help                                                       #
# The miscellaneous other files in the 1_TestData directory are simply  #
# examples for testing the cryr.pl program.                             #
# - - - - -                                                             #
# The cryr.pl program can easily be modified to scan your source code   #
# for any often-included and occasionally-updated sequence, such        #
# as an address, a URL, contact information, version number, etc.       #
# --------------------------------------------------------------------- #
#                                                                       #
#                       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/cryears-0.0.02.tar.bz2 &nbsp; ./.                 #
# 3) Unpack the tar archive:                                            #
#       tar -xjvf cryears-0.0.02.tar.bz2                                #
# 4) Navigate to the target directory:                                  #
#       cd CrYears                                                      #
# 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.                                   #
# 6) To begin using cryr.pl, type:                                      #
#       ./cryr.pl --help                                                #
#                       - - - - - - - - - -                             #
# Package Contents:                                                     #
# -----------------                                                     #
# cryr.pl            - Perl script demonstrating grep scans             #
# README             - Release notes (this file)                        #
# 1_TestData/        - Sample source code modules                       #
#   test.cpp                                                            #
#   test.hpp                                                            #
#   Makefile                                                            #
#   base.texi                                                           #
#   df.py                                                               #
#   report.pl                                                           #
#   VERSION_HISTORY                                                     #
#   README             (a stub of this file)                            #
#                                                                       #
# ********************************************************************* #
# Invocation:  Usage: cryr.pl [OPTIONS]                                 #
# -----------                                                           #
# Invocation options fall into two categories:                          #
#  1) Selection of the files to be scanned.                             #
#  2) Setting the parameters for the scan.                              #
#                                                                       #
# File-specification options:                                           #
# ...........................                                           #
# When invoked without parameters, the files scanned will be all        #
# '.hpp' and '.cpp' files in the CWD.                                   #
#       Filename Regex: "*[.][hc]pp"                                    #
# This is the default basic source file group to be scanned.            #
#                                                                       #
# Note that the order in which filespec options are specified can       #
# affect which files are actually scanned.                              #
#                                                                       #
#   * -hpp : _replaces_ the default option, above.                      #
#   * -cpp : _replaces_ the default option, above.                      #
#   * -fspec='REGEX' parameter directly specifies the basic filename    #
#      group. Python example:  -fspec='*[.]py'                          #
#      -- To specify all the listed filename groups except '*.hpp'      #
#         and '*.cpp', use 'fspec' to specify a pattern that will       #
#         match no filenames. Example: cryr.pl --all --fspec='no_files' #
#      Technical Note: To decode filename groups, Bash uses POSIX ERE   #
#      regex which is not entirely equivalent to Perl "extended" regex. #
#                                                                       #
#   The other filespec options, '-texi', '-pl', '-make', '-aux'         #
#   are _added to_ the primary filespec option.                         #
#   * -texi : Scan all files with Texinfo source file extension:        #
#             "*[.]texi"                                                #
#   * -pl   : Scan all Perl scripts (with a filename extension)         #
#             "*[.]pl"                                                  #
#   * -make : Scan filenames which include the "Makefile" substring.    #
#             Examples: "Makefile" "myMakefile" "Makefile.bak"          #
#             (See also the case-insensitive option, below.)            #
#   * -aux  : Scan the common auxillary files typically included        #
#             in a distribution package:                                #
#                "README" and "VERSION_HISTORY"                         #
#   * -all : Adds all members of the above group to the list of files   #
#            to be scanned.                                             #
#                                                                       #
# Other Options:                                                        #
# ..............                                                        #
#   *  '-path=PATH' option:                                             #
#      By default, the current-working-directory (CWD) is scanned.      #
#      This option specifies an alternate directory to be scanned.      #
#   *  '-stdout' option:                                                #
#      By default, the captured data are piped through the 'less'       #
#      utility; however, if desired, '-stdout' can be used to bypass    #
#      'less' and write the data directly to stdout.                    #
#   *  '-icase' option:                                                 #
#      Because the primary scan is for strictly numeric data, case      #
#      sensitivity/insensitivity applies only to the secondary          #
#      inclusion/exclusion filters.                                     #
#   * '-incl=TOKEN' option:                                             #
#      This secondary filter is applied to the data captured during the #
#      primary scan. Only data matching _both_ primary and secondary    #
#      filters are reported.                                            #
#   *  '-excl=TOKEN' option:                                            #
#      This secondary filter is applied to the data captured during the #
#      primary scan. Only data matching the primary filter but _not_    #
#      the secondary filter are reported. See details below.            #
#      --  Special Case: Using the '-excl' option with an empty string  #
#          invokes a special case of the exclusion scan: Examples:      #
#             cryr.pl -excl=''                                          #
#             cryr.pl -excl=                                            #
#             (However, 'cryr.pl -excl' would be a syntax error)        #
#          This specifies that the text of the exclusion filter is to   #
#          be automagically set to exclude primary-scan tokens which    #
#          end with the current year (as reported by the system).       #
#          In practice, this means that the report will exclude any     #
#          items which have already been updated for the current year.  #
#                   Too cute? or genius move? You decide...             #
#          For example, if the system reports the current year as 2027, #
#          then an invocation of:                                       #
#            cryr.pl -excl=                                             #
#          will report:                                                 #
#            // Copyright 2020-2026 Karen the Kourageous Koder          #
#            // Copyright 2020 - 2026 Patty the Perl Piggie             #
#            # Written by Ruby Redneck during a tequila binge:1998-1999 #
#          but will exclude:                                            #
#            // Copyright 2020-2027 Paul the Pythonian                  #
#            // Copyright 2020 - 2027 Rust-belt Randy                   #
#  *  '-version' option:                                                #
#     Report application name, version, and copyright information.      #
#  *  '-help' option:                                                   #
#     Display command-line help.                                        #
#                                                                       #
#  Notes:                                                               #
#  ......                                                               #
#  1) User friendliness begins with an acknowledgment that many users   #
#     are too bloody lazy to read the documentation; therefore,         #
#     as with many of the author's other script files, an option may    #
#     be specified using either a single dash or a double dash.         #
#     The following are equivalent:                                     #
#       cryr.pl -icase                                                  #
#       cryr.pl --icase                                                 #
#       cryr.pl ---------icase                                          #
#     The author believes that most script files (and many compiled     #
#     programs) would benefit from this simple syntax filter.           #
#                                                                       #
# ********************************************************************* #
#                      Misc. Developer Notes                            #
#                      ---------------------                            #
#                                                                       #
# The Primary Scan Regular Expression:                                  #
# ====================================                                  #
# Notes on the regular expression (regexp) used for scan for date-range #
# substrings. The basic target is a string of the form: "2021-2025" or  #
# minor variations on that form.                                        #
# NOTE: The syntax for the scan described below requires the grep       #
#       '-E' switch which enables "extended regex".                     #
# -- The range of valid dates is selected as the practical range, i.e.  #
#    the year 1900 through 2099. Those savants of the 1800s who created #
#    software using "stone knives and bearskins"* and the AI robots     #
#    who will replace human software nerds in the 2100s will, in our    #
#    opinion, just have to go regex themselves.                         #
#       * Mr. Spock, Star Trek - 'The City on the Edge of Forever'      #
# -- The [[: digit :]] bracket expressions match any of the ASCII       #
#    (Arabic) digits.                                                   #
# -- The substring groupings (19|20) match either a '19' or a '20'.     #
# -- The [-] glob matches a literal dash character. (The enclosing      #
#    brackets are not strictly necesssary, but they give a warm-fuzzy   #
#    regarding any potential "specialness" of the dash character.)      #
# -- The regex sequence " ?" indicates zero-or-one-instance of a        #
#    space character ' '. (This is not whitespace. It is a literal      #
#    character. Note that the '?' character is recognized as "special"  #
#    only when the grep '-E' option is used.                            #
#                                                                       #
# The Secondary Scan Filters:                                           #
# ===========================                                           #
# Inclusion Filter:                                                     #
# -----------------                                                     #
# The inclusion filter is applied to the data captured during the       #
# primary scan. This is done by writing the results of the primary scan #
# to a temporary file. 'grep' is then used to scan the temporary file.  #
# Only lines which include the inclusion token will be reported to the  #
# user.                                                                 #
#   Example:  cryr.pl -incl='Copyright'                                 #
# This report would include lines which contain both the primary token  #
# _and_ the word "Copyright" (case-sensitive).                          #
#   Reported:     "Copyright (c) 2004-2024, Bobo the Basement Troll"    #
#   Not Reported: const char* crYears = "2004-2024"; // copyright years #
# The second line is excluded because the scan is case-sensitive        #
# by default; therefore, to report both, use the '-icase' option:       #
#   cryr.pl -incl='Copyright' --icase                                   #
# or:                                                                   #
#    cryr.pl -incl='[cC]opyright'                                       #
#                                                                       #
# Exclusion Filter:                                                     #
# -----------------                                                     #
# The exclusion filter is applied to one of two sets of captured data:  #
#  1) Applied to the data captured during the primary scan.             #
#  2) Applied to the results of the inclusion-filter scan.              #
# This is done by writing the results of the previous scan to a         #
# temporary file. 'grep' is then used to scan the temporary file.       #
# Only lines which include the primary-scan token but _not_ the         #
# exclusion token will be reported to the user.                         #
#   Example:  -excl='[-] ?2026'                                         #
# This would exclude lines which have already been updated for the      #
# year 2026.                                                            #
#   Reported:      const char* crYears = "2004-2024";                   #
#   Not Reported:  const char* crYears = "2004-2026";                   #
# (See also the special case: "-excl=''" above.)                        #
#                                                                       #
# Special Characters:                                                   #
# -------------------                                                   #
# Both the shell program and the grep utility define a set of "special" #
# characters. Unfortunately, it is not the same set and the             #
# "specialness" of each character may be defined differently by each.   #
# If the filter argument is enclosed in single quotes, the shell will   #
# _probably_ pass special characters through without interpretation.    #
#        Example: --incl='[-] ?2023'                                    #
# This will match both "-2023" and "- 2023" as expected                 #
#                                                                       #
# The following will be passed through the shell without interpretation;#
# however, grep sees parentheses as "special" characters.               #
#        Example: --incl='(c)'                                          #
# In order for grep to see them as ordinary characters, they must be    #
# individually escaped.                                                 #
#        Example: --incl='\(c\)'                                        #
#        Example: --incl='[(]c[)]'                                      #
#                                                                       #
# Some "very special" characters are single-quote, double-quote and     #
# the dash character ('-').                                             #
# If searching for a single or double quote, then the argument should   #
# be enclosed in the opposite quote:                                    #
#        Example: --incl='This is a double-quote: "'                    #
#        Example: --incl="This is a single-quote: '"                    #
# The dash is special to the shell _only_ if it is the first character  #
# of the token; otherwise, it is an ordinary character:                 #
#        Example: --incl='\-Hello World!'                               #
#        Example: --incl='Hello-World!'                                 #
# Bash and other shell programs provide a way to get around the         #
# specialness of the leading dash character, and it is included in the  #
# syntax used in this program.                                          #
# The Bash "--" double-dash/double-hyphen operator is used to signal    #
# the end of command-line arguments for the utility being invoked.      #
# Any tokens following the double-dash will not be interpreted as       #
# grep invocation options, but will instead be passed to grep as        #
# operational parameters.                                               #
#        Example: grep -nHsE --color=always -- '-abc' -stupid_name.txt  #
# This means that the following inclusion filter will work as expected: #
#        Example: cryr --incl='-Hello World!'                           #
#                                                                       #
#   (Don't even get us started on the backtick [`] character, which)    #
#   (in the world of special characters, is poison-on-a-stick.     )    #
#                                                                       #
# --------------------------------------------------------------------- #
# Version History :                                                     #
# -----------------                                                     #
# See the source file.                                                  #
#                                                                       #
# ********************************************************************* #
