diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..8d78c5d
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,64 @@
+root = true
+
+# Language indent/EOL/charset overlap with .vscode/settings.json.
+# Rulers, renderWhitespace, detectIndentation, mergeEditor, and
+# cmake.configureOnOpen cannot be expressed here — they stay in settings.json.
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = tab
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# [bat]
+[*.{bat,cmd}]
+end_of_line = crlf
+indent_size = 4
+indent_style = space
+
+# [c]
+[*.{c,h}]
+indent_size = 4
+indent_style = space
+
+# [cmake]
+[{CMakeLists.txt,*.cmake}]
+indent_size = 4
+indent_style = tab
+
+# [cpp]
+[*.{cpp,cxx,hpp,hxx}]
+indent_size = 4
+indent_style = space
+
+# [json]
+[*.json]
+indent_size = 2
+indent_style = space
+
+# [markdown]
+[*.md]
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = false
+
+# [ruby]
+[*.{gemspec,rb}]
+indent_size = 2
+indent_style = space
+
+[{Gemfile,Rakefile}]
+indent_size = 2
+indent_style = space
+
+# [shellscript]
+[*.{bash,sh,zsh}]
+indent_size = 2
+indent_style = space
+
+# [yaml]
+[*.{yaml,yml}]
+indent_size = 2
+indent_style = space
diff --git a/.gitattributes b/.gitattributes
index e69de29..2c70232 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -0,0 +1,75 @@
+# .gitattributes — Ruby (GitHub-hosted)
+#
+# Sources: GitHub Docs (line endings), git-scm gitattributes (diff=ruby),
+# gitattributes/gitattributes Common.gitattributes + Web (*.rb),
+# github-linguist overrides.
+
+# Default: detect text, normalize to LF in the repository
+* text=auto
+
+# --- Source ---
+*.gemspec text eol=lf diff=ruby
+*.rake text eol=lf diff=ruby
+*.rb text eol=lf diff=ruby
+*.ru text eol=lf diff=ruby
+Gemfile text eol=lf diff=ruby
+Rakefile text eol=lf diff=ruby
+Capfile text eol=lf diff=ruby
+Guardfile text eol=lf diff=ruby
+*.erb text
+*.haml text
+*.slim text
+
+# --- Lock / config ---
+Gemfile.lock text
+*.gemspec.lock text -diff
+*.yml text
+*.yaml text
+*.toml text
+*.json text
+
+# --- Scripts ---
+*.bash text eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+*.sh text eol=lf
+*.zsh text eol=lf
+
+# --- Docs / meta ---
+*.adoc text
+*.markdown text diff=markdown
+*.md text diff=markdown
+*.txt text
+AUTHORS text
+CHANGELOG text
+CHANGES text
+CONTRIBUTING text
+COPYING text
+LICENSE text
+NEWS text
+README text
+TODO text
+.gitattributes text
+.gitignore text
+
+# --- Binary ---
+*.gem binary
+*.so binary
+
+# --- Archives / images (common) ---
+*.gif binary
+*.gz binary
+*.ico binary
+*.jpeg binary
+*.jpg binary
+*.png binary
+*.tar binary
+*.zip binary
+
+# --- GitHub Linguist ---
+**/vendor/bundle/** linguist-vendored
+**/vendor/cache/** linguist-vendored
+**/coverage/** linguist-generated
+**/doc/** linguist-documentation
+**/pkg/** linguist-generated
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..3189593
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - directory: /
+    package-ecosystem: bundler
+    schedule:
+      interval: weekly
+  - directory: /
+    package-ecosystem: github-actions
+    schedule:
+      interval: weekly
diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml
new file mode 100644
index 0000000..6e63b88
--- /dev/null
+++ b/.github/workflows/ruby.yml
@@ -0,0 +1,117 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+#
+# Created: 15th August 2026
+# Updated: 15th August 2026
+#
+
+name: Ruby
+
+on:
+  push:
+    branches:
+      - master
+      - dev
+      - boilerplate
+      - idiomatic
+      - rc1
+      - rc2
+      - rc3
+  pull_request:
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        os:
+          - macos-latest
+          - ubuntu-latest
+          - windows-latest
+
+        ruby-version:
+          # - head
+          - '3.4'
+          - '3.3'
+          - '3.2'
+          - '3.1'
+          - '3.0'
+          - '2.7'
+          - '2.6'
+
+        include:
+          - os: ubuntu-latest
+            ruby-version: '2.5'
+          - os: ubuntu-latest
+            ruby-version: '2.4'
+          - os: ubuntu-latest
+            ruby-version: '2.0'
+          - os: windows-latest
+            ruby-version: mingw
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - name: Checking out code
+      uses: actions/checkout@v4
+
+    - name: Remove Gemfile.lock
+      run: rm -f Gemfile.lock
+
+    - name: Set up Ruby v${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+    - name: Show Ruby version
+      run: ruby -v
+
+    - name: Run tests
+      run: bundle exec rake test
+
+    - name: Gem build and install smoke
+      shell: bash
+      run: |
+        gem build cmpfs.gemspec
+        gem install --local cmpfs-ruby-*.gem
+        ruby -e "require 'cmpfs/version'; abort('VERSION missing') unless defined?(CmpFS::VERSION); puts CmpFS::VERSION"
+
+  warnings:
+
+    name: Warnings
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checking out code
+      uses: actions/checkout@v4
+
+    - name: Remove Gemfile.lock
+      run: rm -f Gemfile.lock
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.3'
+        bundler-cache: true
+
+    - name: Show Ruby version
+      run: ruby -v
+
+    - name: Run unit tests with warnings
+      run: ./run_all_unit_tests.sh --lib --warnings
diff --git a/.gitignore b/.gitignore
index 0677442..0d510c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,57 +1,44 @@
-
 # directories (by name)
 
+/.bzr/
 /.bundle/
+/.config/
 /.svn/
 /.yardoc/
 
 /_yardoc/
 
+/InstalledFiles/
 /build/
-/build-iPhoneOS/
-/build-iPhoneSimulator/
 /coverage/
 /doc/
-/rdoc/
 /lib/bundler/man/
+/old-gems/
 /pkg/
+/rdoc/
+/scratch/
 /spec/reports/
 /test/tmp/
 /test/version_tmp/
 /tmp/
 /vendor/bundle/
-/InstalledFiles/
-
 
 # directories (by pattern)
 
-
 # files (by name)
 
 .DS_Store
-.bundle
-.config
 .repl_history
+.ruby-version
 .rvmrc
-.yardoc
-
-_yardoc
-
-Gemfile.lock
-InstalledFiles
-coverage
-pkg
-rdoc
 
 /spec/examples.txt
 
-
 # files (by pattern)
 
-.dat*
-
 *~
 *.*~
+.dat*
 *.b64
 *.bridgesupport
 *.gem
@@ -61,4 +48,3 @@ rdoc
 *.swp
 *.tmp
 *.zip
-
diff --git a/.ruby-version b/.ruby-version
deleted file mode 100644
index ef538c2..0000000
--- a/.ruby-version
+++ /dev/null
@@ -1 +0,0 @@
-3.1.2
diff --git a/.ruby-version-exclusions b/.ruby-version-exclusions
index 30e2993..442b295 100644
--- a/.ruby-version-exclusions
+++ b/.ruby-version-exclusions
@@ -1,10 +1,2 @@
 1.8.7-p375
-#1.9.3-p551
-#2.0.0-p648
-#2.1.10
-#2.2.10
-#2.3.8
-#2.4.5
-#2.5.3
-#2.6.1
 
diff --git a/.sis/project_name.txt b/.sis/project_name.txt
new file mode 100644
index 0000000..b654a98
--- /dev/null
+++ b/.sis/project_name.txt
@@ -0,0 +1 @@
+cmpfs.Ruby
diff --git a/.vimrc b/.vimrc
new file mode 100644
index 0000000..b8184be
--- /dev/null
+++ b/.vimrc
@@ -0,0 +1,70 @@
+" Synesis Ruby project .vimrc — aligned with .vscode/settings.json (2-space Ruby)
+
+set nocompatible
+filetype indent plugin on
+syntax enable
+set autoindent
+set backspace=indent,eol,start
+set hlsearch
+set incsearch
+set number
+
+" files.insertFinalNewline
+set eol
+set fixeol
+
+" editor.renderWhitespace: all
+set list
+set listchars=tab:->,trail:-,extends:>,precedes:<,nbsp:+
+
+" editor.detectIndentation: false — global defaults (editor.tabSize: 2, insertSpaces: true)
+set colorcolumn=76
+set expandtab
+set shiftwidth=2
+set softtabstop=2
+set tabstop=2
+
+" colorcolumn draws a full-column tint in Vim (not a VS Code-style 1px line).
+" Keep it subtle via the ColorColumn highlight group; reapply after colorscheme changes.
+if has('termguicolors')
+  " set termguicolors
+endif
+
+function! s:ConfigureColorColumn() abort
+  highlight ColorColumn ctermbg=236 guibg=#2a2a2a cterm=NONE gui=NONE
+endfunction
+
+call s:ConfigureColorColumn()
+autocmd ColorScheme * call s:ConfigureColorColumn()
+
+" files.trimTrailingWhitespace
+autocmd BufWritePre * %s/\s\+$//e
+
+augroup sis_c_cxx
+  autocmd!
+
+  " [c] / [cpp]
+  autocmd FileType c,cpp setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,64,68,72,76
+
+  " [rust]
+  autocmd FileType rs setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=76
+
+  " [cmake]
+  autocmd FileType cmake setlocal noexpandtab tabstop=4 shiftwidth=4 softtabstop=4
+
+  " [shellscript]
+  autocmd FileType sh,bash,zsh setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 colorcolumn=60,76
+
+  " [bat]
+  autocmd FileType bat,dosbatch setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
+
+  " [json] / [markdown] / [yaml] / [ruby]
+  autocmd FileType json,markdown,yaml,ruby setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2
+
+  " [python]
+  autocmd FileType python setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
+
+  " [toml]
+  autocmd FileType toml setlocal noexpandtab tabstop=2 shiftwidth=2 softtabstop=2
+augroup END
+
diff --git a/.vscode/settings.json b/.vscode/settings.json
index d9e8963..19efccd 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,10 +1,43 @@
 {
-  "[ruby]": {
-      "editor.tabSize": 2,
-  },
-  "cmake.configureOnOpen": false,
-  "editor.detectIndentation": false,
-  "editor.insertSpaces": true,
-  "editor.tabSize": 2,
-  "files.trimTrailingWhitespace": true,
+	"[json]": {
+		"editor.insertSpaces": true,
+		"editor.tabSize": 2,
+	},
+	"[markdown]": {
+		"editor.insertSpaces": true,
+		"editor.tabSize": 2,
+	},
+	"[python]": {
+		"editor.insertSpaces": true,
+		"editor.rulers": [ 60, 76 ],
+		"editor.tabSize": 4,
+	},
+	"[ruby]": {
+		"editor.defaultFormatter": "Shopify.ruby-lsp",
+		"editor.formatOnSave": true,
+		"editor.formatOnType": true,
+		"editor.insertSpaces": true,
+		"editor.rulers": [ 60, 76 ],
+		"editor.semanticHighlighting.enabled": true,
+		"editor.tabSize": 2,
+	},
+	"[shellscript]": {
+		"editor.insertSpaces": true,
+		"editor.rulers": [ 60, 76 ],
+		"editor.tabSize": 2,
+	},
+	"[toml]": {
+		"editor.insertSpaces": false,
+		"editor.tabSize": 2,
+	},
+	"cmake.configureOnOpen": false,
+	"editor.detectIndentation": false,
+	"editor.insertSpaces": false,
+	"editor.renderWhitespace": "all",
+	"editor.rulers": [ 76 ],
+	"editor.tabSize": 2,
+	"files.insertFinalNewline": true,
+	"files.trimTrailingWhitespace": true,
+	"git.mergeEditor": false,
+	"rubyLsp.formatter": "auto",
 }
diff --git a/AUTHORS.md b/AUTHORS.md
new file mode 100644
index 0000000..72922f0
--- /dev/null
+++ b/AUTHORS.md
@@ -0,0 +1,21 @@
+# cmpfs.Ruby - Authors <!-- omit in toc -->
+
+
+## Major Contributors
+
+| Name        | GitHub                            |
+| ----------- | --------------------------------- |
+| Matt Wilson | [mwsis](https://github.com/mwsis) |
+
+
+## Defect reports, fixes and suggestions (for which we are very grateful)
+
+| Name        | GitHub                            |
+| ----------- | --------------------------------- |
+| \<none>     |                                   |
+
+
+Contributions are welcomed.
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/CHANGES.md b/CHANGES.md
index 34fb2ca..457beeb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,4 +1,70 @@
-# **cmpfs.Ruby** Changes
+# cmpfs.Ruby - Changes <!-- omit in toc -->
 
-T.B.C.
 
+## 0.2.4 - 15th August 2026
+
+* added `# frozen_string_literal: true` to all **lib/** sources;
+* completed **EXAMPLES.md** catalogue for existing examples;
+
+
+## 0.2.3 - 4th April 2024
+
+* fixed restrictive Ruby 2.x dependency in gemspec;
+
+
+## 0.2.2.1 - 4th April 2024
+
+* fixed license to canonical form;
+
+
+## 0.2.2 - 4th April 2024
+
+* fixed restrictive Ruby 2.x dependency in gemspec;
+
+
+## 0.2.1.4 - 3rd April 2024
+
+* tidying and documentation;
+
+
+## 0.2.1.3 - 3rd April 2024
+
+* tidying and documentation;
+
+
+## 0.2.1.2 - 2nd April 2024
+
+* tidying, documentation, and project boilerplate;
+
+
+## 0.2.1.1 - 2nd April 2024
+
+* merged **boilerplate** into **master**;
+
+
+## 0.2.1 - 11th April 2019
+
+* tidyings;
+
+
+## 0.2.0 - 13th March 2019
+
+* added `Compare.compare_text_files()`, `Compare.compare_text_streams()`, and `Compare.compare_text()`;
+
+
+## 0.1.0 - 13th March 2019
+
+* sorted modules correctly for including and extending;
+
+
+## 0.0.1 - 12th March 2019
+
+* added missing `VERSION_REVISION`;
+
+
+## 0.0.0 - 12th March 2019
+
+* initial version;
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..d8bb0be
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# cmpfs.Ruby - Contributing <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Defects and features](#defects-and-features)
+- [Pull requests](#pull-requests)
+- [Tests](#tests)
+- [License](#license)
+
+
+## Defects and features
+
+Open an issue on https://github.com/synesissoftware/cmpfs.Ruby/issues.
+
+
+## Pull requests
+
+Pull requests are welcome on https://github.com/synesissoftware/cmpfs.Ruby. Keep diffs local to the change; match existing indentation (2 spaces in Ruby) and the Synesis markdown set (**README.md**, **CHANGES.md**, **NEWS.md**, **TODO.md**, **INSTALL.md**, **CONTRIBUTING.md**, **SECURITY.md**).
+
+
+## Tests
+
+```
+bundle exec rake test
+```
+
+or `./run_all_unit_tests.sh`.
+
+
+## License
+
+Contributions are accepted under the 3-clause BSD license. See [LICENSE](./LICENSE).
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/EXAMPLES.md b/EXAMPLES.md
index 23b5970..e4f3fdb 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -1,8 +1,9 @@
-# **cmpfs.Ruby** Examples
+# cmpfs.Ruby - Examples <!-- omit in toc -->
 
-|Name|Source & Description|Summary|
-|---|---|---|
+| Name                         | Source & Description                                                                                                                               | Summary                                                                              |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **compare_two_binary_files** | [examples/compare_two_binary_files.rb](/examples/compare_two_binary_files.rb)<br/>[examples/compare_two_binary_files.md](/examples/compare_two_binary_files.md) | Compares two files for binary equality via `compare_binary`                          |
+| **compare_two_text_files**   | [examples/compare_two_text_files.rb](/examples/compare_two_text_files.rb)<br/>[examples/compare_two_text_files.md](/examples/compare_two_text_files.md)     | Compares two files for text equality via `compare_text` (skip blank lines; trim)     |
 
 
-T.B.C.
-
+<!-- ########################### end of file ########################### -->
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..dd6783d
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,28 @@
+# cmpfs.Ruby - FAQ <!-- omit in toc -->
+
+The FAQ list is under (constant) development. If you post a question on the
+[Issues](https://github.com/synesissoftware/cmpfs.Ruby/issues) forum
+it will be used to create one.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Q1: "How do I install this library?"](#q1-how-do-i-install-this-library)
+
+
+# FAQs: <!-- omit in toc -->
+
+
+## Q1: "How do I install this library?"
+
+Install via **gem**:
+
+```
+gem install cmpfs-ruby
+```
+
+See [README.md](./README.md) for usage.
+
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/Gemfile b/Gemfile
index b22bf8f..29f6d2e 100644
--- a/Gemfile
+++ b/Gemfile
@@ -2,11 +2,15 @@
 
 source "https://rubygems.org"
 
-if RUBY_VERSION >= '2'
+gemspec
 
-  gem "xqsr3", '~> 0.39'
+# rake 13 requires Ruby >= 2.3
+if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.3")
+
+  gem "rake", '~> 13.0'
 else
 
-  gem 'xqsr3', '~> 0.21.3'
+  gem "rake", '~> 12.3'
 end
 
+gem "test-unit", '~> 3.0'
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..8d6765f
--- /dev/null
+++ b/Gemfile.lock
@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    cmpfs-ruby (0.2.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    xqsr3 (0.39.5)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  cmpfs-ruby!
+  xqsr3 (~> 0.39, >= 0.39.1)
+
+BUNDLED WITH
+   2.6.9
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..5ac5030
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,41 @@
+# cmpfs.Ruby - Installation and Use <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Install the gem](#install-the-gem)
+- [From a source checkout](#from-a-source-checkout)
+- [Using the library](#using-the-library)
+
+
+## Install the gem
+
+```
+gem install cmpfs-ruby
+```
+
+or add to a **Gemfile**:
+
+```Ruby
+gem 'cmpfs-ruby'
+```
+
+then `bundle install`.
+
+
+## From a source checkout
+
+```
+bundle install
+bundle exec rake test
+```
+
+
+## Using the library
+
+```Ruby
+require 'cmpfs'
+```
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/LICENSE b/LICENSE
index 61b84ab..1652284 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,22 +1,22 @@
-cmpfs.Ruby
+cmpfs.Ruby - BSD 3-Clause License
 
-Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 Copyright (c) 2019, Matthew Wilson and Synesis Software
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimer.
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
-* Neither the names of cmpfs or cmpfs.Ruby nor the names of its contributors
-  or its copyright holders may be used to endorse or promote products
-  derived from this software without specific prior written permission.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
diff --git a/NEWS.md b/NEWS.md
new file mode 100644
index 0000000..af22b41
--- /dev/null
+++ b/NEWS.md
@@ -0,0 +1,20 @@
+# cmpfs.Ruby - News <!-- omit in toc -->
+
+| Date             | News Item                                                                                |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| 15th August 2026 | [**cmpfs.Ruby** 0.2.4](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.4) |
+| 4th April 2024   | [**cmpfs.Ruby** 0.2.3](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.3) |
+| 4th April 2024   | **cmpfs.Ruby** 0.2.2.1 released                                                          |
+| 4th April 2024   | **cmpfs.Ruby** 0.2.2 released                                                            |
+| 3rd April 2024   | **cmpfs.Ruby** 0.2.1.4 released                                                          |
+| 3rd April 2024   | **cmpfs.Ruby** 0.2.1.3 released                                                          |
+| 2nd April 2024   | **cmpfs.Ruby** 0.2.1.2 released                                                          |
+| 2nd April 2024   | **cmpfs.Ruby** 0.2.1.1 released                                                          |
+| 11th April 2019  | **cmpfs.Ruby** 0.2.1 released                                                            |
+| 13th March 2019  | **cmpfs.Ruby** 0.2.0 released                                                            |
+| 13th March 2019  | **cmpfs.Ruby** 0.1.0 released                                                            |
+| 12th March 2019  | **cmpfs.Ruby** 0.0.1 released                                                            |
+| 12th March 2019  | **cmpfs.Ruby** 0.0.0 released                                                            |
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/README.md b/README.md
index 06ad37a..4fe1341 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
 **Com**pare **F**ile-**S**ystem entities, for **Ruby**
 
 [![Gem Version](https://badge.fury.io/rb/cmpfs-ruby.svg)](https://badge.fury.io/rb/cmpfs-ruby)
+[![Ruby](https://github.com/synesissoftware/cmpfs.Ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/synesissoftware/cmpfs.Ruby/actions/workflows/ruby.yml)
 
 
 ## Introduction
@@ -157,7 +158,7 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 
 ### Related projects
 
-T.B.C.
+* C/C++ **cmpfs** — same product idea (binary/text file and stream comparison); recovery into freelibs is planned beside this gem (not yet published as a sibling tree here);
 
 
 ### License
diff --git a/Rakefile b/Rakefile
new file mode 100644
index 0000000..424b0b7
--- /dev/null
+++ b/Rakefile
@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Rakefile for cmpfs.Ruby
+
+require 'rake/testtask'
+
+
+Rake::TestTask.new do |tt|
+
+  tt.libs << 'lib'
+  tt.libs << 'test'
+  tt.name = 'test'
+  tt.test_files = FileList['test/**/tc_*.rb']
+  tt.verbose = true
+end
+
+
+task :default => :test
+
+
+# ############################## end of file ############################# #
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..6529292
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,23 @@
+# cmpfs.Ruby - Security <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Reporting a vulnerability](#reporting-a-vulnerability)
+- [Supported versions](#supported-versions)
+
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub Security Advisories on https://github.com/synesissoftware/cmpfs.Ruby/security, or by opening an issue if an advisory cannot be filed. Do not attach exploit proofs of concept against third-party systems.
+
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.2.x   | ✅        |
+| < 0.2   | ❌        |
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..94d7dbe
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,19 @@
+# cmpfs.Ruby - TODO <!-- omit in toc -->
+
+
+## Functional improvements
+
+* \<none>
+
+
+## Performance improvements
+
+* \<none>
+
+
+## Packaging improvements
+
+* [ ] Rename gemspec so the filename stem matches `spec.name` (`cmpfs.gemspec` → **cmpfs-ruby.gemspec**);
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/build_gem.cmd b/build_gem.cmd
new file mode 100644
index 0000000..c894c21
--- /dev/null
+++ b/build_gem.cmd
@@ -0,0 +1,13 @@
+@ECHO OFF
+
+REM ########################################################################
+REM File:     build_gem.cmd
+REM
+REM Purpose:  Builds the gem
+REM
+REM Created:  11th July 2016
+REM Updated:  14th August 2026
+REM
+REM ########################################################################
+
+FOR %%f IN (*.gemspec) DO gem build "%%f" %*
diff --git a/build_gem.sh b/build_gem.sh
index 479b6db..864823e 100755
--- a/build_gem.sh
+++ b/build_gem.sh
@@ -6,9 +6,8 @@
 # Purpose:  Builds the gem
 #
 # Created:  9th June 2016
-# Updated:  1st April 2024
+# Updated:  14th August 2026
 #
 #############################################################################
 
-gem build cmpfs.gemspec $*
-
+gem build *.gemspec $*
diff --git a/cmpfs.gemspec b/cmpfs.gemspec
index 49a8739..5f3b3bc 100644
--- a/cmpfs.gemspec
+++ b/cmpfs.gemspec
@@ -4,45 +4,48 @@
 # Purpose:  Gemspec for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  4th April 2024
+# Updated:  15th August 2026
 #
 # ######################################################################### #
 
 
 $:.unshift File.join(File.dirname(__FILE__), 'lib')
 
-require 'cmpfs'
+require 'cmpfs/version'
 
-require 'date'
 
 Gem::Specification.new do |spec|
 
   spec.name         = 'cmpfs-ruby'
   spec.version      = CmpFS::VERSION
-  spec.date         = Date.today.to_s
   spec.summary      = 'CmpFS.Ruby'
   spec.description  = <<END_DESC
 Compare File-System entities, for Ruby is a library that provides comparison
 functions for file-system entities - files and streams - including binary and
 filtering textual comparisons.
 END_DESC
-  spec.authors      = [ 'Matt Wilson' ]
-  spec.email        = 'matthew@synesis.com.au'
-  spec.homepage     = 'http://github.com/synesissoftware/cmpfs.Ruby'
+
+  spec.authors      = [
+    'Matt Wilson',
+  ]
+  spec.email        = [
+    'matthew@synesis.com.au',
+  ]
+  spec.homepage     = 'https://github.com/synesissoftware/cmpfs.Ruby'
   spec.license      = 'BSD-3-Clause'
   spec.files        = Dir[ 'Rakefile', '{bin,examples,lib,man,spec,test}/**/*', 'README*', 'LICENSE*' ] & `git ls-files -z`.split("\0")
 
-  if RUBY_VERSION >= '2'
-
-    spec.required_ruby_version = '>= 2'
-  else
+  spec.required_ruby_version = [ '>= 1.9.3' ]
 
-    spec.required_ruby_version = [ '~> 1.9', '>= 1.9.3' ]
-  end
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby/issues',
+    'changelog_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby/blob/master/CHANGES.md',
+    'homepage_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby',
+    'source_code_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby',
+  }
 
-  spec.add_development_dependency 'xqsr3', [ '~> 0.39', '>= 0.39.1' ]
+  spec.add_development_dependency "xqsr3", [ '>= 0.39.5', '< 1.0' ]
 end
 
 
 # ############################## end of file ############################# #
-
diff --git a/examples/compare_two_binary_files.md b/examples/compare_two_binary_files.md
new file mode 100644
index 0000000..4e19c8c
--- /dev/null
+++ b/examples/compare_two_binary_files.md
@@ -0,0 +1,57 @@
+# cmpfs.Ruby - Example - **compare_two_binary_files**
+
+## Summary
+
+Compares two files for binary equality via `compare_binary`.
+
+
+## Source
+
+```ruby
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../lib')
+
+
+require 'cmpfs'
+
+
+include CmpFS
+
+
+# command-line handling
+
+lhs_path, rhs_path =
+case ARGV.size
+when 0, 1
+
+  if '--help' == ARGV[0]
+
+    $stdout.puts "#$0: <lhs-path> <rhs-path>"
+
+    exit 0
+  end
+
+  abort "#$0: not enough arguments; use --help for usage"
+when 2
+
+  ARGV[0..2]
+else
+
+  abort "#$0: too many arguments; use --help for usage"
+end
+
+
+# main()
+
+
+$stdout.puts "binary comparison of '#{lhs_path}' with '#{rhs_path}':"
+
+$stdout.puts "files are #{compare_binary(lhs_path, rhs_path) ? '' : 'not '}equal"
+
+
+# ############################## end of file ############################# #
+```
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/examples/compare_two_text_files.md b/examples/compare_two_text_files.md
new file mode 100644
index 0000000..c72a1d5
--- /dev/null
+++ b/examples/compare_two_text_files.md
@@ -0,0 +1,57 @@
+# cmpfs.Ruby - Example - **compare_two_text_files**
+
+## Summary
+
+Compares two files for text equality via `compare_text`, skipping blank lines and trimming lines.
+
+
+## Source
+
+```ruby
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../lib')
+
+
+require 'cmpfs'
+
+
+include CmpFS
+
+
+# command-line handling
+
+lhs_path, rhs_path =
+case ARGV.size
+when 0, 1
+
+  if '--help' == ARGV[0]
+
+    $stdout.puts "#$0: <lhs-path> <rhs-path>"
+
+    exit 0
+  end
+
+  abort "#$0: not enough arguments; use --help for usage"
+when 2
+
+  ARGV[0..2]
+else
+
+  abort "#$0: too many arguments; use --help for usage"
+end
+
+
+# main()
+
+
+$stdout.puts "text comparison of '#{lhs_path}' with '#{rhs_path}':"
+
+$stdout.puts "files are #{compare_text(lhs_path, rhs_path, skip_blank_lines: true, trim_lines: true) ? '' : 'not '}equal"
+
+
+# ############################## end of file ############################# #
+```
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/generate_rdoc.cmd b/generate_rdoc.cmd
new file mode 100644
index 0000000..4f6f7ad
--- /dev/null
+++ b/generate_rdoc.cmd
@@ -0,0 +1,28 @@
+@ECHO OFF
+
+REM ########################################################################
+REM File:     generate_rdoc.cmd
+REM
+REM Purpose:  Generates documentation
+REM
+REM Created:  14th August 2026
+REM Updated:  14th August 2026
+REM
+REM ########################################################################
+
+IF EXIST doc RMDIR /S /Q doc
+rdoc ^
+  -x build_gem.cmd ^
+  -x build_gem.sh ^
+  -x generate_rdoc.cmd ^
+  -x generate_rdoc.sh ^
+  -x run_all_unit_tests.sh ^
+  -x *.gemspec ^
+  -x doc/ ^
+  -x gems/ ^
+  -x old-gems/ ^
+  -x test/performance/ ^
+  -x test/scratch/ ^
+  -x tc_.*\.rb ^
+  -x ts_all.rb ^
+  %*
diff --git a/generate_rdoc.sh b/generate_rdoc.sh
new file mode 100755
index 0000000..e7dc865
--- /dev/null
+++ b/generate_rdoc.sh
@@ -0,0 +1,31 @@
+#! /bin/bash
+
+#############################################################################
+# File:     generate_rdoc.sh
+#
+# Purpose:  Generates documentation
+#
+# Created:  11th June 2016
+# Updated:  14th August 2026
+#
+#############################################################################
+
+rm -rfd doc
+rdoc \
+  -x build_gem.cmd \
+  -x build_gem.sh \
+  -x generate_rdoc.cmd \
+  -x generate_rdoc.sh \
+  -x run_all_unit_tests.sh \
+  -x *.gemspec \
+  \
+  -x doc/ \
+  -x gems/ \
+  -x old-gems/ \
+  -x test/performance/ \
+  -x test/scratch/ \
+  \
+  -x tc_.*\.rb \
+  -x ts_all.rb \
+  \
+  $*
diff --git a/lib/cmpfs.rb b/lib/cmpfs.rb
index ceef4d5..83b0648 100644
--- a/lib/cmpfs.rb
+++ b/lib/cmpfs.rb
@@ -1,11 +1,11 @@
-
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     cmpfs.rb
 #
 # Purpose:  Primary require for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  2nd April 2024
+# Updated:  15th August 2026
 #
 # Home:     http://github.com/synesissoftware/cmpfs.Ruby
 #
diff --git a/lib/cmpfs/compare.rb b/lib/cmpfs/compare.rb
index cb0d2b2..b41b3f7 100644
--- a/lib/cmpfs/compare.rb
+++ b/lib/cmpfs/compare.rb
@@ -1,11 +1,11 @@
-
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     cmpfs/version.rb
 #
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  2nd April 2024
+# Updated:  15th August 2026
 #
 # Home:     http://github.com/synesissoftware/cmpfs.Ruby
 #
diff --git a/lib/cmpfs/compare/api_1_9.rb b/lib/cmpfs/compare/api_1_9.rb
index 1b668d6..c1fe500 100644
--- a/lib/cmpfs/compare/api_1_9.rb
+++ b/lib/cmpfs/compare/api_1_9.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 if RUBY_VERSION >= '2'
 
diff --git a/lib/cmpfs/compare/api_2.rb b/lib/cmpfs/compare/api_2.rb
index 8b70c1d..7e01d80 100644
--- a/lib/cmpfs/compare/api_2.rb
+++ b/lib/cmpfs/compare/api_2.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 unless RUBY_VERSION >= '2'
 
diff --git a/lib/cmpfs/compare/binary/internal_.rb b/lib/cmpfs/compare/binary/internal_.rb
index bd347d5..7f3865e 100644
--- a/lib/cmpfs/compare/binary/internal_.rb
+++ b/lib/cmpfs/compare/binary/internal_.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 require 'fileutils'
 require 'stringio'
diff --git a/lib/cmpfs/compare/text/internal_.rb b/lib/cmpfs/compare/text/internal_.rb
index 20b1098..3e5ba1c 100644
--- a/lib/cmpfs/compare/text/internal_.rb
+++ b/lib/cmpfs/compare/text/internal_.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 require 'fileutils'
 require 'stringio'
diff --git a/lib/cmpfs/version.rb b/lib/cmpfs/version.rb
index 7ba3bd9..ee6f778 100644
--- a/lib/cmpfs/version.rb
+++ b/lib/cmpfs/version.rb
@@ -1,17 +1,17 @@
-
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     cmpfs/version.rb
 #
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  4th April 2024
+# Updated:  15th August 2026
 #
 # Home:     http://github.com/synesissoftware/cmpfs.Ruby
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -51,7 +51,7 @@
 module CmpFS
 
   # Current version of the cmpfs.Ruby library
-  VERSION           = '0.2.3'
+  VERSION           = '0.2.4'
 
   private
   VERSION_PARTS_    = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
diff --git a/run_all_unit_tests.sh b/run_all_unit_tests.sh
index 76ca314..6aea55b 100755
--- a/run_all_unit_tests.sh
+++ b/run_all_unit_tests.sh
@@ -4,12 +4,13 @@
 # File:     run_all_unit_tests.sh
 #
 # Purpose:  Executes the unit-tests of a Ruby project regardless of
-#           calling directory
+#           calling directory, allowing use of debug mode, warnings, and
+#           executing each rbenv version
 #
 # Created:  9th June 2011
-# Updated:  2nd April 2024
+# Updated:  12th August 2026
 #
-# Copyright (c) Matthew Wilson, 2011-2024
+# Copyright (c) Matthew Wilson, 2011-2026
 # All rights reserved
 #
 # Redistribution and use in source and binary forms, with or without
@@ -47,128 +48,137 @@
 Source="${BASH_SOURCE[0]}"
 while [ -h "$Source" ]; do
 
-  Dir="$(cd -P "$(dirname "$Source")" && pwd)"
+  ScriptDir="$(cd -P "$(dirname "$Source")" && pwd)"
   Source="$(readlink "$Source")"
-  [[ $Source != /* ]] && Source="$Dir/$Source"
+  [[ $Source != /* ]] && Source="$ScriptDir/$Source"
 done
-Dir="$(cd -P "$( dirname "$Source" )" && pwd)"
+ScriptDir="$(cd -P "$( dirname "$Source" )" && pwd)"
+Basename="$(basename "$Source")"
 
 
 # colours
 
 if command -v tput > /dev/null; then
 
-  RbEnvClr_Blue=${FG_BLUE:-$(tput setaf 4)}
-  RbEnvClr_Red=${FG_BLUE:-$(tput setaf 1)}
-  RbEnvClr_Bold=${FD_BOLD:-$(tput bold)}
-  RbEnvClr_None=${FD_NONE:-$(tput sgr0)}
+  SisClr_Blue=${FG_BLUE:-$(tput setaf 4)}
+  SisClr_Red=${FG_RED:-$(tput setaf 1)}
+  SisClr_Bold=${FD_BOLD:-$(tput bold)}
+  SisClr_None=${FD_NONE:-$(tput sgr0)}
 else
 
-  RbEnvClr_Blue=
-  RbEnvClr_Red=
-  RbEnvClr_Bold=
-  RbEnvClr_None=
+  SisClr_Blue=
+  SisClr_Red=
+  SisClr_Bold=
+  SisClr_None=
 fi
 
 
-# special command-line handling ('--rbenv-versions')
-# rbenv handling
+# special command-line handling ('--pwd', '--rbenv-versions')
 
+ProjectDir="$ScriptDir"
+ForwardArgs=()
+FoundHelp=
 RunRbEnvAllVersions=
-Arguments=
 
 for arg in "$@"
 do
 
   case "$arg" in
 
-    --rbenv-versions)
+  --help)
 
-      RunRbEnvAllVersions=1
-      ;;
-    *)
+    FoundHelp=1
+    ForwardArgs+=("$arg")
+    ;;
+  --pwd)
 
-      Arguments="$Arguments $arg"
-      ;;
+    ProjectDir=$(pwd)
+    ForwardArgs+=("$arg")
+    ;;
+  --rbenv-versions)
+
+    RunRbEnvAllVersions=1
+    ;;
+  *)
+
+    ForwardArgs+=("$arg")
+    ;;
   esac
 done
 
-if [ ! -z "$RunRbEnvAllVersions" ]; then
+if [ ! -z "$FoundHelp" ]; then
 
-  if ! command -v rbenv > /dev/null; then
-
-    >&2 echo "$0: ${RbEnvClr_Red}${RbEnvClr_Bold}rbenv${RbEnvClr_None} not detected"
+  RunRbEnvAllVersions=
+fi
 
-    exit 1
-  fi
+if [ ! -z "$RunRbEnvAllVersions" ]; then
 
-  if [ ! -e "$Dir/.ruby-version" ];then
+  if ! command -v rbenv > /dev/null; then
 
-    >&2 echo "$0: ${RbEnvClr_Red}${RbEnvClr_Bold}.ruby-version${RbEnvClr_None} file not detected"
+  >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}rbenv${SisClr_None} not detected"
 
-    exit 1
+  exit 1
   fi
 
   exclusions=()
-  if [ -e "$Dir/.ruby-version-exclusions" ]; then
+  if [ -e "$ProjectDir/.ruby-version-exclusions" ]; then
 
-    exclusion_lines=`cat "$Dir/.ruby-version-exclusions"`
-    for line in $exclusion_lines; do
+  exclusion_lines=`cat "$ProjectDir/.ruby-version-exclusions"`
+  for line in $exclusion_lines; do
 
-      exclusions+=($line)
-    done
+    exclusions+=("$line")
+  done
   fi
 
-  echo "executing command line '${RbEnvClr_Blue}${RbEnvClr_Bold}$0 $Arguments${RbEnvClr_None}' with all Ruby versions ..."
+  echo "executing command line '${SisClr_Blue}${SisClr_Bold}$0 ${ForwardArgs[*]}${SisClr_None}' with all Ruby versions ..."
 
-  current=$(rbenv local)
+  current=
+  if [ -f "$ProjectDir/.ruby-version" ]; then
 
-  #echo "current version: $current"
+    current=$(tr -d '[:space:]' < "$ProjectDir/.ruby-version")
+  fi
 
   versions=()
   while IFS= read -r line; do
 
-    versions+=("$line")
+  versions+=("$line")
   done < <(rbenv versions --bare)
 
-  echo "versions: ${RbEnvClr_Blue}${RbEnvClr_Bold}${versions[*]}${RbEnvClr_None}; skipped versions: ${RbEnvClr_Blue}${RbEnvClr_Bold}${exclusions[*]}${RbEnvClr_None}; current version: ${RbEnvClr_Blue}${RbEnvClr_Bold}${current}${RbEnvClr_None}"
+  echo "versions: ${SisClr_Blue}${SisClr_Bold}${versions[*]}${SisClr_None}; skipped versions: ${SisClr_Blue}${SisClr_Bold}${exclusions[*]}${SisClr_None}; current version: ${SisClr_Blue}${SisClr_Bold}${current:-(none)}${SisClr_None}"
 
   result=0
 
-  for version in ${versions[@]}
+  for version in "${versions[@]}"
   do
 
-    echo
+  echo
 
-    skip=
+  skip=
 
-    for exclusion in "${exclusions[@]}"; do
+  for exclusion in "${exclusions[@]}"; do
 
-      if [[ "$exclusion" == "$version" ]]; then
+    if [[ "$exclusion" == "$version" ]]; then
 
-        skip=1
-      fi
-    done
+    skip=1
+    fi
+  done
 
-    if [ "$skip" != "" ]; then
+  if [ "$skip" != "" ]; then
 
-      echo "skipping Ruby version ${RbEnvClr_Blue}${RbEnvClr_Bold}$version${RbEnvClr_None}:"
-    else
+    echo "skipping Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
+  else
 
-      echo "processing Ruby version ${RbEnvClr_Blue}${RbEnvClr_Bold}$version${RbEnvClr_None}:"
+    echo "processing Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
 
-      echo -e "\texecuting command line '$0 $Arguments' with Ruby version $version ..."
-      rbenv local $version
+    echo -e "\texecuting command line 'RBENV_VERSION=$version $0 ${ForwardArgs[*]}' with Ruby version $version ..."
 
-      if ! $0 $Arguments; then
+    if ! RBENV_VERSION="$version" "$0" "${ForwardArgs[@]}"; then
 
-        result=1
-      fi
+    result=1
     fi
+  fi
   done
 
-  rbenv local $current
-
   exit $result
 fi
 
@@ -177,6 +187,8 @@ fi
 
 Separate=
 DebugFlag=
+PrependLib=
+WarningsFlag=-W0
 
 for v in "$@"
 do
@@ -187,52 +199,93 @@ do
 
       DebugFlag=--debug
       ;;
-
     --help)
 
-      echo "USAGE: $Source { | --help | [ --debug ] [ --separate ] }"
-      echo
-      echo "flags:"
-      echo
-      echo "  --help"
-      echo "    shows this help and terminates"
-      echo
-      echo "  --debug"
-      echo "    executes Ruby interpreter in debug mode"
-      echo
-      echo "  --rbenv-versions"
-      echo "    executes this script (with all other specified arguments) for each rbenv version (except those listed in the file .ruby-version-exclusions, if present)"
-      echo
-      echo "  --separate"
-      echo "    executes each unit-test in a separate program"
-      echo
-
-      exit
+      cat << EOF
+USAGE: $Basename { | --help | [ --debug ] [ --lib ] [ --pwd ] [ --rbenv-versions ] [ --separate ] [ --warnings ]}
+
+flags:
+
+  --help
+  shows this help and terminates
+
+  --debug
+  executes Ruby interpreter in debug mode
+
+  --lib
+  prepends the lib directory under the script's directory into RUBYLIB before executing
+
+  --pwd
+  executes from present working directory, rather than relative to the script directory
+
+  --rbenv-versions
+  executes this script (with all other specified arguments) for each rbenv version (except those listed in the file .ruby-version-exclusions, if present)
+
+  --separate
+  executes each unit-test in a separate program
+
+  --warnings
+  executes Ruby interpreter in warnings mode
+EOF
+
+      exit 0
+      ;;
+    --lib)
+
+      PrependLib=1
       ;;
+    --pwd)
 
+      # already-processed as special case above
+      ;;
+    --rbenv-versions)
+
+      # already-processed as special case above
+      ;;
     --separate)
 
       Separate=true
       ;;
+    --warnings|--warn)
 
+      WarningsFlag=-W2 #-W:performance
+      ;;
     *)
 
-      echo "unrecognised argument; use --help for usage"
+      >&2 echo "unrecognised argument '$v'; use --help for usage"
 
       exit 1
       ;;
   esac
 done
 
+
 # executing tests
 
+if [ ! -z "$PrependLib" ]; then
+
+  export RUBYLIB=$ProjectDir/lib:$RUBYLIB
+fi
+
+
 if [ -z "$Separate" ]; then
 
-  ruby $DebugFlag "$Dir/test/unit/ts_all.rb"
+  ruby $DebugFlag $WarningsFlag "$ProjectDir/test/unit/ts_all.rb"
 else
 
-  find "$Dir" -name 'tc_*.rb' -exec ruby $DebugFlag {} \;
+  result=0
+
+  while IFS= read -r -d '' testfile; do
+
+    if ! ruby $DebugFlag $WarningsFlag "$testfile"; then
+
+      result=1
+    fi
+  done < <(find "$ProjectDir" -name 'tc_*.rb' -print0)
+
+  exit $result
 fi
 
+
 # ############################## end of file ############################# #