CrYears - 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

   CrYears (cryr.pl): version 0.0.02
   Developed under : Perl v:5.42.3
                     Grep v:3.12

---

Description

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 originally 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.

---

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/cryears-0.0.02.tar.bz2   ./.
• Unpack the tar archive:
     tar -xjvf cryears-0.0.02.tar.bz2
• Navigate to the target directory:
     cd  CrYears
  The expanded archive should include the following files:

     cryr.pl              - Perl script dempnstrating grep scans
     README               - Release notes (this file)
     1_TestData           - Subdirectory containing test data
       test.cpp
       test.hpp
       Makefile
       Base.texi
       df.py
       report.pl
       VERSION_HISTORY
       README

• 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 cryr.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  ./cryr.pl  ~/bin/.
  • Create a symlink in a directory on the execution path.
       cp ‐‐symbolic-link  ./cryr.pl  ~/bin/cryr
  • Create a shell script to reference the Perl script.
    #!/bin/bash
    ~/SoftwareDesign/CrYears/cryr.pl $1 $2 $3 $4 $5 $6 $7 $8
    Save to a convenient name. Example: '~/bin/cryr'
    Be sure to set the shell script as executable.
       chmod  +x  cryr

---

Command-line Options for ‘cryr.pl’

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 (Current-Working-Directory). This is the “Regular Expression” (regex) specifying the default basic source file group to be scanned:   *[.][hc]pp
Note that the order in which filespec options are specified can affect which files are actually scanned.

• –hpp  :  replaces the default option, above.
  Report all files in CWD which have a filename extension of .hpp


• –cpp  :  replaces the default option, above.
  Report all files in CWD which have a filename extension of .cpp


• –fspec='REGEX'  :  directly specifies the basic filename group.
       Python example:   -fspec='*[.]py'
  

  To exclude the '*.hpp' and '*.cpp' filename group, 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, so if if your regular expressions are not behaving as expected, please compare these two syntax standards.

The other filespec options, '-texi','-pl','-make','-aux' are added to the primary filespec option.
For example: “cryr.pl -pl”  will scan all files in the CWD with extensions of '.hpp','.cpp' and '.pl'.

• –texi  :  Scan all files with Texinfo source file extension:   “*[.]texi”


• –pl  :  Scan all Perl scripts (those identified with a filname extension of:   “*[.]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.
      Example:   cryr.pl -all
  This invocation will scan all files with extensions of '.hpp', '.cpp', '.texi', '.pl', all filenames containing the 'Makefile' substring, as well as the “README” and “VERSION_HISTORY” files.

Other Options

• –path='PATH' path of directory to be scanned (relative or absolute).
  By default, the current-working-directory (CWD) is scanned. This option specifies an alternate directory to be scanned. For example, to scan all the test files bundled with this program:
       ./cryr.pl --path='./1_TestData' -all


• –stdout' write scan results directly to stdout.
  By default, the captured data are piped through the 'less' utility; however, if desired, the '-stdout' option can be used to bypass 'less' and write the data directly to the terminal window.


• –icase perform case-insensitive scan.
  By default, all grep scans are case-sensitive; however, a case-insensitive scan may be specified.
  Note that because the primary scan is for strictly numeric data, case sensitivity/insensitivity will be applied only to the secondary inclusion/exclusion filters. (see next item)


• –incl='TOKEN' report source lines which include the specified token.
  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' desc
  This secondary filter is applied to the data captured during the primary scan.
  Only data matching the primary scan token, but not secondary filter are reported.
  Example:   ./cryr.pl -excl='obsolete' -icase
  This record would be reported:

          Sale! Offer good 2025-2026 only. Buy Now!

  but the following records would be excluded:
  

          Sale! Offer good 2024-2025 only. Buy Now! OBSOLETE
          Sale! Offer good 2023-2024 only. Buy Now! Obsolete
          Sale! Offer good 2022-2023 only. Buy Now! obsolete

  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.
  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 Report application name, version and copyright info.
  If available, the Perl version and copyright info. is also reported.


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

---

Notes

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 to 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 ' '. Note that 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

Technical Note:It is possible (though unlikely) that the secondary filters could match text in the temporary buffer which represents an embedded ANSI color escape sequence inserted by the grep utility rather than actual source code.
Color escape sequences take the general form:
ESC [  0  1  ;  3  1  m
1b  5b 30 31 3b 33 31 6d
If this happens, adjust the search token to exclude the ANSI sequence.

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 contain 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:
Example: cryr.pl -incl='Copyright' -icase
or
Example: 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.
Example: -excl='[-] ?2026'
This would exclude lines which have already been updated for the year 2026.
Reported:
const char* crYears = "2004-2025";
const char* crYears = "2004 - 2025";
Not Reported:
const char* crYears = "2004-2026";
const char* crYears = "2004 - 2026";
(See also the special case of the: “-excl=''” option described 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!'             (backslash '\' removes the specialness)
Example: --incl='Hello-World!'               (not the first character of token)
Bash and other shell programs provide a way to get around the specialness of the leading dash character, and this special invocation syntax is used by cryr.pl:
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 nonportable filename.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.