CommExtract - Release Notes

Copyright 2024 by The Software Samurai.
On the web: http://www.SoftwareSam.us/
Software released under GNU GPL3, and documentation released under FDL1.3
This document describes version 0.0.02 of CommExtract.

---

Description

Description: Extract C++ comment lines from a source file, then remove the comment token (//) and leading/trailing whitespace, to create plain text which can then be inserted into the documentation for that project. The author has found this to be a useful tool, in that his development style for a new project is to write the comments first. The code is then written to implement the project described in those comments. This is ALSO the approach all of our students are encouraged to use for their class projects. The practical result of this approach is that the project documentation essentially writes itself. This is done by copying the bulk of the source code comments to a ReadMe file or to a Texinfo documentation file. However, it is rather tedious to manually remove the C++ comment tokens, so this simple utility performs that task automagically.

This application was designed under Fedora Linux and is built using the GNU C compiler,
version 13.3.1 or higher (C++11 support required).
If you are not using GCC, then verify that your compiler fully supports the C++11 standard.

---

Building From Source

• Download and unpack the distribution archive.
  • Navigate to the base directory where package will be installed (example):
       cd ~/SoftwareDesign
  • Move the archive file to the base directory:
       mv ~/Dowloads/commextract-0.0.02.tar.bz2  
  • Unpack the tar archive:
       tar -xjvf commextract-0.0.02.tar.bz2
  • Navigate to the target directory:
       cd CommExtract
• After unpacking the archive, the directory will look something like this:

  /home/sam/Software/CommExtract/CommExtract.hpp   <== Application class definition
                                /CommExtract.cpp   <== Application definition and implementation
                                /CxFile.hpp        <== File management definitions
                                /CxFile.cpp        <== File management implementation
                                /gString.hpp       <== gString class definition
                                                       (text analysis and formatting)
                                /gString.cpp       <== gString class implementation 
                                /Makefile          <== Build the 'comex' application
                                /create_archive.pl <== Sample Perl script
                                /README            <== Package description, release notes
  

• Build the application:
     gmake all
  
  The GNU G++ compiler is invoked to build and link the binary executable file.
  The application should build without errors and without warnings.
• Test the build:
     ./comex − −version
  The application version and a copyright message should be displayed.

  CommExtract (comex) v:0.0.02 Copyright(c) 2024-____  The Software Samurai
  =========================================================================
  License GPLv3+: GNU GPL version 3 
  This is free software: you are free to modify and/or redistribute it
  under the terms set out in the license.
  There is NO WARRANTY, to the extent permitted by law.
  

• For invocation options, type:
     ./comex − −help
  See the next section for a description of command-line options.
• Make the application visible on the system $PATH:
  This can be done in either of two ways:
    1) copy the executable to a directory on the path:
        cp − −preserve=all ./comex   ~/usr/local/bin/.
    2) create a symbolic link to the executable in the source directory.
        cp − −symbolic-link ./comex   ~/usr/local/bin/.
  

---

Operational Overview

The CommExtract application is controlled via command-line options. No direct user interaction is required.

Output is written to the specified target file, and may optionally be echoed to the terminal window.

This application relies on our gString text-analysis tool for parsing the source data and reformatting the data for output. For a full discussion of the gString class, please see the documentation for the author's NcDialog API package, or the stand-alone gString text-analysis-and-formatting package. gString Documentation

---

Command-line Options

Invocation:    comex ––src=NAME ––beg=n [––end=n | ––cnt=n] [OPTIONS]

• Options may be specified in any order.
• Options are not case sensitive.
• The ‘– –help’ option overrides everything except the ‘– –version’ option.
• The ‘– –version’ option overrides all other options.
• Three(3) parameters are required:
  
  1. Name of the source file to be scanned
  2. Line number of first source line to be scanned. (1-based)
  3. The range of lines to be scanned. This may be specified in either of two ways:
       a) The line number of the last source line to be scanned (inclusive).
            OR
       b) The count of source lines to be scanned.
     These parameters are mutually exclusive, so specify only one. If both are specified, the last one seen will take precedence.

  Example: comex --src=MySource.cpp --beg=1 --end=24 comex MySource.cpp --beg=1 --cnt=24

  All other parameters are optional.

• – –src=FILENAME     Specify the file containing the source text.

  It is recommended that the specified source file be in the current working directory (CWD); although this is not enforced.
  As a convenience, the "––src" switch may be omitted IF the source filename is the first argument on the command line. (see example above)



• – –beg=LINE_NUMBER     Specify the first source line to be processed (1-based).

  All preceeding source lines will be ignored.



• – –end=LINE_NUMBER     Specify the last source line to be processed (1-based).

  This value must be greater than the value specified by the ––beg option. Processing will continue until the specified source line has been processed, or until end-of-file is reached.
  See also the ––cnt option.



• – –cnt=LINE_COUNT     Specify the number of source lines to be processed.

  This must be a positive number. Processing will continue until the specified number of lines have been processed, or until end-of-file is reached.
  See also the ––end option.



• – –trg=FILENAME     (Optional)

  Specify the file to which the reformatted data will be written. It is recommended that the specified target file be in the current working directory (CWD); although this is not enforced.  If the target file is not specified, the default: xcom.txt will be used.



• – –deltrg     (Optional)

  By default, the reformatted data are appended to the existing contents of the target file. This is done to avoid potential loss of existing data; however, if desired, the ––deltrg option may be used to delete the contents of the target file (if any) before writing to output.



• – –wspall     (Optional)

  When reformatting the data, by default, the trailing whitespace is removed, while the leading whitespace is retained in order to retain the indenting of the text. If desired, the ––wspall option may be used to remove both leading and trailing whitespace.



• – –echo     (Optional)

  By default, a minimum amount of information is written to the display; however, if desired,
  the ––echo option may be used to write the formatted data to the display in addition to writing to the target file.



• – –help     Display application help, then exit. The shortcut –h is also recognized.
• 
  
• – –version     Display application version and copyright information, then exit.

---

Notes on the current release of “CommExtract”

1. Because this is a smelly old hack and not a production-worthy application, we assume that the user IS the owner of the source and target files and of the directory in which they live. This simplifies the access-validation process. For a more robust validatation of file access, see our FileMangler application.
   
2. It is expected (but not enforced) that source and target files are in the current working directory (CWD). It would be rather dangerous to create and/or truncate a target file at some random position in the filesystem.
              Beware!
   
3. The actual reformatting of the text data is handled by the gString class. The gString source included in this package is also available as a stand-alone package and well as being integrated into our NcDialog API library. Please see: gString Documentation
4. If the source data contains ASCII Tab characters (0x09): first, don't ever use tabs in source code, and second, the columns of the output will be misaligned. Sorry about that :)
5. Terminal Configuration:
   1. The width of the I/O streams are set the first time they are used. The wide input/output streams are accessed through the ‘wcin’ and ‘wcout’ classes, respectively. The narrow input/output streams are accessed through the ‘cin’ and ‘cout’ classes, respectively. Narrow streams are not used in this application.
      (Editorial: No application written in the current century should use narrow-stream I/O.)
   2. The terminal's “locale” determines the character encoding used, and the primary language expected. This determines the way the terminal will handle certain text formatting — for instance, currency symbols and number formats. It is important to understand that if the application does not explicitly set the desired locale, the so-called “C-locale” is used. The C-locale restricts the character set to an ASCII superset (7-8-bit characters), and is unacceptable for any serious application. Besides, it is so easy to implement that it can be added to any application in under five minutes. See the setLocale method for details.
6. The file ‘create_archive.pl’ is included in this package only as an example of using Perl to perform file-management chores. Your humble author is certainly no expert in the Perl language, but the code provides examples for some simple constructs. ‘create_archive.pl’ is used during the development process to verify the state of conditional-compilation declarations, to extract the application version number and to create the distribution archive.
7. Data Processing Logic:
   For each source line in the specified range:
   1. Scan over leading whitespace. If first non-whitespace characters are not  “//” , skip the line.
   2. If first non-whitespace is  “//” , i.e. a C++ comment:
      1. If “//” is followed by ‘*’, include it in sequence to be deleted.
      2. If “//” or “//*” is followed by a space, include it in sequence to be deleted, (2, 3 or 4 characters, total).
   3. If the line ends with a trailing ‘*’, remove it.
   4. Strip whitespace:
      1. If the ‘wspAll’ flag is set, strip both leading and trailing whitespace.
      2. Else, strip trailing whitespace only. (maintains vertical column alignment)
   5. Append a single space to the end of the line.
   6. Write the reformatted text to the output file.
8. Note: The application change log is located in the header of “CommExtract.cpp”.

These notes are adapted from the “README” file included with the application archive.   Thank you, and we hope you enjoy using this application!  — Software Sam