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 new file mode 100644 index 0000000..2c70232 --- /dev/null +++ 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..0de7605 --- /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: 14th 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 recls-helpers-ruby.gemspec + gem install --local recls-helpers-ruby-*.gem + ruby -e "require 'recls/helpers/version'; abort('VERSION missing') unless defined?(Recls::Helpers::VERSION); puts Recls::Helpers::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 new file mode 100644 index 0000000..0d510c3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,50 @@ +# directories (by name) + +/.bzr/ +/.bundle/ +/.config/ +/.svn/ +/.yardoc/ + +/_yardoc/ + +/InstalledFiles/ +/build/ +/coverage/ +/doc/ +/lib/bundler/man/ +/old-gems/ +/pkg/ +/rdoc/ +/scratch/ +/spec/reports/ +/test/tmp/ +/test/version_tmp/ +/tmp/ +/vendor/bundle/ + +# directories (by pattern) + +# files (by name) + +.DS_Store +.repl_history +.ruby-version +.rvmrc + +/spec/examples.txt + +# files (by pattern) + +*~ +*.*~ +.dat* +*.b64 +*.bridgesupport +*.gem +*.rbc +*.scc +*.suo +*.swp +*.tmp +*.zip diff --git a/.ruby-version-exclusions b/.ruby-version-exclusions new file mode 100644 index 0000000..a8df221 --- /dev/null +++ b/.ruby-version-exclusions @@ -0,0 +1,2 @@ +1.8.7-p375 +1.9.3-p551 diff --git a/.sis/project_name.txt b/.sis/project_name.txt new file mode 100644 index 0000000..1c6c67f --- /dev/null +++ b/.sis/project_name.txt @@ -0,0 +1 @@ +recls-helpers.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 new file mode 100644 index 0000000..19efccd --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,43 @@ +{ + "[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..eabc7e0 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,21 @@ +# recls-helpers.Ruby - Authors + + +## Major Contributors + +| Name | GitHub | +| ----------- | --------------------------------- | +| Matt Wilson | [mwsis](https://github.com/mwsis) | + + +## Defect reports, fixes and suggestions (for which we are very grateful) + +| Name | GitHub | +| ----------- | --------------------------------- | +| \ | | + + +Contributions are welcomed. + + + diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..ddd2a1a --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,10 @@ +# recls-helpers.Ruby - Changes + + +## 0.0.0 - 16th August 2026 + +* added `# frozen_string_literal: true` to all **lib/** sources; +* initial skeleton; + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..53b3400 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# recls-helpers.Ruby - Contributing + + +## Table of Contents + +- [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/recls-helpers.Ruby/issues. + + +## Pull requests + +Pull requests are welcome on https://github.com/synesissoftware/recls-helpers.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). + + + diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 0000000..f100923 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,7 @@ +# recls-helpers.Ruby - Examples + +| Name | Source & Description | Summary | +| ---- | -------------------- | ------- | + + + diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..89a6079 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,28 @@ +# recls-helpers.Ruby - FAQ + +The FAQ list is under (constant) development. If you post a question on the +[Issues](https://github.com/synesissoftware/recls-helpers.Ruby/issues) forum +it will be used to create one. + + +## Table of Contents + +- [Q1: "How do I install this library?"](#q1-how-do-i-install-this-library) + + +# FAQs: + + +## Q1: "How do I install this library?" + +Install via **gem**: + +``` +gem install recls-helpers-ruby +``` + +See [README.md](./README.md) for usage. + + + + diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..29f6d2e --- /dev/null +++ b/Gemfile @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +source "https://rubygems.org" + +gemspec + +# rake 13 requires Ruby >= 2.3 +if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.3") + + gem "rake", '~> 13.0' +else + + gem "rake", '~> 12.3' +end + +gem "test-unit", '~> 3.0' diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..8baee4d --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,22 @@ +PATH + remote: . + specs: + recls-helpers-ruby (0.0.0) + recls-ruby (~> 2.13) + +GEM + remote: https://rubygems.org/ + specs: + recls-ruby (2.13.2) + xqsr3 (0.39.5) + +PLATFORMS + arm64-darwin-25 + ruby + +DEPENDENCIES + recls-helpers-ruby! + xqsr3 (~> 0.39) + +BUNDLED WITH + 2.6.9 diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..6da184c --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,41 @@ +# recls-helpers.Ruby - Installation and Use + + +## Table of Contents + +- [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 recls-helpers-ruby +``` + +or add to a **Gemfile**: + +```Ruby +gem 'recls-helpers-ruby' +``` + +then `bundle install`. + + +## From a source checkout + +``` +bundle install +bundle exec rake test +``` + + +## Using the library + +```Ruby +require 'recls/helpers' +``` + + + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3704773 --- /dev/null +++ b/LICENSE @@ -0,0 +1,31 @@ +recls-helpers.Ruby - BSD 3-Clause License + +Copyright (c) 2026, Matthew Wilson and Synesis Information Systems +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + +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. + +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 +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..ff6ca18 --- /dev/null +++ b/NEWS.md @@ -0,0 +1,8 @@ +# recls-helpers.Ruby - News + +| Date | News Item | +| ---------------- | ------------------------------------------------------------------------------------------------- | +| 16th August 2026 | [recls-helpers.Ruby 0.0.0 released](https://github.com/synesissoftware/recls-helpers.Ruby/releases/tag/0.0.0) | + + + diff --git a/README.md b/README.md index f83a398..f428b82 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,105 @@ -# recls-helpers.Ruby -Helper types and functions for working with recls.Ruby +# recls-helpers.Ruby + +Helper types and functions for working with **recls.Ruby** + +![Language](https://img.shields.io/badge/Ruby-CC342D?style=flat&logo=ruby&logoColor=white) +[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) +[![Gem Version](https://badge.fury.io/rb/recls-helpers-ruby.svg)](https://badge.fury.io/rb/recls-helpers-ruby) +[![GitHub release](https://img.shields.io/github/v/release/synesissoftware/recls-helpers.Ruby.svg)](https://github.com/synesissoftware/recls-helpers.Ruby/releases/latest) +[![Last Commit](https://img.shields.io/github/last-commit/synesissoftware/recls-helpers.Ruby)](https://github.com/synesissoftware/recls-helpers.Ruby/commits/master) +[![Ruby](https://github.com/synesissoftware/recls-helpers.Ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/synesissoftware/recls-helpers.Ruby/actions/workflows/ruby.yml) + + +## Table of Contents + +- [Introduction](#introduction) +- [Installation](#installation) +- [Components](#components) +- [Examples](#examples) +- [Project Information](#project-information) + - [Where to get help](#where-to-get-help) + - [Contribution guidelines](#contribution-guidelines) + - [Dependencies](#dependencies) + - [Related projects](#related-projects) + - [License](#license) + + +## Introduction + +**recls-helpers.Ruby** provides helper types and functions layered on [**recls.Ruby**](https://github.com/synesissoftware/recls.Ruby) — common patterns for filtering search results, walking directory trees, presenting paths, and related filesystem utilities used across Synesis tooling. + + +## Installation + +Install via **gem** as in: + +``` +gem install recls-helpers-ruby +``` + +or add it to your `Gemfile`. + +Use via **require**, as in: + +```Ruby +require 'recls/helpers' +``` + + +## Components + +**recls-helpers.Ruby** currently ships the **`Recls::Helpers`** namespace and version metadata (`require 'recls/helpers'`), layered on [**recls.Ruby**](https://github.com/synesissoftware/recls.Ruby). Concrete helper APIs are still landing; the intended first set (see **TODO.md**) includes: + +* ignore / exclude filtering (`strip_excludes` / `reject_ignored`, `String` + `Regexp`); +* `each_file_r` (and related flag builders) for recursive file walks with default directory and ignores; +* path-or-directory search dispatch; +* `empty_directory?`, `directory_byte_size`, `display_path`, and group-by helpers; +* optional stock Synesis ignore / pattern presets; + + +## Examples + +Examples are provided in the `examples` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md). + + +## Project Information + + +### Where to get help + +[GitHub Page](https://github.com/synesissoftware/recls-helpers.Ruby "GitHub Page") + + +### Contribution guidelines + +Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/recls-helpers.Ruby. + + +### Dependencies + +This library has **efferent** (fan-out) dependencies on: + +* [**recls.Ruby**](https://github.com/synesissoftware/recls.Ruby) (`recls-ruby`); + +and, for development/tests: + +* [**xqsr3**](https://github.com/synesissoftware/xqsr3/). + +It has no known **afferent** (fan-in) dependencies yet. + + +### Related projects + +* [**recls.Ruby**](https://github.com/synesissoftware/recls.Ruby); +* [**recls**](https://github.com/synesissoftware/recls) (**C** / **C++**); +* [**recls.Go**](https://github.com/synesissoftware/recls.Go); +* [**recls.NET**](https://github.com/synesissoftware/recls.NET); +* [**recls.Rust**](https://github.com/synesissoftware/recls.Rust); + + +### License + +**recls-helpers.Ruby** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details. + + + diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..ad63284 --- /dev/null +++ b/Rakefile @@ -0,0 +1,21 @@ +# frozen_string_literal: true + +# Rakefile for recls-helpers.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..cfd9933 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,22 @@ +# recls-helpers.Ruby - Security + + +## Table of Contents + +- [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/recls-helpers.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.0.x | ✅ | + + + diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..60d9010 --- /dev/null +++ b/TODO.md @@ -0,0 +1,25 @@ +# recls-helpers.Ruby - TODO + + +## Table of Contents + +- [Functional improvements](#functional-improvements) +- [Packaging improvements](#packaging-improvements) + + +## Functional improvements + +* [ ] Ignore / exclude filtering (`strip_excludes` / `reject_ignored`, String + Regexp); +* [ ] `each_file_r` (+ flag builder) for recursive file walks with default `.` and ignores; +* [ ] Path-or-directory search dispatcher; +* [ ] `empty_directory?`, `directory_byte_size`, `display_path`, group-by helpers; +* [ ] Stock Synesis ignore / pattern presets (optional); + + +## Packaging improvements + +* [ ] Examples for first shipped helpers; +* [ ] Publish gem and GitHub release for **0.0.0**; + + + 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 new file mode 100755 index 0000000..864823e --- /dev/null +++ b/build_gem.sh @@ -0,0 +1,13 @@ +#! /bin/bash + +############################################################################# +# File: build_gem.sh +# +# Purpose: Builds the gem +# +# Created: 9th June 2016 +# Updated: 14th August 2026 +# +############################################################################# + +gem build *.gemspec $* 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/recls/helpers.rb b/lib/recls/helpers.rb new file mode 100644 index 0000000..b4b9abf --- /dev/null +++ b/lib/recls/helpers.rb @@ -0,0 +1,59 @@ +# frozen_string_literal: true +# ######################################################################## # +# File: recls/helpers.rb +# +# Purpose: Top-level include for recls-helpers.Ruby library +# +# Created: 14th August 2026 +# Updated: 15th August 2026 +# +# Home: http://github.com/synesissoftware/recls-helpers.Ruby +# +# Author: Matthew Wilson +# +# Copyright (c) 2026, Matthew Wilson and Synesis Information Systems +# 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. +# +# * 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 the copyright holders 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 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +# +# ######################################################################## # + + +require 'recls' + +require 'recls/helpers/version' + + +module Recls +module Helpers + +end # module Helpers +end # module Recls + + +# ############################## end of file ############################# # diff --git a/lib/recls/helpers/version.rb b/lib/recls/helpers/version.rb new file mode 100644 index 0000000..5d71235 --- /dev/null +++ b/lib/recls/helpers/version.rb @@ -0,0 +1,71 @@ +# frozen_string_literal: true +# ######################################################################## # +# File: recls/helpers/version.rb +# +# Purpose: Version for recls-helpers.Ruby library +# +# Created: 14th August 2026 +# Updated: 15th August 2026 +# +# Home: http://github.com/synesissoftware/recls-helpers.Ruby +# +# Author: Matthew Wilson +# +# Copyright (c) 2026, Matthew Wilson and Synesis Information Systems +# 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. +# +# * 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 the copyright holders 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 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +# +# ######################################################################## # + + +=begin +=end + +module Recls +module Helpers + + # Current version of the recls-helpers.Ruby library + VERSION = '0.0.0' + + private + # @!visibility private + VERSION_PARTS_ = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc: + public + # Major version of the recls-helpers.Ruby library + VERSION_MAJOR = VERSION_PARTS_[0] # :nodoc: + # Minor version of the recls-helpers.Ruby library + VERSION_MINOR = VERSION_PARTS_[1] # :nodoc: + # Revision version of the recls-helpers.Ruby library + VERSION_REVISION = VERSION_PARTS_[2] # :nodoc: + +end # module Helpers +end # module Recls + + +# ############################## end of file ############################# # diff --git a/recls-helpers-ruby.gemspec b/recls-helpers-ruby.gemspec new file mode 100644 index 0000000..26728e3 --- /dev/null +++ b/recls-helpers-ruby.gemspec @@ -0,0 +1,53 @@ +# ######################################################################### # +# File: recls-helpers-ruby.gemspec +# +# Purpose: Gemspec for recls-helpers.Ruby library +# +# Created: 14th August 2026 +# Updated: 15th August 2026 +# +# ######################################################################### # + + +$:.unshift File.join(File.dirname(__FILE__), 'lib') + +require 'recls/helpers/version' + + +Gem::Specification.new do |spec| + + spec.name = 'recls-helpers-ruby' + spec.version = Recls::Helpers::VERSION + spec.summary = 'recls-helpers.Ruby' + spec.description = <= 2.0', '< 4' ] + + spec.metadata = { + 'bug_tracker_uri' => 'https://github.com/synesissoftware/recls-helpers.Ruby/issues', + 'changelog_uri' => 'https://github.com/synesissoftware/recls-helpers.Ruby/blob/master/CHANGES.md', + 'homepage_uri' => 'https://github.com/synesissoftware/recls-helpers.Ruby', + 'source_code_uri' => 'https://github.com/synesissoftware/recls-helpers.Ruby', + } + + spec.add_runtime_dependency "recls-ruby", [ '~> 2.13' ] + + spec.add_development_dependency "xqsr3", [ '>= 0.39.5', '< 1.0' ] + + spec.files = Dir[ 'Rakefile', '{bin,examples,lib,man,spec,test}/**/*', 'README*', 'LICENSE*' ] & `git ls-files -z`.split("\0") +end + + +# ############################## end of file ############################# # diff --git a/run_all_unit_tests.sh b/run_all_unit_tests.sh new file mode 100755 index 0000000..6aea55b --- /dev/null +++ b/run_all_unit_tests.sh @@ -0,0 +1,291 @@ +#! /bin/bash + +# ######################################################################## # +# File: run_all_unit_tests.sh +# +# Purpose: Executes the unit-tests of a Ruby project regardless of +# calling directory, allowing use of debug mode, warnings, and +# executing each rbenv version +# +# Created: 9th June 2011 +# Updated: 12th August 2026 +# +# Copyright (c) Matthew Wilson, 2011-2026 +# 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. +# +# * 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 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 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +# +# ######################################################################## # + + +# constants + +Source="${BASH_SOURCE[0]}" +while [ -h "$Source" ]; do + + ScriptDir="$(cd -P "$(dirname "$Source")" && pwd)" + Source="$(readlink "$Source")" + [[ $Source != /* ]] && Source="$ScriptDir/$Source" +done +ScriptDir="$(cd -P "$( dirname "$Source" )" && pwd)" +Basename="$(basename "$Source")" + + +# colours + +if command -v tput > /dev/null; then + + 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 + + SisClr_Blue= + SisClr_Red= + SisClr_Bold= + SisClr_None= +fi + + +# special command-line handling ('--pwd', '--rbenv-versions') + +ProjectDir="$ScriptDir" +ForwardArgs=() +FoundHelp= +RunRbEnvAllVersions= + +for arg in "$@" +do + + case "$arg" in + + --help) + + FoundHelp=1 + ForwardArgs+=("$arg") + ;; + --pwd) + + ProjectDir=$(pwd) + ForwardArgs+=("$arg") + ;; + --rbenv-versions) + + RunRbEnvAllVersions=1 + ;; + *) + + ForwardArgs+=("$arg") + ;; + esac +done + +if [ ! -z "$FoundHelp" ]; then + + RunRbEnvAllVersions= +fi + +if [ ! -z "$RunRbEnvAllVersions" ]; then + + if ! command -v rbenv > /dev/null; then + + >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}rbenv${SisClr_None} not detected" + + exit 1 + fi + + exclusions=() + if [ -e "$ProjectDir/.ruby-version-exclusions" ]; then + + exclusion_lines=`cat "$ProjectDir/.ruby-version-exclusions"` + for line in $exclusion_lines; do + + exclusions+=("$line") + done + fi + + echo "executing command line '${SisClr_Blue}${SisClr_Bold}$0 ${ForwardArgs[*]}${SisClr_None}' with all Ruby versions ..." + + current= + if [ -f "$ProjectDir/.ruby-version" ]; then + + current=$(tr -d '[:space:]' < "$ProjectDir/.ruby-version") + fi + + versions=() + while IFS= read -r line; do + + versions+=("$line") + done < <(rbenv versions --bare) + + 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[@]}" + do + + echo + + skip= + + for exclusion in "${exclusions[@]}"; do + + if [[ "$exclusion" == "$version" ]]; then + + skip=1 + fi + done + + if [ "$skip" != "" ]; then + + echo "skipping Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:" + else + + echo "processing Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:" + + echo -e "\texecuting command line 'RBENV_VERSION=$version $0 ${ForwardArgs[*]}' with Ruby version $version ..." + + if ! RBENV_VERSION="$version" "$0" "${ForwardArgs[@]}"; then + + result=1 + fi + fi + done + + exit $result +fi + + +# regular command-line handling + +Separate= +DebugFlag= +PrependLib= +WarningsFlag=-W0 + +for v in "$@" +do + + case "$v" in + + --debug) + + DebugFlag=--debug + ;; + --help) + + 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 + ;; + *) + + >&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 $WarningsFlag "$ProjectDir/test/unit/ts_all.rb" +else + + 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 ############################# # + diff --git a/test/unit/tc_version.rb b/test/unit/tc_version.rb new file mode 100644 index 0000000..4e74890 --- /dev/null +++ b/test/unit/tc_version.rb @@ -0,0 +1,37 @@ +#! /usr/bin/env ruby + +$:.unshift File.join(File.dirname(__FILE__), '../../lib') + + +require 'recls/helpers/version' + +require 'test/unit' + + +class Test_version < Test::Unit::TestCase + + def test_has_VERSION + + assert defined? Recls::Helpers::VERSION + end + + def test_has_VERSION_MAJOR + + assert defined? Recls::Helpers::VERSION_MAJOR + end + + def test_has_VERSION_MINOR + + assert defined? Recls::Helpers::VERSION_MINOR + end + + def test_has_VERSION_REVISION + + assert defined? Recls::Helpers::VERSION_REVISION + end + + def test_VERSION_has_consistent_format + + assert_equal Recls::Helpers::VERSION.split('.')[0..2].join('.'), "#{Recls::Helpers::VERSION_MAJOR}.#{Recls::Helpers::VERSION_MINOR}.#{Recls::Helpers::VERSION_REVISION}" + end +end diff --git a/test/unit/ts_all.rb b/test/unit/ts_all.rb new file mode 100644 index 0000000..70e0ef8 --- /dev/null +++ b/test/unit/ts_all.rb @@ -0,0 +1,11 @@ +#! /usr/bin/env ruby +# +# executes all other tests + +this_dir = File.expand_path(File.dirname(__FILE__)) + +# all tc_*rb in current directory +Dir[File.join(this_dir, 'tc_*rb')].each { |file| require file } + +# all ts_*rb in immediate sub-directories +Dir[File.join(this_dir, '*', 'ts_*rb')].each { |file| require file }