--- /dev/null
+/.idea/
+/.settings/
+/target/
+/*.iml
+/*.log
+/test/
+
+/doc/apidocs/
+/doc/graphs/
+
+/.classpath
+/.factorypath
+/.project
+*.html
--- /dev/null
+# Svjatoslav Commons
+
+Shared Java utility library used as a dependency across other
+projects. Contains commonly useful functionality for string
+manipulation, file I/O, binary data handling, and simple GUI dialogs.
+
+## Build Commands
+
+```bash
+mvn compile # Compile source code
+mvn test # Run unit tests
+mvn package # Build JAR
+mvn clean install # Clean build and install to local Maven repo
+```
+
+## Project Info
+
+- **License:** Creative Commons Zero (CC0)
+- **Java Version:** 8
+- **Package:** `eu.svjatoslav.commons`
+
+## Dependencies
+
+| Dependency | Scope | Purpose |
+|-----------------|----------|----------------------------|
+| junit 4.8.1 | test | Unit testing |
+| servlet-api 2.5 | provided | Servlet support (optional) |
+
+## Package Structure
+
+### `eu.svjatoslav.commons.data`
+- **BitInputStream** - Read individual bits from an InputStream
+- **BitOutputStream** - Write individual bits to an OutputStream
+- **HexConverter** - Convert byte arrays to hexadecimal strings
+
+### `eu.svjatoslav.commons.file`
+- **IOHelper** - File I/O utilities (recursive delete, read/write files, smart overwrite)
+- **FilePathParser** - Extract file extensions, names without extensions, format file sizes
+- **CommonPathResolver** - Resolve common system paths (home directory)
+
+### `eu.svjatoslav.commons.gui.dialog`
+- **ExceptionDialog** - Swing dialog for displaying exceptions with stack traces
+
+### `eu.svjatoslav.commons.string`
+- **String2** - Mutable string builder optimized for prefix/suffix operations (trim, prepend, append, repeat, enforce length)
+- **GlobMatcher** - Match strings against wildcard patterns (`*` and `?`)
+
+### `eu.svjatoslav.commons.string.tokenizer`
+Regex-based tokenizer for parsing structured text.
+
+- **Tokenizer** - Main tokenizer class; add terminators with regex patterns
+- **Terminator** - Defines how tokens are identified (PRESERVE or DROP)
+- **TokenizerMatch** - Result object containing matched token and metadata
+- **InvalidSyntaxException** - Thrown on parsing errors
+
+Example usage:
+```java
+Tokenizer tokenizer = new Tokenizer("\"hello\" world");
+tokenizer.addTerminator(DROP, "\\s"); // Drop whitespace
+tokenizer.addTerminator(PRESERVE, "\".*\""); // Preserve quoted strings
+TokenizerMatch match = tokenizer.getNextToken(); // Returns "\"hello\""
+```
+
+## Code Style
+
+- Standard file header with license comment on all source files
+- Fluent API pattern (method chaining returns `this`)
+- Javadoc on public classes, methods, and fields
+- Static utility methods in helper classes (e.g., `IOHelper`, `GlobMatcher`, `HexConverter`)
+- Mutable builder pattern (e.g., `String2`)
+
+## Testing
+
+Tests are located in `src/test/java/` mirroring the main package structure.
+Uses JUnit 4 with standard `@Test` annotations.
+
+```bash
+mvn test # Run all tests
+mvn test -Dtest=String2Test # Run specific test class
+```
--- /dev/null
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+ CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+ LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+ ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+ INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+ REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+ PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+ THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+ HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+ i. the right to reproduce, adapt, distribute, perform, display,
+ communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+ likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+ subject to the limitations in paragraph 4(a), below;
+ v. rights protecting the extraction, dissemination, use and reuse of data
+ in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+ European Parliament and of the Council of 11 March 1996 on the legal
+ protection of databases, and under any national implementation
+ thereof, including any amended or successor version of such
+ directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+ world based on applicable law or treaty, and any national
+ implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+ surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+ warranties of any kind concerning the Work, express, implied,
+ statutory or otherwise, including without limitation warranties of
+ title, merchantability, fitness for a particular purpose, non
+ infringement, or the absence of latent or other defects, accuracy, or
+ the present or absence of errors, whether or not discoverable, all to
+ the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+ that may apply to the Work or any use thereof, including without
+ limitation any person's Copyright and Related Rights in the Work.
+ Further, Affirmer disclaims responsibility for obtaining any necessary
+ consents, permissions or other rights required for any use of the
+ Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+ party to this document and has no duty or obligation with respect to
+ this CC0 or use of the Work.
--- /dev/null
++ publish auto generated JavaDoc on web site
+ + link to JavaDoc from documentation
--- /dev/null
+#!/bin/bash
+
+# This script launches IntelliJ IDEA with the current project
+# directory. The script is designed to be run by double-clicking it in
+# the GNOME Nautilus file manager.
+
+# First, we change the current working directory to the directory of
+# the script.
+
+# "${0%/*}" gives us the path of the script itself, without the
+# script's filename.
+
+# This command basically tells the system "change the current
+# directory to the directory containing this script".
+
+cd "${0%/*}"
+
+# Then, we move up one directory level.
+# The ".." tells the system to go to the parent directory of the current directory.
+# This is done because we assume that the project directory is one level up from the script.
+cd ..
+
+# Now, we use the 'setsid' command to start a new session and run
+# IntelliJ IDEA in the background. 'setsid' is a UNIX command that
+# runs a program in a new session.
+
+# The command 'idea .' opens IntelliJ IDEA with the current directory
+# as the project directory. The '&' at the end is a UNIX command that
+# runs the process in the background. The '> /dev/null' part tells
+# the system to redirect all output (both stdout and stderr, denoted
+# by '&') that would normally go to the terminal to go to /dev/null
+# instead, which is a special file that discards all data written to
+# it.
+
+setsid idea . &>/dev/null &
+
+# The 'disown' command is a shell built-in that removes a shell job
+# from the shell's active list. Therefore, the shell will not send a
+# SIGHUP to this particular job when the shell session is terminated.
+
+# '-h' option specifies that if the shell receives a SIGHUP, it also
+# doesn't send a SIGHUP to the job.
+
+# '$!' is a shell special parameter that expands to the process ID of
+# the most recent background job.
+disown -h $!
+
+
+sleep 2
+
+# Finally, we use the 'exit' command to terminate the shell script.
+# This command tells the system to close the terminal window after
+# IntelliJ IDEA has been opened.
+exit
--- /dev/null
+#!/bin/bash
+cd "${0%/*}"; if [ "$1" != "T" ]; then gnome-terminal -e "'$0' T"; exit; fi;
+
+cd ..
+
+# Function to export org to html using emacs in batch mode
+export_org_to_html() {
+ local org_file=$1
+ local dir=$(dirname "$org_file")
+ local base=$(basename "$org_file" .org)
+ (
+ cd "$dir" || return 1
+ local html_file="${base}.html"
+ if [ -f "$html_file" ]; then
+ rm -f "$html_file"
+ fi
+ echo "Exporting: $org_file → $dir/$html_file"
+ emacs --batch -l ~/.emacs --visit="${base}.org" --funcall=org-html-export-to-html --kill
+ if [ $? -eq 0 ]; then
+ echo "✓ Successfully exported $org_file"
+ else
+ echo "✗ Failed to export $org_file"
+ return 1
+ fi
+ )
+}
+
+export_org_files_to_html() {
+ echo "🔍 Searching for .org files in doc/ ..."
+ echo "======================================="
+
+ mapfile -t ORG_FILES < <(find doc -type f -name "*.org" | sort)
+
+ if [ ${#ORG_FILES[@]} -eq 0 ]; then
+ echo "❌ No .org files found!"
+ return 1
+ fi
+
+ echo "Found ${#ORG_FILES[@]} .org file(s):"
+ printf '%s\n' "${ORG_FILES[@]}"
+ echo "======================================="
+
+ SUCCESS_COUNT=0
+ FAILED_COUNT=0
+
+ for org_file in "${ORG_FILES[@]}"; do
+ export_org_to_html "$org_file"
+ if [ $? -eq 0 ]; then
+ ((SUCCESS_COUNT++))
+ else
+ ((FAILED_COUNT++))
+ fi
+ done
+
+ echo "======================================="
+ echo "📊 SUMMARY:"
+ echo " ✓ Successful: $SUCCESS_COUNT"
+ echo " ✗ Failed: $FAILED_COUNT"
+ echo " Total: $((SUCCESS_COUNT + FAILED_COUNT))"
+ echo ""
+}
+
+# Build project jar file and JavaDocs
+mvn clean package
+
+# Put generated JavaDoc HTML files to documentation directory
+rm -rf doc/apidocs/
+cp -r target/apidocs/ doc/
+
+# Publish Emacs org-mode files into HTML format
+export_org_files_to_html
+
+## Upload assembled documentation to server
+echo "📤 Uploading to server..."
+rsync -avz --delete -e 'ssh -p 10006' doc/ \
+ n0@www3.svjatoslav.eu:/mnt/big/projects/svjatoslav_commons/
+
+if [ $? -eq 0 ]; then
+ echo "✓ Upload completed successfully!"
+else
+ echo "✗ Upload failed!"
+fi
+
+echo ""
+echo "Press ENTER to close this window."
+read
--- /dev/null
+#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme
+#+TITLE: Svjatoslav Commons - Java library of commonly used functions
+#+LANGUAGE: en
+#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry}
+#+LATEX_HEADER: \usepackage{parskip}
+#+LATEX_HEADER: \usepackage[none]{hyphenat}
+
+#+OPTIONS: H:20 num:20
+#+OPTIONS: author:nil
+
+#+begin_export html
+<style>
+ .flex-center {
+ display: flex; /* activate flexbox */
+ justify-content: center; /* horizontally center anything inside */
+ }
+
+ .flex-center video {
+ width: min(90%, 1000px); /* whichever is smaller wins */
+ height: auto; /* preserve aspect ratio */
+ }
+
+ .responsive-img {
+ width: min(100%, 1000px);
+ height: auto;
+ }
+
+
+ .flex-center {
+ display: flex;
+ justify-content: center;
+ }
+ .flex-center video {
+ width: min(90%, 1000px);
+ height: auto;
+ }
+ .responsive-img {
+ width: min(100%, 1000px);
+ height: auto;
+ }
+
+
+ /* === SVG diagram theme === */
+ svg > rect:first-child {
+ fill: #061018;
+ }
+
+ /* Lighten axis/helper labels that were dark-on-light */
+ svg text[fill="#666"],
+ svg text[fill="#999"] {
+ fill: #aaa !important;
+ }
+
+ /* Lighten dashed axis lines */
+ svg line[stroke="#ccc"] {
+ stroke: #445566 !important;
+ }
+
+ svg {
+ background-color: #061018;
+ border-radius: 8px;
+ display: block;
+ margin: 0 auto;
+ }
+</style>
+#+end_export
+
+
+* Introduction
+
+Svjatoslav Commons is a shared Java utility library that consolidates
+commonly needed functionality: reading and writing files, manipulating
+strings, handling binary data, and displaying errors to users.
+
+The library requires Java 8 and has minimal dependencies: only JUnit
+for testing and servlet-api (optional, provided scope). See [[#usage][How to
+take library into use]] for Maven dependency configuration. The complete
+API documentation is available in the [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][JavaDoc]].
+
+* Library contents
+:PROPERTIES:
+:CUSTOM_ID: library-contents
+:END:
+- See [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][JavaDoc]].
+
+** Binary data utilities ([[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/data/package-summary.html][eu.svjatoslav.commons.data]])
+
+The data package provides classes for working with binary data at the
+bit level and converting it to human-readable formats.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/data/BitInputStream.html][BitInputStream]] and [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/data/BitOutputStream.html][BitOutputStream]] allow reading and writing
+individual bits from streams, not just whole bytes. This is essential
+for applications that work with bit-packed data formats where data is
+not byte-aligned, such as custom compression algorithms, network
+protocols, or binary file formats. Bits are processed from most
+significant to least significant within each byte, and you can read or
+write any number of bits (not just multiples of 8).
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/data/HexConverter.html][HexConverter]] converts byte arrays to uppercase hexadecimal strings.
+Each byte becomes exactly two characters (0-9, A-F), making binary data
+visible in logs, debug output, or text-based protocols. Null inputs
+return null; empty arrays return empty strings.
+
+** File system utilities ([[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/file/package-summary.html][eu.svjatoslav.commons.file]])
+
+The file package provides utilities for common file operations: reading
+and writing files, parsing paths, and resolving system directories.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/file/IOHelper.html][IOHelper]] is the primary file I/O class. It reads and writes files as
+byte arrays or UTF-8 strings, deletes files and directories
+recursively (without following symbolic links, which prevents accidental
+deletion of data outside the intended scope), and overwrites files only
+when content actually differs, avoiding unnecessary disk writes and
+preserving timestamps.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/file/FilePathParser.html][FilePathParser]] extracts metadata from file paths: the file extension
+(lowercase normalized), the file name without extension, and formats
+file sizes using binary units (b, KiB, MiB, GiB, TiB, PiB) with
+human-readable descriptions like "15 MiB".
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/file/CommonPathResolver.html][CommonPathResolver]] resolves common system paths. Currently it provides
+the user's home directory, useful for storing application configuration
+files or user-specific data.
+
+** Graphical dialogs ([[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/gui/dialog/package-summary.html][eu.svjatoslav.commons.gui.dialog]])
+
+The dialog package provides Swing-based components for displaying
+information to users in graphical applications.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/gui/dialog/ExceptionDialog.html][ExceptionDialog]] displays exceptions with their full stack traces in a
+windowed dialog. It shows the exception type, error message, cause (if
+present), and complete stack trace, making it easy to debug errors in
+GUI applications without requiring console output or log files. Note:
+this requires a graphical environment and is not suitable for headless
+or server-side applications.
+
+** String utilities ([[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/package-summary.html][eu.svjatoslav.commons.string]])
+
+The string package provides a mutable string builder optimized for
+prefix and suffix operations, plus simple glob-style pattern matching.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/String2.html][String2]] is a mutable string that stores characters in a list, enabling
+efficient operations at both ends. It provides ~prepend()~ and ~append()~
+for adding text, ~trimPrefix()~ and ~trimSuffix()~ for removing characters,
+~trimPrefixIfExists()~ and ~trimSuffixIfExists()~ for conditional removal,
+~hasPrefix()~ and ~hasSuffix()~ for checking, ~repeat()~ for duplication,
+and ~enforceLength()~ for padding or truncating to exact lengths. All
+methods return the same instance for fluent chaining.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/GlobMatcher.html][GlobMatcher]] matches strings against glob-style wildcard patterns using
+~*~ (matches any sequence of characters, including empty) and ~?~ (matches
+exactly one character). This is simpler than regular expressions and
+useful for file name filtering, simple validation, or user-friendly
+pattern input.
+
+** Tokenizer ([[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/tokenizer/package-summary.html][eu.svjatoslav.commons.string.tokenizer]])
+
+The tokenizer package provides a regex-based tokenizer for parsing
+structured text into tokens with lookahead and backtracking support.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/tokenizer/Tokenizer.html][Tokenizer]] is the main class. You add [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/tokenizer/Terminator.html][Terminator]] objects that define
+token boundaries using regex patterns. Each terminator has a strategy:
+~PRESERVE~ returns matched tokens for processing, ~DROP~ silently discards
+them (useful for whitespace or comments). You can peek at the next token
+without consuming it, unread tokens to backtrack, expect specific tokens
+and throw exceptions on mismatch, and categorize tokens using group
+names.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/tokenizer/TokenizerMatch.html][TokenizerMatch]] is the result object containing the matched text, the
+terminator that identified it, the regex matcher (for extracting capture
+groups), and methods to check group membership.
+
+[[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/eu/svjatoslav/commons/string/tokenizer/InvalidSyntaxException.html][InvalidSyntaxException]] is thrown when expectations fail during parsing,
+such as when expecting a specific token but finding something else.
+
+* How to take library into use
+:PROPERTIES:
+:CUSTOM_ID: usage
+:END:
+
+Add the *svjatoslavcommons* dependency to your Maven project:
+
+#+BEGIN_SRC xml
+ <dependencies>
+ <dependency>
+ <groupId>eu.svjatoslav</groupId>
+ <artifactId>svjatoslavcommons</artifactId>
+ <version>1.9</version>
+ </dependency>
+ </dependencies>
+#+END_SRC
+
+Also add the repository (the library is not on Maven Central):
+
+#+BEGIN_SRC xml
+ <repositories>
+ <repository>
+ <id>svjatoslav.eu</id>
+ <name>Svjatoslav repository</name>
+ <url>https://www3.svjatoslav.eu/maven/</url>
+ </repository>
+ </repositories>
+#+END_SRC
+
+* Source code
+:PROPERTIES:
+:CUSTOM_ID: source-code
+:ID: 978b7ea2-e246-45d0-be76-4d561308e9f3
+:END:
+
+*This program is free software: released under Creative Commons Zero
+(CC0) license*
+
+*Program author:*
+- Svjatoslav Agejenko
+- Homepage: https://svjatoslav.eu
+- Email: mailto://svjatoslav@svjatoslav.eu
+- See also: [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
+
+*Getting the source code:*
+- [[https://www2.svjatoslav.eu/gitweb/?p=svjatoslav_commons.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
+- [[https://www2.svjatoslav.eu/gitweb/?p=svjatoslav_commons.git;a=summary][Browse Git repository online]]
+- Clone Git repository using command:
+ : git clone https://www2.svjatoslav.eu/git/svjatoslav_commons.git
--- /dev/null
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>eu.svjatoslav</groupId>
+ <artifactId>svjatoslavcommons</artifactId>
+ <version>1.10-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <name>Svjatoslav Commons</name>
+ <description>Collection many small but commonly useful functionalities</description>
+ <url>https://www3.svjatoslav.eu/projects/svjatoslav_commons/</url>
+
+ <organization>
+ <name>svjatoslav.eu</name>
+ <url>http://svjatoslav.eu</url>
+ </organization>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+ </properties>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.8.1</version>
+ <configuration>
+ <source>8</source>
+ <target>8</target>
+ <encoding>UTF-8</encoding>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-source-plugin</artifactId>
+ <version>2.2.1</version>
+ <executions>
+ <execution>
+ <id>attach-sources</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>2.10.4</version>
+ <executions>
+ <execution>
+ <id>attach-javadocs</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <!-- workaround for https://bugs.openjdk.java.net/browse/JDK-8212233 -->
+ <javaApiLinks>
+ <property>
+ <name>foo</name>
+ <value>bar</value>
+ </property>
+ </javaApiLinks>
+ <!-- Workaround for https://stackoverflow.com/questions/49472783/maven-is-unable-to-find-javadoc-command -->
+ <javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-release-plugin</artifactId>
+ <version>2.5.2</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven.scm</groupId>
+ <artifactId>maven-scm-provider-gitexe</artifactId>
+ <version>1.9.4</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+
+
+ </plugins>
+
+ <extensions>
+ <extension>
+ <groupId>org.apache.maven.wagon</groupId>
+ <artifactId>wagon-ssh-external</artifactId>
+ <version>2.6</version>
+ </extension>
+ </extensions>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.8.1</version>
+ <scope>test</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ <version>2.5</version>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+
+ <distributionManagement>
+ <snapshotRepository>
+ <id>svjatoslav.eu</id>
+ <name>svjatoslav.eu</name>
+ <url>scpexe://svjatoslav.eu:10006/srv/maven</url>
+ </snapshotRepository>
+ <repository>
+ <id>svjatoslav.eu</id>
+ <name>svjatoslav.eu</name>
+ <url>scpexe://svjatoslav.eu:10006/srv/maven</url>
+ </repository>
+ </distributionManagement>
+
+ <scm>
+ <connection>scm:git:ssh://n0@svjatoslav.eu:10006/home/n0/git/svjatoslav_commons.git</connection>
+ <developerConnection>scm:git:ssh://n0@svjatoslav.eu:10006/home/n0/git/svjatoslav_commons.git</developerConnection>
+ <tag>HEAD</tag>
+ </scm>
+
+</project>
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.data;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+/**
+ * Reads individual bits from an input stream.
+ *
+ * <p>This class provides bit-level reading capabilities, allowing you to
+ * read any number of bits from an underlying input stream. Bits are read from
+ * most significant to least significant within each byte.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * InputStream input = new ByteArrayInputStream(new byte[]{0b10101010, 0b11001100});
+ * BitInputStream bis = new BitInputStream(input);
+ *
+ * int first3Bits = bis.readBits(3); // Returns 0b101 (5)
+ * int next5Bits = bis.readBits(5); // Returns 0b01010 (10)
+ * int next8Bits = bis.readBits(8); // Returns 0b11001100 (204)
+ * }</pre>
+ *
+ * <p>This class is useful for applications that work with bit-packed data
+ * formats, such as custom compression algorithms, network protocols, or
+ * binary file formats where data is not byte-aligned.</p>
+ *
+ * @see BitOutputStream
+ */
+public class BitInputStream {
+
+ /**
+ * The underlying input stream from which bytes are read.
+ * Bytes are then disassembled into individual bits.
+ */
+ private final InputStream inputStream;
+
+ /**
+ * The current byte being processed. Bits are extracted from this byte
+ * one at a time as requested by read operations.
+ */
+ private int currentByte;
+
+ /**
+ * The current position within the current byte (0-7).
+ * Starts at -1 to indicate that no byte has been read yet.
+ * Bit 7 is the most significant bit, bit 0 is the least significant.
+ */
+ private int currentBytePointer = -1;
+
+ /**
+ * Creates a new BitInputStream that reads bits from the specified
+ * input stream.
+ *
+ * @param inputStream the underlying input stream to read bytes from.
+ * Must not be null.
+ */
+ public BitInputStream(final InputStream inputStream) {
+ this.inputStream = inputStream;
+ }
+
+ /**
+ * Reads the specified number of bits from the input stream.
+ *
+ * <p>Bits are read from most significant to least significant.
+ * The returned value is assembled with the first bit read becoming
+ * the most significant bit of the result.</p>
+ *
+ * <p>If the end of the stream is reached while reading, the remaining
+ * bits will be zero-filled. Reading zero bits returns zero.</p>
+ *
+ * <p>When crossing byte boundaries, the method automatically reads
+ * the next byte from the underlying stream.</p>
+ *
+ * @param bitCount the number of bits to read (0 to 32).
+ * Values greater than 32 may produce unexpected results.
+ * @return the assembled bits as an integer value, with the first bit
+ * read becoming the most significant bit of the result.
+ * @throws IOException if an I/O error occurs while reading from
+ * the underlying stream.
+ */
+ public int readBits(final int bitCount) throws IOException {
+
+ int readableByte = 0;
+ for (int i = 0; i < bitCount; i++) {
+
+ readableByte = readableByte << 1;
+
+ if (currentBytePointer == -1) {
+ currentBytePointer = 7;
+ currentByte = inputStream.read();
+ }
+
+ int mask = 1;
+ mask = mask << currentBytePointer;
+
+ final int currentBit = currentByte & mask;
+
+ if (currentBit != 0)
+ readableByte = readableByte | 1;
+
+ currentBytePointer--;
+ }
+ return readableByte;
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.data;
+
+import java.io.IOException;
+import java.io.OutputStream;
+
+/**
+ * Writes individual bits to an output stream.
+ *
+ * <p>This class provides bit-level writing capabilities, allowing you to
+ * write any number of bits to an underlying output stream. Bits are written
+ * from most significant to least significant within each byte.</p>
+ *
+ * <p>Writing starts from the most significant bit (bit 7) of each byte and
+ * proceeds to the least significant bit (bit 0). When a byte is complete
+ * (8 bits written), it is flushed to the underlying stream automatically.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ByteArrayOutputStream output = new ByteArrayOutputStream();
+ * BitOutputStream bos = new BitOutputStream(output);
+ *
+ * bos.storeBits(0b101, 3); // Writes 3 bits: 101
+ * bos.storeBits(0b11110000, 8); // Writes 8 bits: 11110000
+ * bos.storeBits(0b11, 2); // Writes 2 bits: 11
+ * bos.finishByte(); // Flushes partial byte if any
+ *
+ * byte[] result = output.toByteArray();
+ * }</pre>
+ *
+ * <p>This class is useful for applications that create bit-packed data
+ * formats, such as custom compression algorithms, network protocols, or
+ * binary file formats where data is not byte-aligned.</p>
+ *
+ * <p><strong>Important:</strong> Always call {@link #finishByte()} when done
+ * writing to ensure any partially written byte is flushed to the output stream.</p>
+ *
+ * @see BitInputStream
+ */
+public class BitOutputStream {
+
+ /**
+ * The underlying output stream where assembled bytes are written.
+ * Bytes are accumulated from individual bits before being written.
+ */
+ private final OutputStream outputStream;
+
+ /**
+ * The current byte being assembled from individual bits.
+ * Bits are added from most significant to the least significant position.
+ */
+ private int currentByte;
+
+ /**
+ * The current position within the current byte (0-7).
+ * Counts how many bits have been written to the current byte.
+ * When it reaches 8, the byte is flushed and the counter resets to 0.
+ */
+ private int currentBytePointer;
+
+ /**
+ * Creates a new BitOutputStream that writes bits to the specified
+ * output stream.
+ *
+ * <p>The output stream is not modified until at least 8 bits have
+ * been written, or {@link #finishByte()} is called.</p>
+ *
+ * @param outputStream the underlying output stream to write bytes to.
+ * Must not be null.
+ */
+ public BitOutputStream(final OutputStream outputStream) {
+ currentByte = 0;
+ currentBytePointer = 0;
+ this.outputStream = outputStream;
+ }
+
+ /**
+ * Finishes writing the current incomplete byte to the output stream.
+ *
+ * <p>If less than 8 bits have been written to the current byte,
+ * the remaining bits are filled with zeros and the byte is written.
+ * If exactly 8 bits have been written (byte already flushed), this
+ * method does nothing.</p>
+ *
+ * <p><strong>Important:</strong> Always call this method when finished
+ * writing to ensure all data is flushed to the output stream. Otherwise,
+ * the last partial byte may be lost.</p>
+ *
+ * @throws IOException if an I/O error occurs while writing to
+ * the underlying stream.
+ */
+ public void finishByte() throws IOException {
+ if (currentBytePointer != 0) {
+ outputStream.write(currentByte);
+ currentBytePointer = 0;
+ }
+ }
+
+ /**
+ * Writes the specified number of bits from the data value to the output stream.
+ *
+ * <p>Bits are taken from the most significant positions of the data value.
+ * For example, calling {@code storeBits(0b1011, 3)} will write the 3 most
+ * significant bits: 101.</p>
+ *
+ * <p>Bits are written from most significant to least significant within
+ * each byte. When a byte is completed (8 bits), it is automatically
+ * flushed to the underlying stream.</p>
+ *
+ * <p>Writing zero bits does nothing and does not advance the byte pointer.</p>
+ *
+ * @param data the integer value containing the bits to write.
+ * Only the specified number of most significant bits are used.
+ * @param bitCount the number of bits to write (0 to 32).
+ * Values greater than 32 may produce unexpected results.
+ * @throws IOException if an I/O error occurs while writing to
+ * the underlying stream.
+ */
+ public void storeBits(final int data, final int bitCount)
+ throws IOException {
+ for (int i = bitCount - 1; i >= 0; i--) {
+
+ int mask = 1;
+ mask = mask << i;
+
+ final int currentBit = data & mask;
+ currentByte = currentByte << 1;
+
+ if (currentBit != 0)
+ currentByte = currentByte | 1;
+ currentBytePointer++;
+
+ if (currentBytePointer == 8) {
+ currentBytePointer = 0;
+ outputStream.write(currentByte);
+ currentByte = 0;
+ }
+ }
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.data;
+
+/**
+ * Converts byte arrays to hexadecimal string representation.
+ *
+ * <p>This utility class provides a simple method to convert binary data
+ * into a human-readable hexadecimal format. Each byte is converted to
+ * two uppercase hexadecimal characters (0-9, A-F).</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * byte[] data = new byte[]{0x01, 0x02, 0xFF};
+ * String hex = HexConverter.byteArrayToHex(data);
+ * // Result: "0102FF"
+ *
+ * byte[] empty = new byte[]{};
+ * String emptyHex = HexConverter.byteArrayToHex(empty);
+ * // Result: ""
+ *
+ * String nullHex = HexConverter.byteArrayToHex(null);
+ * // Result: null
+ * }</pre>
+ *
+ * <p>This class is useful for:</p>
+ * <ul>
+ * <li>Displaying binary data in logs or debug output</li>
+ * <li>Creating checksums or hash representations</li>
+ * <li>Encoding binary data for text-based protocols</li>
+ * <li>Comparing byte arrays visually</li>
+ * </ul>
+ *
+ */
+public class HexConverter {
+
+ /**
+ * Private constructor to prevent instantiation.
+ *
+ * <p>This is a utility class with only static methods. It does not need
+ * to be instantiated.</p>
+ */
+ private HexConverter() {}
+
+ /**
+ * The lookup table for hexadecimal characters (0-9, A-F).
+ * Each nibble (4 bits, value 0-15) maps to the corresponding
+ * hexadecimal character.
+ */
+ static final String hexCharacters = "0123456789ABCDEF";
+
+ /**
+ * Converts a byte array to an uppercase hexadecimal string.
+ *
+ * <p>Each byte is converted to exactly two hexadecimal characters.
+ * The high nibble (bits 7-4) becomes the first character, and the
+ * low nibble (bits 3-0) becomes the second character.</p>
+ *
+ * <p>Example conversions:</p>
+ * <ul>
+ * <li>{@code byte 0x00} → "00"</li>
+ * <li>{@code byte 0x0F} → "0F"</li>
+ * <li>{@code byte 0xFF} → "FF"</li>
+ * <li>{@code byte 0xAB} → "AB"</li>
+ * </ul>
+ *
+ * <p>The result is always uppercase. Empty arrays return an empty string.
+ * Null arrays return null.</p>
+ *
+ * @param bytes the byte array to convert. May be null or empty.
+ * @return an uppercase hexadecimal string representation, or null
+ * if the input was null. The string length is always twice
+ * the byte array length.
+ */
+ public static String byteArrayToHex(final byte[] bytes) {
+
+ if (bytes == null)
+ return null;
+
+ final StringBuilder result = new StringBuilder(2 * bytes.length);
+
+ for (final byte b : bytes)
+ result.append(hexCharacters.charAt((b & 0xF0) >> 4)).append(
+ hexCharacters.charAt((b & 0x0F)));
+
+ return result.toString();
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+
+/**
+ * Provides utility classes for binary data manipulation and conversion.
+ *
+ * <p>This package contains classes for working with data at the bit level
+ * and converting binary data to human-readable formats:</p>
+ *
+ * <ul>
+ * <li>{@link eu.svjatoslav.commons.data.BitInputStream} - Read individual bits from an input stream</li>
+ * <li>{@link eu.svjatoslav.commons.data.BitOutputStream} - Write individual bits to an output stream</li>
+ * <li>{@link eu.svjatoslav.commons.data.HexConverter} - Convert byte arrays to hexadecimal strings</li>
+ * </ul>
+ *
+ * <p>These utilities are useful for applications that need fine-grained
+ * control over binary data, such as compression algorithms, custom file
+ * formats, or network protocols.</p>
+ *
+ * @author Svjatoslav Agejenko
+ * @since 1.0
+ * @see eu.svjatoslav.commons.data.BitInputStream
+ * @see eu.svjatoslav.commons.data.BitOutputStream
+ * @see eu.svjatoslav.commons.data.HexConverter
+ */
+package eu.svjatoslav.commons.data;
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.file;
+
+import java.io.File;
+
+/**
+ * Resolves common system paths and directories.
+ *
+ * <p>This utility class provides static methods to obtain common file system
+ * paths that are frequently needed in applications, such as the user's home
+ * directory, configuration directories, or temporary directories.</p>
+ *
+ * <p>Currently provides:</p>
+ * <ul>
+ * <li>User home directory - the personal directory of the current user</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * File homeDir = CommonPathResolver.getHomeDirectory();
+ * File configFile = new File(homeDir, ".myapp/config.properties");
+ * }</pre>
+ *
+ * <p>This class is designed to be extended with additional common path
+ * resolution methods as needed.</p>
+ *
+ */
+public class CommonPathResolver {
+
+ /**
+ * Private constructor to prevent instantiation.
+ *
+ * <p>This is a utility class with only static methods. It does not need
+ * to be instantiated.</p>
+ */
+ private CommonPathResolver() {}
+
+ /**
+ * Returns the current user's home directory.
+ *
+ * <p>This is typically the personal directory of the logged-in user,
+ * such as:</p>
+ * <ul>
+ * <li>On Linux/Mac: "/home/username" or "/Users/username"</li>
+* <li>On Windows: "C:\\Users\\username"</li>
+ * </ul>
+ *
+ * <p>This is a convenient location for storing user-specific configuration
+ * files, documents, and application data.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * File home = CommonPathResolver.getHomeDirectory();
+ * System.out.println("Home directory: " + home.getAbsolutePath());
+ *
+ * // Create an application config directory
+ * File configDir = new File(home, ".myapp");
+ * configDir.mkdirs();
+ * }</pre>
+ *
+ * @return a File object representing the user's home directory.
+ * The directory typically exists and is readable/writable
+ * by the current user.
+ */
+ public static File getHomeDirectory() {
+ return new File(System.getProperty("user.home"));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.file;
+
+import java.io.File;
+
+/**
+ * Utility class for parsing file paths and extracting file metadata.
+ *
+ * <p>This class provides static methods for extracting file extensions,
+ * file names without extensions, and formatting file sizes for display.
+ * All methods are simple utilities that operate on file names or paths.</p>
+ *
+ * <p>Key features:</p>
+ * <ul>
+ * <li>Extract file extensions (lowercase normalized)</li>
+ * <li>Get file names without extensions</li>
+ * <li>Format file sizes with appropriate binary units (b, KiB, MiB, GiB, TiB, PiB)</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * // Get file extension
+ * String ext = FilePathParser.getFileExtension("document.PDF");
+ * // Result: "pdf" (lowercase)
+ *
+ * // Get file name without extension
+ * String name = FilePathParser.getFileNameWithoutExtension(new File("image.jpg"));
+ * // Result: "image"
+ *
+ * // Format file size
+ * String size = FilePathParser.getFileSizeDescription(15728640);
+ * // Result: "15 MiB"
+ * }</pre>
+ *
+ * <p><strong>Note on extensions:</strong> For files with multiple dots,
+ * only the last dot-separated segment is considered the extension.
+ * For example, "archive.tar.gz" has extension "gz", not "tar.gz".</p>
+ */
+public class FilePathParser {
+
+ /**
+ * Private constructor to prevent instantiation.
+ *
+ * <p>This is a utility class with only static methods. It does not need
+ * to be instantiated.</p>
+ */
+ private FilePathParser() {}
+
+ /**
+ * Returns the file extension from a File object.
+ *
+ * <p>The extension is extracted from the file name (not the full path)
+ * and returned in lowercase. Files without an extension return an
+ * empty string.</p>
+ *
+ * <p>Example results:</p>
+ * <ul>
+ * <li>"document.TXT" → "txt"</li>
+ * <li>"image.JPG" → "jpg"</li>
+ * <li>"archive.tar.gz" → "gz"</li>
+ * <li>"README" → "" (empty string)</li>
+ * </ul>
+ *
+ * @param file the file to extract the extension from. Must not be null.
+ * @return the file extension in lowercase, or an empty string if the
+ * file has no extension (no dot in the name, or dot at the start).
+ */
+ public static String getFileExtension(final File file) {
+ final String fullFileName = file.getName();
+
+ return getFileExtension(fullFileName);
+ }
+
+ /**
+ * Returns the file extension from a file name string.
+ *
+ * <p>The extension is extracted from the last dot-separated segment
+ * and returned in lowercase. File names without an extension return
+ * an empty string.</p>
+ *
+ * <p>Example results:</p>
+ * <ul>
+ * <li>"document.TXT" → "txt"</li>
+ * <li>"archive.tar.gz" → "gz"</li>
+ * <li>".gitignore" → "gitignore"</li>
+ * <li>"noextension" → ""</li>
+ * <li>"file." → ""</li>
+ * </ul>
+ *
+ * @param fullFileName the file name (not full path) to parse.
+ * Must not be null.
+ * @return the file extension in lowercase, or an empty string if the
+ * file has no extension.
+ */
+ public static String getFileExtension(final String fullFileName) {
+ final int dot = fullFileName.lastIndexOf('.');
+ String fileExtension;
+ if (dot == -1)
+ fileExtension = "";
+ else {
+ fileExtension = fullFileName.substring(dot + 1);
+ fileExtension = fileExtension.toLowerCase();
+ }
+
+ return fileExtension;
+ }
+
+ /**
+ * Returns the file name without its extension from a File object.
+ *
+ * <p>The base name is everything before the last dot. If the file
+ * has no extension, the entire file name is returned.</p>
+ *
+ * <p>Example results:</p>
+ * <ul>
+ * <li>"document.txt" → "document"</li>
+ * <li>"archive.tar.gz" → "archive.tar"</li>
+ * <li>"README" → "README"</li>
+ * <li>"file." → "file"</li>
+ * </ul>
+ *
+ * @param file the file to extract the base name from. Must not be null.
+ * @return the file name without the extension. Returns the complete
+ * file name if there is no extension.
+ */
+ public static String getFileNameWithoutExtension(final File file) {
+ final String fullFileName = file.getName();
+ return getFileNameWithoutExtension(fullFileName);
+ }
+
+ /**
+ * Returns the file name without its extension from a file name string.
+ *
+ * <p>The base name is everything before the last dot. If the file
+ * has no extension, the entire file name is returned.</p>
+ *
+ * <p>Example results:</p>
+ * <ul>
+ * <li>"document.txt" → "document"</li>
+ * <li>"archive.tar.gz" → "archive.tar"</li>
+ * <li>".gitignore" → ""</li>
+ * <li>"noextension" → "noextension"</li>
+ * </ul>
+ *
+ * @param fullFileName the file name (not full path) to parse.
+ * Must not be null.
+ * @return the file name without the extension. Returns the complete
+ * file name if there is no extension.
+ */
+ public static String getFileNameWithoutExtension(final String fullFileName) {
+ final int dot = fullFileName.lastIndexOf('.');
+ String fileName;
+ if (dot == -1)
+ fileName = fullFileName;
+ else
+ fileName = fullFileName.substring(0, dot);
+
+ return fileName;
+ }
+
+ /**
+ * Returns a human-readable description of a file size using binary units.
+ *
+ * <p>The size is formatted with appropriate binary units (IEC standard).
+ * Larger units are used only when the size is at least 5 units of that size:</p>
+ * <table border="1">
+ * <caption>Size unit thresholds</caption>
+ * <tr><th>Unit</th><th>Threshold</th></tr>
+ * <tr><td>bytes (b)</td><td>< 5 KiB (5120 bytes)</td></tr>
+ * <tr><td>kibibytes (KiB)</td><td>≥ 5 KiB, < 5 MiB</td></tr>
+ * <tr><td>mebibytes (MiB)</td><td>≥ 5 MiB, < 5 GiB</td></tr>
+ * <tr><td>gibibytes (GiB)</td><td>≥ 5 GiB, < 5 TiB</td></tr>
+ * <tr><td>tebibytes (TiB)</td><td>≥ 5 TiB, < 5 PiB</td></tr>
+ * <tr><td>pebibytes (PiB)</td><td>≥ 5 PiB</td></tr>
+ * </table>
+ *
+ * <p>Example results:</p>
+ * <ul>
+ * <li>500 bytes → "500 b"</li>
+ * <li>1024 bytes → "1024 b"</li>
+ * <li>5120 bytes (5 KiB) → "5 KiB"</li>
+ * <li>1048576 bytes (1 MiB) → "1024 KiB"</li>
+ * <li>5242880 bytes (5 MiB) → "5120 KiB"</li>
+ * <li>5242881 bytes → "5 MiB"</li>
+ * <li>1073741824 bytes (1 GiB) → "1024 MiB"</li>
+ * </ul>
+ *
+ * <p><strong>Note:</strong> This method uses binary units (KiB = 1024 bytes,
+ * MiB = 1024 KiB, etc.) per the IEC standard, not SI units (KB = 1000 bytes).</p>
+ *
+ * @param fileSize the file size in bytes. Negative values will produce
+ * unexpected results.
+ * @return a human-readable size description with binary units.
+ */
+ public static String getFileSizeDescription(long fileSize) {
+ final long KIB = 1L << 10;
+ final long MIB = 1L << 20;
+ final long GIB = 1L << 30;
+ final long TIB = 1L << 40;
+ final long PIB = 1L << 50;
+
+ if (fileSize >= 5L * PIB) {
+ return (fileSize / PIB) + " PiB";
+ } else if (fileSize >= 5L * TIB) {
+ return (fileSize / TIB) + " TiB";
+ } else if (fileSize >= 5L * GIB) {
+ return (fileSize / GIB) + " GiB";
+ } else if (fileSize >= 5L * MIB) {
+ return (fileSize / MIB) + " MiB";
+ } else if (fileSize >= 5L * KIB) {
+ return (fileSize / KIB) + " KiB";
+ } else {
+ return fileSize + " b";
+ }
+ }
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.file;
+
+import java.io.*;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static java.nio.file.Files.isSymbolicLink;
+
+/**
+ * Utility class for common file system operations.
+ *
+ * <p>This class provides static methods for file I/O operations including:
+ * reading and writing files, recursive directory deletion, and smart file
+ * overwriting that only writes when content differs.</p>
+ *
+ * <p>Key features:</p>
+ * <ul>
+ * <li>Safe recursive deletion that does not follow symbolic links</li>
+ * <li>UTF-8 encoding for text file operations</li>
+ * <li>Smart overwriting that avoids unnecessary disk writes</li>
+ * <li>Simple byte array and string-based file operations</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * // Write and read a text file
+ * File file = new File("example.txt");
+ * IOHelper.saveToFile(file, "Hello, World!");
+ * String content = IOHelper.getFileContentsAsString(file);
+ *
+ * // Smart overwriting - only writes if content differs
+ * IOHelper.overwriteFileIfContentDiffers(file, "New content".getBytes());
+ *
+ * // Delete a directory recursively
+ * File directory = new File("temp");
+ * IOHelper.deleteRecursively(directory);
+ * }</pre>
+ *
+ * <p><strong>Note on symbolic links:</strong> The {@link #deleteRecursively(File)}
+ * method handles symbolic links safely. When a symlink points to a directory,
+ * the directory's contents are not deleted - only the symlink itself is removed.
+ * This prevents accidental deletion of data outside the intended scope.</p>
+ *
+ */
+public class IOHelper {
+
+ /**
+ * Private constructor to prevent instantiation.
+ *
+ * <p>This is a utility class with only static methods. It does not need
+ * to be instantiated.</p>
+ */
+ private IOHelper() {}
+
+ /**
+ * Deletes a file or directory recursively. Does not follow symbolic links.
+ *
+ * <p>This method safely handles:</p>
+ * <ul>
+ * <li>Regular files - deleted directly</li>
+ * <li>Directories - contents deleted first, then the directory itself</li>
+ * <li>Symbolic links - the link is deleted, not the target</li>
+ * <li>Symbolic links to directories - link deleted, target directory untouched</li>
+ * </ul>
+ *
+ * <p>The non-following of symlinks is an important safety feature. If a
+ * symlink points to an important directory outside the scope of deletion,
+ * that directory's contents remain safe.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * // Delete a file
+ * IOHelper.deleteRecursively(new File("temp.txt"));
+ *
+ * // Delete a directory with all contents
+ * IOHelper.deleteRecursively(new File("tempDir"));
+ *
+ * // Delete a symlink (target remains intact)
+ * IOHelper.deleteRecursively(new File("linkToOtherDir"));
+ * }</pre>
+ *
+ * @param file the file, directory, or symbolic link to delete.
+ * Must not be null.
+ * @throws IOException if a filesystem error occurs during deletion,
+ * such as permission denied or file in use.
+ */
+ public static void deleteRecursively(final File file) throws IOException {
+
+ if (file.isDirectory()) {
+ deleteDirectory(file);
+ return;
+ }
+
+ if (file.isFile()){
+ if (!file.delete()) throw new IOException("Failed to delete file: " + file);
+ } else {
+ if (isSymbolicLink(file.toPath()) && !file.delete())
+ throw new IOException("Failed to delete symlink: " + file);
+ }
+ }
+
+ /**
+ * Deletes a directory and all its contents recursively.
+ *
+ * <p>If the directory is a symbolic link, only the link is deleted
+ * (not the target directory's contents). This prevents accidental
+ * deletion of data outside the intended scope.</p>
+ *
+ * @param file the directory to delete. Must not be null.
+ * @throws IOException if a filesystem error occurs, such as
+ * failure to read directory contents or delete files.
+ */
+ private static void deleteDirectory(File file) throws IOException {
+ // if file is symlink that points to directory, do not touch content
+ if (!isSymbolicLink(file.toPath())){
+ File[] files = file.listFiles();
+ if (files == null)
+ throw new IOException("Failed to read directory content for: "
+ + file);
+
+ for (final File subFile : files)
+ deleteRecursively(subFile);
+ }
+
+ if (!file.delete())
+ throw new IOException("Failed to delete directory: " + file);
+ }
+
+ /**
+ * Reads the entire contents of a file as a byte array.
+ *
+ * <p>The file must exist and its size must fit in memory. This method
+ * is suitable for small to medium-sized files. For large files, consider
+ * using streaming approaches instead.</p>
+ *
+ * <p>The returned array has exactly the same length as the file size.</p>
+ *
+ * @param file the file to read. Must exist and be readable.
+ * @return the complete file contents as a byte array.
+ * @throws IOException if an I/O error occurs, such as file not found
+ * or permission denied.
+ * @throws RuntimeException if the file could not be fully read
+ * (unexpected EOF).
+ */
+ public static byte[] getFileContents(final File file)
+ throws IOException {
+
+ final byte[] result = new byte[(int) file.length()];
+ try (final FileInputStream fileInputStream = new FileInputStream(file)) {
+ if (fileInputStream.read(result) != result.length)
+ throw new RuntimeException("Could not read file content:" + file);
+ }
+ return result;
+ }
+
+ /**
+ * Reads the entire contents of a file as a UTF-8 encoded string.
+ *
+ * <p>The file content is assumed to be UTF-8 encoded. This is the
+ * standard encoding for text files in most modern applications.</p>
+ *
+ * <p>The file must exist and its size must fit in memory. This method
+ * is suitable for text files of reasonable size.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * File file = new File("config.txt");
+ * String config = IOHelper.getFileContentsAsString(file);
+ * }</pre>
+ *
+ * @param file the file to read. Must exist and be readable.
+ * @return the file contents as a UTF-8 decoded string.
+ * @throws IOException if an I/O error occurs during file reading.
+ */
+ public static String getFileContentsAsString(final File file)
+ throws IOException {
+ try {
+ return new String(getFileContents(file), UTF_8);
+ } catch (final UnsupportedEncodingException exception) {
+ throw new RuntimeException(exception);
+ }
+ }
+
+ /**
+ * Compares new content with existing file content and overwrites
+ * only if different.
+ *
+ * <p>This method performs a byte-by-byte comparison with the existing
+ * file content. If the content is identical, no write operation occurs,
+ * saving disk I/O and preserving file timestamps.</p>
+ *
+ * <p>This is useful for:</p>
+ * <ul>
+ * <li>Configuration files that might not change</li>
+ * <li>Generated source code to avoid triggering rebuilds</li>
+ * <li>Any case where unnecessary writes should be avoided</li>
+ * </ul>
+ *
+ * <p>If the file does not exist, it is created and the content is written.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * byte[] newConfig = generateConfig().getBytes();
+ * boolean changed = IOHelper.overwriteFileIfContentDiffers(
+ * new File("config.xml"), newConfig);
+ * if (changed) {
+ * System.out.println("Configuration updated");
+ * } else {
+ * System.out.println("No changes needed");
+ * }
+ * }</pre>
+ *
+ * @param file the file to potentially overwrite. If it does not exist,
+ * it will be created.
+ * @param newContent the new content to potentially write. Must not be null.
+ * @return {@code true} if the file was overwritten (content differed or
+ * file was created), {@code false} if the content was identical
+ * and no write occurred.
+ * @throws FileNotFoundException if the file cannot be found for reading
+ * (when comparing existing content).
+ * @throws IOException if an I/O error occurs during reading or writing.
+ */
+ public static boolean overwriteFileIfContentDiffers(final File file,
+ final byte[] newContent) throws IOException {
+
+ checkForEquality:
+ {
+ if (file.length() == newContent.length) {
+
+ final byte[] oldContent = getFileContents(file);
+
+ for (int i = 0; i < newContent.length; i++)
+ if (newContent[i] != oldContent[i])
+ break checkForEquality;
+
+ // new file content is identical to old content
+ return false;
+ }
+ }
+
+ // New content differs from existing. Overwrite file.
+ saveToFile(file, newContent);
+ return true;
+ }
+
+ /**
+ * Saves byte content to a file, overwriting any existing content.
+ *
+ * <p>This method writes the complete byte array to the file. If the
+ * file exists, it is overwritten. If it does not exist, it is created.</p>
+ *
+ * <p>This is a straightforward write operation - use
+ * {@link #overwriteFileIfContentDiffers(File, byte[])} if you want to
+ * avoid unnecessary writes when content is unchanged.</p>
+ *
+ * @param file the file to write to. Parent directories must exist.
+ * @param content the byte content to write. Must not be null.
+ * @throws IOException if an I/O error occurs during writing.
+ */
+ public static void saveToFile(final File file, final byte[] content)
+ throws IOException {
+ try (final FileOutputStream fos = new FileOutputStream(file)) {
+ fos.write(content);
+ }
+ }
+
+ /**
+ * Saves string content to a file using UTF-8 encoding, overwriting
+ * any existing content.
+ *
+ * <p>The string is encoded as UTF-8 before writing. If the file exists,
+ * it is overwritten. If it does not exist, it is created.</p>
+ *
+ * <p>This is a convenient method for writing text files:</p>
+ * <pre>{@code
+ * IOHelper.saveToFile(new File("output.txt"), "Hello, World!");
+ * }</pre>
+ *
+ * @param file the file to write to. Parent directories must exist.
+ * @param content the string content to write, encoded as UTF-8.
+ * Must not be null.
+ * @throws IOException if an I/O error occurs during writing.
+ */
+ public static void saveToFile(final File file, final String content)
+ throws IOException {
+ saveToFile(file, content.getBytes(UTF_8));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+
+/**
+ * Provides utility classes for file system operations and path handling.
+ *
+ * <p>This package contains classes for common file operations:</p>
+ *
+ * <ul>
+ * <li>{@link eu.svjatoslav.commons.file.IOHelper} - File I/O utilities including recursive deletion,
+ * reading/writing files, and smart file overwriting</li>
+ * <li>{@link eu.svjatoslav.commons.file.FilePathParser} - Parse file paths to extract extensions,
+ * file names, and format file sizes</li>
+ * <li>{@link eu.svjatoslav.commons.file.CommonPathResolver} - Resolve common system paths
+ * such as user home directory</li>
+ * </ul>
+ *
+ * <p>These utilities simplify common file operations that would otherwise require
+ * repetitive boilerplate code. The {@link eu.svjatoslav.commons.file.IOHelper} class
+ * in particular handles edge cases like symbolic links and recursive directory deletion.</p>
+ *
+ * @author Svjatoslav Agejenko
+ * @since 1.0
+ * @see eu.svjatoslav.commons.file.IOHelper
+ * @see eu.svjatoslav.commons.file.FilePathParser
+ * @see eu.svjatoslav.commons.file.CommonPathResolver
+ */
+package eu.svjatoslav.commons.file;
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.gui.dialog;
+
+import javax.swing.*;
+import java.awt.*;
+
+import static javax.swing.BoxLayout.Y_AXIS;
+
+/**
+ * A graphical dialog for displaying exceptions with stack traces.
+ *
+ * <p>This Swing-based dialog provides a user-friendly way to display
+ * exceptions and their stack traces in graphical applications. It shows:</p>
+ *
+ * <ul>
+ * <li>Exception type (class name)</li>
+ * <li>Error message</li>
+ * <li>Cause message (if available)</li>
+ * <li>Complete stack trace</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * try {
+ * // some operation that might fail
+ * } catch (Exception e) {
+ * new ExceptionDialog(e);
+ * }
+ * }</pre>
+ *
+ * <p>The dialog opens a new JFrame window with the exception details.
+ * The window is 800x600 pixels and centered on screen.</p>
+ *
+ * <p><strong>Note:</strong> This class requires a graphical environment
+ * and Swing libraries. It is not suitable for headless or server-side
+ * applications. For non-graphical error reporting, use standard logging
+ * or console output instead.</p>
+ *
+ */
+public class ExceptionDialog {
+
+ /**
+ * Creates and displays an exception dialog for the given exception.
+ *
+ * <p>The dialog is shown immediately upon construction. This is a
+ * convenience for quick exception display without additional setup.</p>
+ *
+ * @param exception the exception to display. Must not be null.
+ */
+ public ExceptionDialog(final Exception exception) {
+ showException(exception);
+ }
+
+ /**
+ * Main method for testing the exception dialog.
+ *
+ * <p>This method creates a sample exception with a cause and displays
+ * it in the dialog, allowing developers to test the dialog appearance
+ * without needing actual exceptions.</p>
+ *
+ * @param args command line arguments (ignored).
+ */
+ public static void main(final String[] args) {
+
+ final Throwable cause = new Throwable("details.....");
+
+ final Exception exception = new Exception("test", cause);
+
+ new ExceptionDialog(exception);
+ }
+
+ /**
+ * Displays the exception in a new JFrame window.
+ *
+ * <p>Creates a window with:</p>
+ * <ul>
+ * <li>Top panel showing exception type, message, and cause</li>
+ * <li>Center panel showing the stack trace in a text area</li>
+ * </ul>
+ *
+ * <p>The window is sized 800x600 pixels and centered on the screen.
+ * It closes when the user clicks the close button (DISPOSE_ON_CLOSE).</p>
+ *
+ * @param exception the exception to display. Must not be null.
+ */
+ public void showException(final Exception exception) {
+ final JPanel contentPanel = new JPanel(new BorderLayout());
+ contentPanel.add(getTopPanel(exception), BorderLayout.NORTH);
+ contentPanel.add(getStackTraceView(exception.getCause()), BorderLayout.CENTER);
+
+ final JFrame frame = new JFrame("Exception occurred!");
+ frame.getContentPane().add(contentPanel);
+ frame.setSize(800, 600);
+ frame.setVisible(true);
+ frame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE);
+ frame.setLocationRelativeTo(null); // center frame on screen
+ }
+
+ /**
+ * Creates a text area displaying the stack trace.
+ *
+ * <p>If a cause is provided, shows the cause's stack trace. Otherwise,
+ * shows a placeholder message and the current stack trace for context.</p>
+ *
+ * @param cause the cause of the exception, or null if no cause is available.
+ * @return a TextArea containing the stack trace text.
+ */
+ private TextArea getStackTraceView(Throwable cause) {
+ final StringBuilder buffer = new StringBuilder();
+
+ if (cause != null) {
+ // if cause is available, show original stack trace
+ buffer.append("Stack trace:\n");
+ final StackTraceElement[] stackTrace = cause.getStackTrace();
+ enlistStackTraceElements(buffer, stackTrace);
+ } else {
+ // otherwise show at least current stack trace
+ buffer.append("Stack trace from original cause is not available.\n" +
+ "Showing current stack trace instead:\n");
+ enlistStackTraceElements(buffer, new Exception("Stack trace").getStackTrace());
+ }
+
+ return new TextArea(buffer.toString());
+ }
+
+ /**
+ * Appends stack trace elements to a StringBuilder buffer.
+ *
+ * <p>Each element is converted to a string and appended on a new line.</p>
+ *
+ * @param buffer the StringBuilder to append to. Must not be null.
+ * @param stackTrace the array of stack trace elements to append.
+ * May be empty but must not be null.
+ */
+ private void enlistStackTraceElements(StringBuilder buffer, StackTraceElement[] stackTrace) {
+ for (final StackTraceElement stackTraceElement : stackTrace)
+ buffer.append(stackTraceElement.toString()).append("\n");
+ }
+
+ /**
+ * Creates a panel showing exception summary information.
+ *
+ * <p>The panel contains JLabels for:</p>
+ * <ul>
+ * <li>Exception type (canonical class name)</li>
+ * <li>Error message from the exception</li>
+ * <li>Cause message (if cause exists and has a message)</li>
+ * </ul>
+ *
+ * @param exception the exception to display information for. Must not be null.
+ * @return a JPanel containing the exception summary labels.
+ */
+ private JPanel getTopPanel(Exception exception) {
+
+ final JPanel topPanel = new JPanel();
+ topPanel.setLayout(new BoxLayout(topPanel, Y_AXIS));
+
+ // add an exception type
+ topPanel.add(
+ new JLabel("Exception type: " + exception.getClass().getCanonicalName()));
+
+ // add an error message
+ topPanel.add(new JLabel("Error message: " + exception.getMessage()));
+
+ // add a cause message
+ Throwable cause = exception.getCause();
+ if (cause != null && cause.getMessage() != null)
+ topPanel.add(new JLabel("Cause: " + cause.getMessage()));
+ return topPanel;
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+
+/**
+ * Provides Swing-based dialog components for graphical user interfaces.
+ *
+ * <p>This package contains utility dialogs for displaying information
+ * to users in graphical applications:</p>
+ *
+ * <ul>
+ * <li>{@link eu.svjatoslav.commons.gui.dialog.ExceptionDialog} - Display exceptions with
+ * stack traces in a user-friendly dialog window</li>
+ * </ul>
+ *
+ * <p>These dialogs are designed to be simple to use and provide immediate
+ * visual feedback for application errors, making debugging and user
+ * communication easier in GUI applications.</p>
+ *
+ * <p>Note: This package requires a graphical environment and Swing libraries.
+ * It is not suitable for headless or server-side applications.</p>
+ *
+ * @author Svjatoslav Agejenko
+ * @since 1.0
+ * @see eu.svjatoslav.commons.gui.dialog.ExceptionDialog
+ */
+package eu.svjatoslav.commons.gui.dialog;
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string;
+
+/**
+ * Matches strings against glob-style wildcard patterns.
+ *
+ * <p>This class provides simple glob pattern matching similar to shell
+ * wildcards, using two special characters:</p>
+ *
+ * <ul>
+ * <li>{@code *} - Matches any sequence of characters (zero or more)</li>
+ * <li>{@code ?} - Matches exactly one character</li>
+ * </ul>
+ *
+ * <p>All other characters match literally (case-sensitive).</p>
+ *
+ * <p>Example patterns and matches:</p>
+ * <pre>{@code
+ * "*.txt" matches: "file.txt", "document.txt", ".txt"
+ * "*.txt" does NOT match: "file.TXT" (case-sensitive)
+ *
+ * "file?.txt" matches: "file1.txt", "fileA.txt", "file_.txt"
+ * "file?.txt" does NOT match: "file.txt", "file12.txt"
+ *
+ * "test*" matches: "test", "testing", "test123"
+ * "*test" matches: "test", "mytest", "123test"
+ *
+ * "*_*" matches: "a_b", "hello_world", "_"
+ * }</pre>
+ *
+ * <p>This is simpler than regular expressions but useful for basic
+ * pattern matching in file name filtering, simple validation, or
+ * user-friendly pattern input.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * if (GlobMatcher.match("document.TXT", "*.txt")) {
+ * // This will NOT match (case-sensitive)
+ * }
+ *
+ * if (GlobMatcher.match("image.jpg", "*.jpg")) {
+ * // This will match
+ * }
+ *
+ * if (GlobMatcher.match("file123", "file?*")) {
+ * // This will match (? for one char, * for remaining)
+ * }
+ * }</pre>
+ *
+ * <p><strong>Null handling:</strong> Both string and pattern arguments
+ * are handled gracefully - if either is null, the result is {@code false}.</p>
+ */
+public class GlobMatcher {
+
+ /**
+ * Private constructor to prevent instantiation.
+ *
+ * <p>This is a utility class with only static methods. It does not need
+ * to be instantiated.</p>
+ */
+ private GlobMatcher() {}
+
+ /**
+ * Checks if the remaining portion of a wildcard expression consists
+ * only of asterisks.
+ *
+ * <p>This is used during matching to determine if a partial match
+ * can succeed. If only asterisks remain, any remaining input string
+ * content will match.</p>
+ *
+ * @param wildcardExpression the wildcard pattern to check.
+ * @param wildCardPosition the starting position within the pattern.
+ * @return {@code true} if all remaining characters are asterisks,
+ * {@code false} otherwise.
+ */
+ private static boolean checkWildCardEnd(final String wildcardExpression,
+ int wildCardPosition) {
+ for (; wildCardPosition < wildcardExpression.length(); wildCardPosition++) {
+ final char wildCardChar = wildcardExpression
+ .charAt(wildCardPosition);
+ if (wildCardChar != '*')
+ return false;
+ }
+
+ return true;
+ }
+
+ /**
+ * Tests if an input string matches a wildcard expression.
+ *
+ * <p>The wildcard expression uses:</p>
+ * <ul>
+ * <li>{@code *} - matches any sequence of characters (zero or more)</li>
+ * <li>{@code ?} - matches exactly one character</li>
+ * </ul>
+ *
+ * <p>All other characters must match exactly (case-sensitive).</p>
+ *
+ * <p>Matching rules:</p>
+ * <ul>
+ * <li>Empty pattern matches empty string only</li>
+ * <li>Pattern "*" matches any string (including empty)</li>
+ * <li>Pattern "?" matches any single character</li>
+ * <li>Null inputs result in {@code false}</li>
+ * </ul>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * GlobMatcher.match("file.txt", "*.txt"); // true
+ * GlobMatcher.match("file.TXT", "*.txt"); // false (case)
+ * GlobMatcher.match("file1", "file?"); // true
+ * GlobMatcher.match("file", "file?"); // false (too short)
+ * GlobMatcher.match("", "*"); // true
+ * GlobMatcher.match("", "?"); // false
+ * GlobMatcher.match(null, "*"); // false
+ * }</pre>
+ *
+ * @param inputString the string to test against the pattern.
+ * May be null (returns false).
+ * @param wildcardExpression the wildcard pattern to match against.
+ * May be null (returns false).
+ * @return {@code true} if the input string matches the wildcard pattern,
+ * {@code false} if it does not match or either argument is null.
+ */
+ public static boolean match(final String inputString,
+ final String wildcardExpression) {
+
+ if (inputString == null)
+ return false;
+
+ if (wildcardExpression == null)
+ return false;
+
+ int i;
+
+ for (i = 0; i < inputString.length(); i++) {
+ if (i >= wildcardExpression.length())
+ return false;
+ final char wildCardChar = wildcardExpression.charAt(i);
+ if (wildCardChar == '*')
+ return matchPiece(inputString, i, wildcardExpression, i + 1);
+ if (wildCardChar != '?')
+ if (inputString.charAt(i) != wildCardChar)
+ return false;
+ }
+
+ return checkWildCardEnd(wildcardExpression, i);
+ }
+
+ /**
+ * Handles matching after encountering an asterisk in the pattern.
+ *
+ * <p>This method attempts to match the remaining input against the
+ * remaining pattern, accounting for the asterisk's ability to match
+ * any number of characters. It tries multiple starting positions
+ * to find a valid match.</p>
+ *
+ * @param inputString the input string being matched.
+ * @param inputStringIndex the current position in the input string.
+ * @param wildcardExpression the wildcard pattern.
+ * @param wildCardExpressionIndex the position after the asterisk in the pattern.
+ * @return {@code true} if a valid match is found, {@code false} otherwise.
+ */
+ private static boolean matchPiece(final String inputString,
+ final int inputStringIndex, final String wildcardExpression,
+ final int wildCardExpressionIndex) {
+
+ int wildCardPosition = wildCardExpressionIndex;
+
+ for (int i = inputStringIndex; i < inputString.length(); i++) {
+
+ wildCardPosition = wildCardExpressionIndex;
+
+ subMatchAttempt:
+ {
+
+ for (int j = i; j < inputString.length(); j++) {
+ if (wildCardPosition >= wildcardExpression.length())
+ break subMatchAttempt;
+ final char wildCardChar = wildcardExpression
+ .charAt(wildCardPosition);
+
+ if (wildCardChar == '*')
+ return matchPiece(inputString, j, wildcardExpression,
+ wildCardPosition + 1);
+
+ if (wildCardChar != '?')
+ if (inputString.charAt(j) != wildCardChar)
+ break subMatchAttempt;
+
+ wildCardPosition++;
+ }
+
+ return checkWildCardEnd(wildcardExpression, wildCardPosition);
+ }
+
+ }
+
+ return checkWildCardEnd(wildcardExpression, wildCardPosition);
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * A mutable string builder optimized for prefix and suffix operations.
+ *
+ * <p>String2 provides a more intuitive alternative to {@link StringBuilder}
+ * for operations involving prefixes and suffixes. It uses a fluent API
+ * that allows method chaining for concise string manipulation.</p>
+ *
+ * <p>Key features:</p>
+ * <ul>
+ * <li>{@link #prepend(String)} - Add text at the beginning</li>
+ * <li>{@link #append(String)} - Add text at the end</li>
+ * <li>{@link #trimPrefix(int)} - Remove characters from the beginning</li>
+ * <li>{@link #trimSuffix(int)} - Remove characters from the end</li>
+ * <li>{@link #trimPrefixIfExists(String)} - Remove prefix if present</li>
+ * <li>{@link #trimSuffixIfExists(String)} - Remove suffix if present</li>
+ * <li>{@link #hasPrefix(String)} / {@link #hasSuffix(String)} - Check for prefix/suffix</li>
+ * <li>{@link #repeat(int)} - Repeat the string content</li>
+ * <li>{@link #enforceLength(int)} - Pad or truncate to exact length</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * String2 s = new String2("world");
+ * s.prepend("Hello, ").append("!");
+ * // Result: "Hello, world!"
+ *
+ * s.trimSuffix(1).append(" wonderful world!");
+ * // Result: "Hello, world wonderful world!"
+ *
+ * String2 path = new String2("/path/to/file");
+ * path.trimPrefixIfExists("/").prepend("./");
+ * // Result: "./path/to/file"
+ * }</pre>
+ *
+ * <p>All methods (except getters) return the same String2 instance, enabling
+ * fluent method chaining:</p>
+ * <pre>{@code
+ * String result = new String2()
+ * .append("hello")
+ * .appendWithSeparator(" ", "world")
+ * .prepend("Say: ")
+ * .append("!")
+ * .toString();
+ * }</pre>
+ */
+public class String2 {
+
+ /**
+ * The internal list of characters that make up the string.
+ * Characters are stored individually in an ArrayList, allowing
+ * efficient insertion at the beginning (prepend) and removal
+ * from either end (trimPrefix/trimSuffix).
+ */
+ private final List<Character> chars = new ArrayList<>();
+
+ /**
+ * Clears all characters from this string.
+ *
+ * <p>After calling this method, the string becomes empty (length 0).
+ * The fluent return allows immediate rebuilding of the string.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("hello");
+ * s.clear().append("world");
+ * // Result: "world"
+ * }</pre>
+ *
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 clear(){
+ chars.clear();
+ return this;
+ }
+
+ /**
+ * Creates a new String2 initialized with the given value.
+ *
+ * <p>If the value is null, an empty String2 is created.</p>
+ *
+ * @param value the initial string content. May be null.
+ */
+ public String2(String value) {
+ append(value);
+ }
+
+ /**
+ * Creates an empty String2.
+ *
+ * <p>The string has zero length initially. Use {@link #append(String)}
+ * or {@link #prepend(String)} to add content.</p>
+ */
+ public String2() {
+ }
+
+ /**
+ * Repeats the current string content the specified number of times.
+ *
+ * <p>The string is duplicated and appended to itself.</p>
+ * <ul>
+ * <li>count = 1: no change (string remains as-is)</li>
+ * <li>count = 2: string appears twice</li>
+ * <li>count = 0 or negative: string is cleared</li>
+ * </ul>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("ab");
+ * s.repeat(3);
+ * // Result: "ababab"
+ *
+ * s.repeat(0);
+ * // Result: "" (empty)
+ * }</pre>
+ *
+ * @param count the number of times to repeat the content.
+ * If less than 1, the string is cleared.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 repeat(int count){
+ if (count > 0) {
+ String value = toString();
+
+ for (int i = 1; i < count; i++)
+ append(value);
+ } else {
+ clear();
+ }
+ return this;
+ }
+
+ /**
+ * Inserts text at the beginning of this string.
+ *
+ * <p>The prefix is added before all existing characters. If the
+ * prefix is null, no change occurs.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("world");
+ * s.prepend("Hello, ");
+ * // Result: "Hello, world"
+ * }</pre>
+ *
+ * @param prefix the text to prepend. May be null (no effect).
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 prepend(final String prefix) {
+ if (prefix == null)
+ return this;
+
+ int i = 0;
+ for (final char c : prefix.toCharArray())
+ chars.add(i++, c);
+
+ return this;
+ }
+
+ /**
+ * Appends text at the end of this string.
+ *
+ * <p>The suffix is added after all existing characters. If the
+ * suffix is null, no change occurs.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("Hello");
+ * s.append(", world!");
+ * // Result: "Hello, world!"
+ * }</pre>
+ *
+ * @param suffix the text to append. May be null (no effect).
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 append(final String suffix) {
+ if (suffix == null)
+ return this;
+
+ for (final char c : suffix.toCharArray())
+ chars.add(c);
+
+ return this;
+ }
+
+ /**
+ * Appends text with a separator, only adding the separator if
+ * the string is not empty.
+ *
+ * <p>This is useful for building comma-separated or space-separated
+ * lists where the separator should not appear before the first item.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2();
+ * s.appendWithSeparator(", ", "apple");
+ * s.appendWithSeparator(", ", "banana");
+ * s.appendWithSeparator(", ", "cherry");
+ * // Result: "apple, banana, cherry"
+ * }</pre>
+ *
+ * @param separator the separator to insert before the suffix if
+ * the string is not empty. Must not be null.
+ * @param suffix the text to append. Must not be null.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 appendWithSeparator(String separator, final String suffix) {
+ if (!isEmpty())
+ append(separator);
+
+ append(suffix);
+
+ return this;
+ }
+
+ /**
+ * Appends the given string multiple times.
+ *
+ * <p>If times is zero, no change occurs. The string is appended
+ * repeatedly in sequence.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2();
+ * s.append("x", 5);
+ * // Result: "xxxxx"
+ * }</pre>
+ *
+ * @param s the string to append repeatedly. Must not be null.
+ * @param times the number of times to append. If zero, no change.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 append(String s, int times) {
+ for (int i = 0; i < times; i++) append(s);
+ return this;
+ }
+
+
+ /**
+ * Removes the specified number of characters from the beginning of this string.
+ *
+ * <p>If cutAmount exceeds the string length, the entire string is cleared.
+ * If cutAmount is zero, no change occurs.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("hello world");
+ * s.trimPrefix(6);
+ * // Result: "world"
+ *
+ * s.trimPrefix(500); // exceeds length
+ * // Result: "" (empty)
+ * }</pre>
+ *
+ * @param cutAmount the number of characters to remove from the beginning.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 trimPrefix(final int cutAmount) {
+
+ int actualCutAmount = cutAmount;
+
+ if (actualCutAmount > getLength())
+ actualCutAmount = getLength();
+
+ if (actualCutAmount > 0) chars.subList(0, actualCutAmount).clear();
+
+ return this;
+ }
+
+ /**
+ * Removes the specified prefix if this string starts with it.
+ *
+ * <p>If the string does not have the given prefix, no change occurs.
+ * If the prefix is null, no change occurs.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("prefix_content");
+ * s.trimPrefixIfExists("prefix_");
+ * // Result: "content"
+ *
+ * s.trimPrefixIfExists("nonexistent");
+ * // Result: "content" (unchanged)
+ * }</pre>
+ *
+ * @param prefix the prefix to remove if present. May be null (no effect).
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 trimPrefixIfExists(String prefix) {
+ if (prefix == null)
+ return this;
+
+ if (hasPrefix(prefix))
+ trimPrefix(prefix.length());
+
+ return this;
+ }
+
+ /**
+ * Removes the specified suffix if this string ends with it.
+ *
+ * <p>If the string does not have the given suffix, no change occurs.</p>
+ *
+ * <p><strong>Note:</strong> This method may throw an exception if the
+ * suffix is longer than the string. Use carefully with potentially
+ * long suffix strings.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("content_suffix");
+ * s.trimSuffixIfExists("_suffix");
+ * // Result: "content"
+ * }</pre>
+ *
+ * @param suffix the suffix to remove if present. Must not be null
+ * and must not be longer than the string.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 trimSuffixIfExists(String suffix) {
+ if (hasSuffix(suffix))
+ trimSuffix(suffix.length());
+
+ return this;
+ }
+
+ /**
+ * Removes the specified number of characters from the end of this string.
+ *
+ * <p>If charsToTrim exceeds the string length, the entire string is cleared.
+ * If charsToTrim is zero, no change occurs.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("hello world");
+ * s.trimSuffix(6);
+ * // Result: "hello"
+ *
+ * s.trimSuffix(500); // exceeds length
+ * // Result: "" (empty)
+ * }</pre>
+ *
+ * @param charsToTrim the number of characters to remove from the end.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 trimSuffix(int charsToTrim) {
+
+ if (charsToTrim > chars.size()) {
+ chars.clear();
+ return this;
+ }
+
+ for (int i = 0; i < charsToTrim; i++)
+ chars.remove(chars.size() - 1);
+
+ return this;
+ }
+
+ /**
+ * Checks if this string ends with the specified suffix.
+ *
+ * <p><strong>Note:</strong> This method may throw an exception if the
+ * suffix is longer than the string. Ensure the suffix length is
+ * appropriate before calling.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("filename.txt");
+ * s.hasSuffix(".txt"); // true
+ * s.hasSuffix("txt"); // true
+ * }</pre>
+ *
+ * @param suffix the suffix to check for. Must not be null and must
+ * not be longer than the string.
+ * @return {@code true} if this string ends with the suffix,
+ * {@code false} otherwise.
+ */
+ public boolean hasSuffix(String suffix) {
+ return contains(suffix, getLength() - suffix.length());
+ }
+
+ /**
+ * Checks if this string starts with the specified prefix.
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("Hello, world");
+ * s.hasPrefix("Hello"); // true
+ * s.hasPrefix("hello"); // false (case-sensitive)
+ * }</pre>
+ *
+ * @param prefix the prefix to check for. Must not be null.
+ * @return {@code true} if this string starts with the prefix,
+ * {@code false} otherwise.
+ */
+ public boolean hasPrefix(String prefix) {
+ return contains(prefix, 0);
+ }
+
+ /**
+ * Checks if a fragment appears at the specified position in this string.
+ *
+ * <p>This is a substring check starting at the given index. The fragment
+ * must match exactly (case-sensitive) at that position.</p>
+ *
+ * <p>If the position plus fragment length exceeds the string length,
+ * {@code false} is returned.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("hello world");
+ * s.contains("hello", 0); // true
+ * s.contains("world", 6); // true
+ * s.contains("lo wo", 3); // true
+ * s.contains("hello", 1); // false
+ * }</pre>
+ *
+ * @param fragment the text to check for. Must not be null.
+ * @param index the starting position to check from (0-based).
+ * @return {@code true} if the fragment appears at that position,
+ * {@code false} otherwise.
+ */
+ public boolean contains(String fragment, int index) {
+ if (index + fragment.length() > chars.size())
+ return false;
+
+ for (int i = 0; i < fragment.length(); i++)
+ if (chars.get(index + i) != fragment.charAt(i))
+ return false;
+
+ return true;
+ }
+
+ /**
+ * Adjusts this string to have exactly the specified length.
+ *
+ * <p>If the string is longer than the target, excess characters are
+ * removed from the end. If the string is shorter, spaces are added
+ * at the end. If the length already matches, no change occurs.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("12345678");
+ * s.enforceLength(5);
+ * // Result: "12345"
+ *
+ * s.enforceLength(8);
+ * // Result: "12345 " (3 spaces added)
+ * }</pre>
+ *
+ * <p>This is useful for creating fixed-width columns or formatting
+ * text for tabular output.</p>
+ *
+ * @param targetLength the exact length to enforce.
+ * @return this String2 instance for fluent method chaining.
+ */
+ public String2 enforceLength(final int targetLength) {
+ if (getLength() > targetLength)
+ chars.subList(targetLength, getLength()).clear();
+ else if (getLength() < targetLength) {
+ final int charactersToAdd = targetLength - getLength();
+ for (int i = 0; i < charactersToAdd; i++)
+ chars.add(' ');
+ }
+
+ return this;
+ }
+
+ /**
+ * Returns the current length of this string.
+ *
+ * @return the number of characters in this string.
+ */
+ public int getLength() {
+ return chars.size();
+ }
+
+ /**
+ * Returns a substring of this string.
+ *
+ * <p>The substring includes characters from startInclusive to
+ * endExclusive (exclusive end). This follows the standard Java
+ * substring convention.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String2 s = new String2("hello world");
+ * s.getSubString(0, 5); // "hello"
+ * s.getSubString(6, 11); // "world"
+ * }</pre>
+ *
+ * @param startInclusive the starting index (inclusive, 0-based).
+ * @param endExclusive the ending index (exclusive). Must be greater
+ * than or equal to startInclusive.
+ * @return the substring as a new String object.
+ */
+ public String getSubString(final int startInclusive, final int endExclusive) {
+ final char[] charArray = new char[endExclusive - startInclusive];
+
+ int j = 0;
+ for (int i = startInclusive; i < endExclusive; i++) {
+ charArray[j] = chars.get(i);
+ j++;
+ }
+ return new String(charArray);
+ }
+
+ /**
+ * Checks if this string is empty.
+ *
+ * @return {@code true} if this string has zero length,
+ * {@code false} otherwise.
+ */
+ public boolean isEmpty() {
+ return chars.size() == 0;
+ }
+
+ /**
+ * Returns the string content as a standard Java String.
+ *
+ * <p>This creates a new String object containing all characters
+ * currently in this String2.</p>
+ *
+ * @return the complete string content as a String.
+ */
+ @Override
+ public String toString() {
+ return getSubString(0, chars.size());
+ }
+
+
+ /**
+ * Extracts regex capture groups from a string.
+ *
+ * <p>This static utility method applies a regular expression to a
+ * string and returns all capture groups as an array.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * String[] groups = String2.getGroups(
+ * "name: John, age: 25",
+ * "name: (\\w+), age: (\\d+)");
+ * // groups[0] = "John"
+ * // groups[1] = "25"
+ * }</pre>
+ *
+ * <p><strong>Note:</strong> The regex must match the string, otherwise
+ * this method will throw an exception. The returned array contains
+ * only capture groups (group 1 onwards), not the entire match.</p>
+ *
+ * @param s the string to search. Must not be null.
+ * @param regexp the regular expression with capture groups.
+ * Must not be null and must match the string.
+ * @return an array of captured group strings. Length equals the
+ * number of capture groups in the regexp.
+ */
+ public static String[] getGroups(String s, String regexp){
+ Pattern pattern = Pattern.compile(regexp);
+ Matcher matcher = pattern.matcher(s);
+
+ matcher.find();
+ String[] result = new String[matcher.groupCount()];
+
+ for (int i = 0; i< result.length; i++){
+ result[i] = matcher.group(i+1);
+ }
+
+ return result;
+ }
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+
+/**
+ * Provides utility classes for string manipulation and pattern matching.
+ *
+ * <p>This package contains classes for advanced string operations:</p>
+ *
+ * <ul>
+ * <li>{@link eu.svjatoslav.commons.string.String2} - A mutable string builder optimized
+ * for prefix/suffix operations, with fluent API for easy chaining</li>
+ * <li>{@link eu.svjatoslav.commons.string.GlobMatcher} - Match strings against wildcard
+ * patterns using {@code *} (any characters) and {@code ?} (single character)</li>
+ * </ul>
+ *
+ * <p>The {@link eu.svjatoslav.commons.string.String2} class provides a more intuitive
+ * alternative to {@link java.lang.StringBuilder} for operations involving prefixes
+ * and suffixes, with methods like {@code trimPrefix()}, {@code trimSuffix()},
+ * {@code prepend()}, and {@code appendWithSeparator()}.</p>
+ *
+ * <p>The {@link eu.svjatoslav.commons.string.GlobMatcher} implements glob-style pattern
+ * matching similar to shell wildcards, useful for file name filtering and simple
+ * pattern matching without regular expressions.</p>
+ *
+ * @author Svjatoslav Agejenko
+ * @since 1.0
+ * @see eu.svjatoslav.commons.string.String2
+ * @see eu.svjatoslav.commons.string.GlobMatcher
+ */
+package eu.svjatoslav.commons.string;
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+/**
+ * Exception thrown when token parsing encounters unexpected content.
+ *
+ * <p>This exception is thrown by the tokenizer when expectations fail,
+ * such as:</p>
+ *
+ * <ul>
+ * <li>{@link Tokenizer#expectAndConsumeNextStringToken(String)} - when
+ * the next token doesn't match the expected value</li>
+ * <li>{@link Tokenizer#expectAndConsumeNextTerminatorToken(Terminator)} -
+ * when the next token was matched by a different terminator</li>
+ * <li>{@link Tokenizer#peekExpectNoneOf(String...)} - when the next
+ * token matches a forbidden value</li>
+ * </ul>
+ *
+ * <p>Example handling:</p>
+ * <pre>{@code
+ * try {
+ * tokenizer.expectAndConsumeNextStringToken("if");
+ * // Parse if statement...
+ * } catch (InvalidSyntaxException e) {
+ * System.err.println("Syntax error: " + e.getMessage());
+ * // Error recovery or abort
+ * }
+ * }</pre>
+ *
+ * <p>The exception message describes what was expected and what was
+ * actually encountered, useful for error reporting to users.</p>
+ *
+ * @see Tokenizer
+ */
+public class InvalidSyntaxException extends Exception {
+
+ /**
+ * Serial version UID for serialization compatibility.
+ */
+ private static final long serialVersionUID = 88294980027680555L;
+
+ /**
+ * Creates a new InvalidSyntaxException with a descriptive message.
+ *
+ * <p>The message should describe what was expected and what was found,
+ * to help users understand the syntax error.</p>
+ *
+ * @param cause a description of the syntax error. Must not be null.
+ */
+ public InvalidSyntaxException(final String cause) {
+ super(cause);
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Defines a token boundary using a regular expression pattern.
+ *
+ * <p>A Terminator specifies how to identify and handle token boundaries
+ * in the tokenizer. Each terminator has:</p>
+ *
+ * <ul>
+ * <li>A regex pattern to match at the current position</li>
+ * <li>A termination strategy (PRESERVE or DROP)</li>
+ * <li>An optional group name for categorizing matched tokens</li>
+ * <li>An active flag that can disable the terminator temporarily</li>
+ * </ul>
+ *
+ * <p>Termination strategies:</p>
+ * <ul>
+ * <li>{@link TerminationStrategy#PRESERVE PRESERVE} - The matched text is returned
+ * as a token. Use this for tokens you want to process (keywords, operators, etc.)</li>
+ * <li>{@link TerminationStrategy#DROP DROP} - The matched text is discarded silently.
+ * Use this for separators you don't need (whitespace, comments, etc.)</li>
+ * </ul>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * // Drop whitespace (don't return it as a token)
+ * Terminator whitespace = tokenizer.addTerminator(DROP, "\\s+");
+ *
+ * // Preserve quoted strings (return them as tokens)
+ * Terminator strings = tokenizer.addTerminator(PRESERVE, "\".*?\"", "string");
+ *
+ * // Preserve numbers with a group name
+ * Terminator numbers = tokenizer.addTerminator(PRESERVE, "\\d+", "number");
+ *
+ * // Temporarily disable a terminator
+ * whitespace.active = false; // Now whitespace will be returned as tokens
+ * whitespace.active = true; // Back to dropping whitespace
+ * }</pre>
+ *
+ * <p>Patterns are anchored to match only at the current position (the "^"
+ * anchor is prepended automatically).</p>
+ *
+ * @see Tokenizer
+ * @see TokenizerMatch
+ */
+public class Terminator {
+
+ /**
+ * The regular expression pattern that identifies this token boundary.
+ *
+ * <p>This is stored for reference (used in toString). The actual pattern
+ * used for matching is stored in {@link #pattern} with "^" prepended.</p>
+ */
+ String regexp;
+
+ /**
+ * The strategy for handling matched tokens.
+ *
+ * <p>Determines whether matched text is returned as a token (PRESERVE)
+ * or silently discarded (DROP).</p>
+ *
+ * @see TerminationStrategy
+ */
+ public final TerminationStrategy termination;
+
+ /**
+ * An optional group name for categorizing this token type.
+ *
+ * <p>When set, matched tokens can be identified by this group name
+ * using {@link TokenizerMatch#isGroup(String)}.</p>
+ *
+ * <p>May be null for uncategorized tokens.</p>
+ */
+ public final String group;
+
+ /**
+ * Flag indicating whether this terminator is active.
+ *
+ * <p>When false, this terminator is skipped during matching. Set this
+ * to temporarily disable a terminator without removing it.</p>
+ *
+ * <p>Default value is {@code true}.</p>
+ */
+ public boolean active = true;
+
+ /**
+ * The compiled regex pattern used for matching.
+ *
+ * <p>This is the regexp with "^" prepended to anchor it at the start.
+ * The pattern is compiled once for efficiency.</p>
+ */
+ public final Pattern pattern;
+
+ /**
+ * Creates a new terminator with the specified configuration.
+ *
+ * <p>The regex pattern is anchored with "^" to match only at the
+ * current position in the source string.</p>
+ *
+ * @param termination how to handle matched tokens (PRESERVE or DROP).
+ * @param regexp the regex pattern to match tokens. Must not be null.
+ * @param group the group name for categorizing this token type.
+ * May be null.
+ */
+ public Terminator(TerminationStrategy termination, String regexp, String group) {
+ this.termination = termination;
+ this.group = group;
+ this.regexp = regexp;
+ this.pattern = Pattern.compile("^"+regexp);
+ }
+
+ /**
+ * Creates a matcher for this terminator at the specified position.
+ *
+ * <p>The matcher is configured to search from the given index to the
+ * end of the source string, ensuring matches only occur at that
+ * exact position (due to the "^" anchor in the pattern).</p>
+ *
+ * @param source the source string to match against. Must not be null.
+ * @param index the starting position for matching.
+ * @return a Matcher configured to search from index to the end.
+ */
+ public Matcher match(String source, int index) {
+ Matcher matcher = pattern.matcher(source);
+ matcher.region(index, source.length());
+ return matcher;
+ }
+
+ /**
+ * Returns a string representation of this terminator.
+ *
+ * <p>Includes the regexp, termination strategy, group name, and active status.</p>
+ *
+ * @return a descriptive string for debugging.
+ */
+ @Override
+ public String toString() {
+ return "Terminator{" +
+ "regexp='" + regexp + '\'' +
+ ", termination=" + termination +
+ ", group='" + group + '\'' +
+ ", active=" + active +
+ '}';
+ }
+
+ /**
+ * Defines how matched tokens are handled by the tokenizer.
+ */
+ public enum TerminationStrategy {
+ /**
+ * Preserve the matched token and return it for processing.
+ *
+ * <p>Use this for tokens you want to capture and handle in your
+ * parsing logic, such as keywords, operators, literals, or
+ * other syntax elements.</p>
+ *
+ * <p>Example use cases:</p>
+ * <ul>
+ * <li>Keywords: "if", "else", "while"</li>
+ * <li>Operators: "+", "-", "==", "<"</li>
+ * <li>Literals: numbers, quoted strings</li>
+ * <li>Delimiters: parentheses, brackets</li>
+ * </ul>
+ */
+ PRESERVE,
+
+ /**
+ * Drop the matched token silently without returning it.
+ *
+ * <p>Use this for tokens that act as separators or noise that
+ * you don't need to process, such as whitespace or comments.</p>
+ *
+ * <p>Example use cases:</p>
+ * <ul>
+ * <li>Whitespace: spaces, tabs, newlines</li>
+ * <li>Comments: "// ...", "/* ... */"</li>
+ * <li>Optional separators that don't affect parsing</li>
+ * </ul>
+ *
+ * <p>Dropped tokens still separate other tokens - they're just
+ * not returned by getNextToken().</p>
+ */
+ DROP
+ }
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Stack;
+import java.util.regex.Matcher;
+import java.util.stream.Stream;
+
+import static eu.svjatoslav.commons.string.tokenizer.Terminator.TerminationStrategy.PRESERVE;
+import static java.lang.System.out;
+
+/**
+ * A regex-based tokenizer for parsing structured text into tokens.
+ *
+ * <p>The Tokenizer breaks down source text into tokens based on regular
+ * expression patterns called "terminators". Terminators define how to
+ * identify and handle token boundaries:</p>
+ *
+ * <ul>
+ * <li>{@link Terminator.TerminationStrategy#PRESERVE PRESERVE} - Return matched
+ * tokens for processing (useful for syntax elements you want to capture)</li>
+ * <li>{@link Terminator.TerminationStrategy#DROP DROP} - Silently discard matched
+ * tokens (useful for whitespace, comments, or other separators)</li>
+ * </ul>
+ *
+ * <p>Key features:</p>
+ * <ul>
+ * <li>Pattern-based token identification using regex</li>
+ * <li>Peek ahead without consuming tokens</li>
+ * <li>Unread tokens to backtrack</li>
+ * <li>Expect specific tokens (throws on mismatch)</li>
+ * <li>Group-based token categorization</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * Tokenizer tokenizer = new Tokenizer("hello, world! 123");
+ * tokenizer.addTerminator(DROP, "\\s+"); // Drop whitespace
+ * tokenizer.addTerminator(PRESERVE, "\\w+"); // Preserve words
+ * tokenizer.addTerminator(PRESERVE, ","); // Preserve comma
+ * tokenizer.addTerminator(PRESERVE, "!"); // Preserve exclamation
+ * tokenizer.addTerminator(PRESERVE, "\\d+"); // Preserve numbers
+ *
+ * while (tokenizer.hasMoreContent()) {
+ * TokenizerMatch match = tokenizer.getNextToken();
+ * System.out.println(match.token);
+ * }
+ * // Output: hello, world, !, 123
+ * }</pre>
+ *
+ * <p>The tokenizer maintains a history stack, allowing you to unread
+ * tokens and backtrack during parsing:</p>
+ * <pre>{@code
+ * TokenizerMatch first = tokenizer.getNextToken();
+ * TokenizerMatch second = tokenizer.getNextToken();
+ * tokenizer.unreadToken(); // Go back one token
+ * tokenizer.unreadToken(); // Go back another token
+ * TokenizerMatch again = tokenizer.getNextToken(); // Same as first
+ * }</pre>
+ *
+ * <p>You can also peek without consuming:</p>
+ * <pre>{@code
+ * TokenizerMatch peeked = tokenizer.peekNextToken(); // Look ahead
+ * TokenizerMatch actual = tokenizer.getNextToken(); // Same as peeked
+ * }</pre>
+ *
+ * @see Terminator
+ * @see TokenizerMatch
+ * @see InvalidSyntaxException
+ */
+public class Tokenizer {
+
+ /**
+ * Stack of token indexes for backtracking.
+ *
+ * <p>Each time a token is consumed, the current index is pushed onto
+ * this stack. Calling {@link #unreadToken()} pops the stack and
+ * restores the previous position, allowing the same token to be
+ * read again.</p>
+ */
+ private final Stack<Integer> tokenIndexes = new Stack<>();
+
+ /**
+ * List of terminators that define token boundaries.
+ *
+ * <p>Terminators are checked in order during tokenization. When a
+ * terminator matches at the current position, it determines how
+ * the match is handled (preserved or dropped).</p>
+ */
+ private final List<Terminator> terminators = new ArrayList<>();
+
+ /**
+ * The source string being tokenized.
+ *
+ * <p>This is the text that will be broken down into tokens. Can be
+ * null initially and set later via {@link #setSource(String)}.</p>
+ */
+ private String source;
+
+ /**
+ * Current reading position within the source string.
+ *
+ * <p>This index advances as tokens are consumed. It starts at 0
+ * and moves forward through the source string.</p>
+ */
+ private int currentIndex = 0;
+
+ /**
+ * Creates a new tokenizer for the specified source string.
+ *
+ * <p>The source string will be processed when {@link #getNextToken()}
+ * is called. Add terminators before calling getNextToken() to
+ * define how tokens should be identified.</p>
+ *
+ * @param source the text to tokenize. May be null (use setSource later).
+ */
+ public Tokenizer(final String source) {
+ this.source = source;
+ }
+
+ /**
+ * Creates an empty tokenizer without a source string.
+ *
+ * <p>Use {@link #setSource(String)} to provide text for tokenization
+ * before calling {@link #getNextToken()}.</p>
+ */
+ public Tokenizer() {
+ }
+
+ /**
+ * Sets or replaces the source string to tokenize.
+ *
+ * <p>This resets the tokenizer state: the reading position is set to 0,
+ * and the token history stack is cleared. Use this to tokenize a new
+ * string with the same terminator configuration.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * Tokenizer tokenizer = new Tokenizer();
+ * tokenizer.addTerminator(DROP, "\\s+");
+ *
+ * tokenizer.setSource("first string");
+ * // tokenize first string...
+ *
+ * tokenizer.setSource("second string");
+ * // tokenize second string with same rules...
+ * }</pre>
+ *
+ * @param source the new text to tokenize. May be null.
+ * @return this Tokenizer instance for fluent method chaining.
+ */
+ public Tokenizer setSource(String source) {
+ this.source = source;
+ currentIndex = 0;
+ tokenIndexes.clear();
+ return this;
+ }
+
+ /**
+ * Adds a terminator with a termination strategy and regex pattern.
+ *
+ * <p>The terminator will match tokens based on the regex pattern.
+ * The termination strategy determines whether matched tokens are
+ * preserved (returned) or dropped (silently discarded).</p>
+ *
+ * <p>The pattern is anchored to match only at the current position
+ * (prepended with "^").</p>
+ *
+ * @param terminationStrategy how to handle matched tokens
+ * (PRESERVE or DROP).
+ * @param regexp the regex pattern to match tokens.
+ * @return the created Terminator object, which can be further configured
+ * (e.g., setting the active flag or group).
+ */
+ public Terminator addTerminator(final Terminator.TerminationStrategy terminationStrategy, String regexp) {
+ Terminator terminator = new Terminator(terminationStrategy, regexp,null);
+ terminators.add(terminator);
+ return terminator;
+ }
+
+ /**
+ * Adds a terminator with a termination strategy, regex pattern, and group name.
+ *
+ * <p>The group name allows categorizing tokens by type, which can be
+ * checked using {@link TokenizerMatch#isGroup(String)}.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * tokenizer.addTerminator(PRESERVE, "\\d+", "number");
+ * tokenizer.addTerminator(PRESERVE, "\\w+", "word");
+ *
+ * TokenizerMatch match = tokenizer.getNextToken();
+ * if (match.isGroup("number")) {
+ * // Handle number token...
+ * }
+ * }</pre>
+ *
+ * @param terminationStrategy how to handle matched tokens
+ * (PRESERVE or DROP).
+ * @param regexp the regex pattern to match tokens.
+ * @param group the group name for categorizing this token type.
+ * May be null.
+ * @return the created Terminator object.
+ */
+ public Terminator addTerminator(final Terminator.TerminationStrategy terminationStrategy,
+ String regexp, String group) {
+ Terminator terminator = new Terminator(terminationStrategy, regexp,group);
+ terminators.add(terminator);
+ return terminator;
+ }
+
+
+ /**
+ * Adds a pre-configured terminator to this tokenizer.
+ *
+ * <p>Use this when you need to create a Terminator with custom
+ * configuration before adding it.</p>
+ *
+ * @param terminator the terminator to add. Must not be null.
+ * @return the same terminator that was added.
+ */
+ public Terminator addTerminator(Terminator terminator) {
+ terminators.add(terminator);
+ return terminator;
+ }
+
+ /**
+ * Consumes the next token and verifies it matches the expected value.
+ *
+ * <p>This is a convenience method for parsing where you expect a
+ * specific token at a specific position. If the token doesn't match,
+ * an exception is thrown.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * tokenizer.expectAndConsumeNextStringToken("if");
+ * // Consumes "if" token, throws if next token is not "if"
+ * }</pre>
+ *
+ * @param value the expected token value. Must not be null.
+ * @throws InvalidSyntaxException if the next token does not match
+ * the expected value.
+ */
+ public void expectAndConsumeNextStringToken(final String value)
+ throws InvalidSyntaxException {
+ final TokenizerMatch match = getNextToken();
+ if (!value.equals(match.token))
+ throw new InvalidSyntaxException("Expected \"" + value
+ + "\" but got \"" + match.token + "\" instead.");
+ }
+
+ /**
+ * Consumes the next token and verifies it was matched by the expected terminator.
+ *
+ * <p>This is useful when you need to ensure a specific terminator matched
+ * the token, not just that the token has a certain value.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * Terminator stringTerminator = tokenizer.addTerminator(PRESERVE, "\".*\"");
+ * tokenizer.expectAndConsumeNextTerminatorToken(stringTerminator);
+ * }</pre>
+ *
+ * @param terminator the expected terminator that should have matched.
+ * @return the TokenizerMatch containing the matched token.
+ * @throws InvalidSyntaxException if the next token was matched by
+ * a different terminator.
+ */
+ public TokenizerMatch expectAndConsumeNextTerminatorToken(Terminator terminator)
+ throws InvalidSyntaxException {
+ final TokenizerMatch match = getNextToken();
+
+ if (match.terminator != terminator)
+ throw new InvalidSyntaxException("Expected terminator \"" + terminator
+ + "\" but got \"" + match.terminator + "\" instead.");
+
+ return match;
+ }
+
+
+ /**
+ * Returns the next token from the source string.
+ *
+ * <p>This method advances the reading position. The token is identified
+ * based on the configured terminators:</p>
+ * <ul>
+ * <li>If a PRESERVE terminator matches, that matched text is returned</li>
+ * <li>If a DROP terminator matches, it is discarded and the next token is sought</li>
+ * <li>If no terminator matches, characters accumulate until a terminator matches</li>
+ * </ul>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * TokenizerMatch match = tokenizer.getNextToken();
+ * if (match != null) {
+ * System.out.println(match.token);
+ * }
+ * }</pre>
+ *
+ * @return the next TokenizerMatch, or {@code null} if the end of the
+ * source string is reached.
+ */
+ public TokenizerMatch getNextToken() {
+ tokenIndexes.push(currentIndex);
+
+ StringBuilder tokenAccumulator = new StringBuilder();
+
+ while (true) {
+
+ if (currentIndex >= source.length()) { // reached end of input
+ if (hasAccumulatedToken(tokenAccumulator))
+ return new TokenizerMatch(tokenAccumulator.toString(), null, null, this);
+ else
+ return null;
+ }
+
+ TokenizerMatch matchResult = findTerminatorMatch();
+ if (matchResult == null) {
+ tokenAccumulator.append(source.charAt(currentIndex));
+ currentIndex++;
+ continue;
+ }
+
+ if (matchResult.terminator.termination == PRESERVE) {
+ if (hasAccumulatedToken(tokenAccumulator))
+ return new TokenizerMatch(tokenAccumulator.toString(), null, null, this);
+
+ currentIndex = matchResult.matcher.end();
+ return matchResult;
+ } else {
+ currentIndex = matchResult.matcher.end();
+
+ if (hasAccumulatedToken(tokenAccumulator))
+ return new TokenizerMatch(tokenAccumulator.toString(), null, null, this);
+ }
+ }
+ }
+
+ /**
+ * Finds a terminator that matches at the current position.
+ *
+ * <p>This checks all active terminators (in order) to see if any
+ * matches at the current index. The first matching terminator
+ * is returned.</p>
+ *
+ * <p>Terminators with {@code active = false} are skipped.</p>
+ *
+ * @return a TokenizerMatch if a terminator matches, or {@code null}
+ * if no terminator matches at the current position.
+ */
+ public TokenizerMatch findTerminatorMatch(){
+ for (Terminator terminator : terminators)
+ if (terminator.active) {
+ Matcher match = terminator.match(source, currentIndex);
+ if (match.find()) {
+ String token = source.substring(match.start(), match.end());
+ return new TokenizerMatch(token, terminator, match, this);
+ }
+ }
+ return null;
+ }
+
+ /**
+ * Checks if the token accumulator has any content.
+ *
+ * <p>This is used internally to determine if accumulated characters
+ * should be returned as a token.</p>
+ *
+ * @param tokenAccumulator the StringBuilder containing accumulated characters.
+ * @return {@code true} if there are accumulated characters, {@code false} otherwise.
+ */
+ private boolean hasAccumulatedToken(StringBuilder tokenAccumulator) {
+ return tokenAccumulator.length() > 0;
+ }
+
+ /**
+ * Checks if there is more content to read.
+ *
+ * <p>Returns true if the current position is before the end of the
+ * source string. Note that even if this returns true, getNextToken()
+ * might return null if remaining content is dropped by terminators.</p>
+ *
+ * @return {@code true} if there is more content, {@code false} if at
+ * the end of source or source is null.
+ */
+ public boolean hasMoreContent() {
+ if (source == null) return false;
+ return currentIndex < source.length();
+ }
+
+ /**
+ * Consumes the next token if it matches the expected value.
+ *
+ * <p>If the next token matches, it is consumed and {@code true} is returned.
+ * If it doesn't match, the token is unread and {@code false} is returned.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * if (tokenizer.consumeIfNextToken("else")) {
+ * // Handle else clause
+ * } else {
+ * // Token was not "else", position unchanged
+ * }
+ * }</pre>
+ *
+ * @param token the expected token value. Must not be null.
+ * @return {@code true} if the next token matched and was consumed,
+ * {@code false} otherwise (position unchanged).
+ * @throws InvalidSyntaxException if parsing fails.
+ */
+ public boolean consumeIfNextToken(final String token) throws InvalidSyntaxException {
+ if (token.equals(getNextToken().token))
+ return true;
+
+ unreadToken();
+ return false;
+ }
+
+ /**
+ * Returns the next token without consuming it.
+ *
+ * <p>This looks ahead at the next token and returns it, then immediately
+ * unread to restore the position. Use this to examine what's coming
+ * without advancing.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * TokenizerMatch peeked = tokenizer.peekNextToken();
+ * System.out.println("Next will be: " + peeked.token);
+ * TokenizerMatch actual = tokenizer.getNextToken(); // Same as peeked
+ * }</pre>
+ *
+ * @return the next TokenizerMatch without advancing the position.
+ * @throws InvalidSyntaxException if parsing fails.
+ */
+ public TokenizerMatch peekNextToken() throws InvalidSyntaxException {
+ TokenizerMatch result = getNextToken();
+ unreadToken();
+ return result;
+ }
+
+ /**
+ * Checks if the next token is one of the specified possibilities.
+ *
+ * <p>This peeks at the next token and checks if its value equals any
+ * of the given strings. The position is unchanged after this call.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * if (tokenizer.peekIsOneOf("if", "else", "while")) {
+ * // Next token is a control keyword
+ * }
+ * }</pre>
+ *
+ * @param possibilities the token values to check against.
+ * Must not be null or empty.
+ * @return {@code true} if the next token matches one of the possibilities,
+ * {@code false} otherwise.
+ * @throws InvalidSyntaxException if parsing fails.
+ */
+ public boolean peekIsOneOf(String... possibilities) throws InvalidSyntaxException {
+ String nextToken = peekNextToken().token;
+ return Stream.of(possibilities).anyMatch(possibility -> possibility.equals(nextToken));
+ }
+
+ /**
+ * Verifies the next token is NOT one of the specified possibilities.
+ *
+ * <p>If the next token matches any possibility, an exception is thrown.
+ * Use this for negative assertions in parsing.</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * tokenizer.peekExpectNoneOf("}", "end");
+ * // Throws if next token is } or end
+ * }</pre>
+ *
+ * @param possibilities the token values that should NOT appear next.
+ * @throws InvalidSyntaxException if the next token matches any possibility.
+ */
+ public void peekExpectNoneOf(String... possibilities) throws InvalidSyntaxException {
+ if (peekIsOneOf(possibilities))
+ throw new InvalidSyntaxException("Not expected \"" + peekNextToken().token + "\" here.");
+ }
+
+ /**
+ * Unreads the most recently consumed token.
+ *
+ * <p>This restores the reading position to before the last token was
+ * read. The token can be read again with getNextToken().</p>
+ *
+ * <p>You can unread multiple times to backtrack further:</p>
+ * <pre>{@code
+ * TokenizerMatch first = tokenizer.getNextToken();
+ * TokenizerMatch second = tokenizer.getNextToken();
+ * TokenizerMatch third = tokenizer.getNextToken();
+ *
+ * tokenizer.unreadToken(); // Back to after second
+ * tokenizer.unreadToken(); // Back to after first
+ *
+ * TokenizerMatch again = tokenizer.getNextToken(); // Same as second
+ * }</pre>
+ */
+ public void unreadToken() {
+ currentIndex = tokenIndexes.pop();
+ }
+
+ /**
+ * Prints all remaining tokens for debugging purposes.
+ *
+ * <p>This reads and prints all remaining tokens without permanently
+ * consuming them. After printing, the position is restored to the
+ * original location.</p>
+ *
+ * <p>Output is printed to stdout with each token on a new line.</p>
+ */
+ public void enlistRemainingTokens(){
+ int redTokenCount = 0;
+
+ while (hasMoreContent()) {
+ out.println(getNextToken().toString());
+ redTokenCount++;
+ }
+
+ // restore pointer to original location
+ for (int i = 0; i< redTokenCount; i++ ) unreadToken();
+ }
+
+
+ /**
+ * Skips to the end of the source string without consuming tokens.
+ *
+ * <p>This advances directly to the end, skipping all remaining content.
+ * After calling this, {@link #hasMoreContent()} will return {@code false}.</p>
+ *
+ * <p>The current position is saved on the stack, so you can unread
+ * to restore it if needed.</p>
+ */
+ public void skipUntilDataEnd() {
+ tokenIndexes.push(currentIndex);
+ currentIndex = source.length();
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+import java.util.regex.Matcher;
+
+/**
+ * Represents a matched token from the tokenizer.
+ *
+ * <p>TokenizerMatch contains all information about a token that was
+ * extracted from the source string:</p>
+ *
+ * <ul>
+ * <li>{@link #token} - The actual text content of the token</li>
+ * <li>{@link #terminator} - The Terminator that identified this token</li>
+ * <li>{@link #matcher} - The regex Matcher used for matching</li>
+ * </ul>
+ *
+ * <p>Key methods:</p>
+ * <ul>
+ * <li>{@link #isGroup(String)} - Check if this token belongs to a specific group</li>
+ * <li>{@link #getRegExpGroups()} - Extract regex capture groups from the match</li>
+ * <li>{@link #getTokenizer()} - Get the tokenizer that produced this match</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * TokenizerMatch match = tokenizer.getNextToken();
+ *
+ * System.out.println("Token: " + match.token);
+ *
+ * if (match.isGroup("number")) {
+ * int value = Integer.parseInt(match.token);
+ * }
+ *
+ * if (match.isGroup("string")) {
+ * String[] groups = match.getRegExpGroups();
+ * // groups[0] might be the string content without quotes
+ * }
+ * }</pre>
+ *
+ * <p>For tokens that were accumulated text (not matched by a terminator),
+ * the terminator and matcher fields will be null.</p>
+ *
+ * @see Tokenizer
+ * @see Terminator
+ */
+public class TokenizerMatch {
+
+ /**
+ * The text content of the matched token.
+ *
+ * <p>This is the actual substring from the source that was identified
+ * as a token. For accumulated text (no terminator match), this contains
+ * all characters accumulated before a terminator was found.</p>
+ */
+ public final String token;
+
+ /**
+ * The Terminator that identified this token.
+ *
+ * <p>May be null if this token was accumulated text rather than
+ * matched by a terminator. When not null, you can check the
+ * terminator's group to categorize the token.</p>
+ */
+ public final Terminator terminator;
+
+ /**
+ * The regex Matcher used to identify this token.
+ *
+ * <p>May be null if this token was accumulated text. When not null,
+ * you can use this to extract capture groups from the match.</p>
+ */
+ public final Matcher matcher;
+
+ /**
+ * The tokenizer that produced this match.
+ *
+ * <p>This is used internally for backtracking. Can also be useful
+ * to continue tokenization from within token handling code.</p>
+ */
+ private Tokenizer tokenizer;
+
+ /**
+ * Creates a new TokenizerMatch with all components.
+ *
+ * @param token the matched text. May be empty but should not be null.
+ * @param terminator the Terminator that matched this token. May be null
+ * for accumulated text tokens.
+ * @param matcher the regex Matcher used for matching. May be null for
+ * accumulated text tokens.
+ * @param tokenizer the Tokenizer that produced this match.
+ */
+ public TokenizerMatch(final String token, final Terminator terminator, Matcher matcher, Tokenizer tokenizer) {
+ this.token = token;
+ this.terminator = terminator;
+ this.matcher = matcher;
+ this.tokenizer = tokenizer;
+ }
+
+ /**
+ * Checks if this token belongs to the specified group.
+ *
+ * <p>This compares the group name of the terminator against the
+ * provided group name. Useful for categorizing tokens by type.</p>
+ *
+ * <p>Special cases:</p>
+ * <ul>
+ * <li>If terminator is null, returns true only if group is also null</li>
+ * <li>If terminator.group is null, returns true only if group is null</li>
+ * </ul>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * tokenizer.addTerminator(PRESERVE, "\\d+", "number");
+ * tokenizer.addTerminator(PRESERVE, "\\w+", "word");
+ *
+ * TokenizerMatch match = tokenizer.getNextToken();
+ * if (match.isGroup("number")) {
+ * // Token is a number
+ * } else if (match.isGroup("word")) {
+ * // Token is a word
+ * }
+ * }</pre>
+ *
+ * @param group the group name to check against. May be null.
+ * @return {@code true} if this token belongs to the specified group,
+ * {@code false} otherwise.
+ */
+ public boolean isGroup(String group){
+ if (terminator == null){
+ return group == null;
+ }
+
+ if (terminator.group == null){
+ return group == null;
+ }
+
+ return terminator.group.equals(group);
+ }
+
+ /**
+ * Extracts regex capture groups from this match.
+ *
+ * <p>Returns the captured groups from the regex pattern that matched
+ * this token. Group 1 and onwards are returned (not the full match).</p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * tokenizer.addTerminator(PRESERVE, "(\\d+):(\\d+)", "time");
+ * // Matches "12:30"
+ *
+ * TokenizerMatch match = tokenizer.getNextToken();
+ * String[] groups = match.getRegExpGroups();
+ * // groups[0] = "12" (hours)
+ * // groups[1] = "30" (minutes)
+ * }</pre>
+ *
+ * @return an array of captured group strings. Empty array if matcher
+ * is null or no capture groups exist in the pattern.
+ */
+ public String[] getRegExpGroups(){
+ if (matcher == null) return new String[]{};
+
+ String[] result = new String[matcher.groupCount()];
+
+ for (int i = 0; i< result.length; i++){
+ result[i] = matcher.group(i+1);
+ }
+
+ return result;
+ }
+
+ /**
+ * Returns a detailed string representation for debugging.
+ *
+ * <p>Includes the token text, terminator details, and any regex groups.</p>
+ *
+ * @return a multi-line descriptive string.
+ */
+ @Override
+ public String toString() {
+ StringBuilder result = new StringBuilder();
+ result.append("TokenizerMatch\n" +
+ " token='" + token + "'\n" +
+ " terminator=" + terminator + "\n" +
+ " groups:\n");
+
+ int i = 0;
+ for (String s : getRegExpGroups()) {
+ result.append(" " + i + ": " + s + "\n");
+ i++;
+ }
+
+ return result.toString();
+ }
+
+ /**
+ * Returns the tokenizer that produced this match.
+ *
+ * <p>This allows continuing tokenization or accessing tokenizer
+ * state from within token handling code.</p>
+ *
+ * @return the Tokenizer instance that created this match.
+ */
+ public Tokenizer getTokenizer() {
+ return tokenizer;
+ }
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+
+/**
+ * Provides a regex-based tokenizer for parsing structured text.
+ *
+ * <p>This package contains a flexible tokenizer system for breaking down
+ * text into tokens based on regular expression patterns:</p>
+ *
+ * <ul>
+ * <li>{@link eu.svjatoslav.commons.string.tokenizer.Tokenizer} - Main tokenizer class
+ * that processes source text and extracts tokens</li>
+ * <li>{@link eu.svjatoslav.commons.string.tokenizer.Terminator} - Defines token boundaries
+ * using regex patterns with configurable handling strategies</li>
+ * <li>{@link eu.svjatoslav.commons.string.tokenizer.TokenizerMatch} - Result object
+ * containing matched token and metadata</li>
+ * <li>{@link eu.svjatoslav.commons.string.tokenizer.InvalidSyntaxException} - Exception
+ * thrown when parsing fails</li>
+ * </ul>
+ *
+ * <p>The tokenizer supports two termination strategies:</p>
+ * <ul>
+ * <li>{@code PRESERVE} - Return matched tokens for processing</li>
+ * <li>{@code DROP} - Silently drop matched tokens (useful for whitespace/comments)</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * Tokenizer tokenizer = new Tokenizer("hello, world!");
+ * tokenizer.addTerminator(DROP, "\\s+"); // Drop whitespace
+ * tokenizer.addTerminator(PRESERVE, ","); // Preserve commas
+ * while (tokenizer.hasMoreContent()) {
+ * TokenizerMatch match = tokenizer.getNextToken();
+ * System.out.println(match.token);
+ * }
+ * }</pre>
+ *
+ * @author Svjatoslav Agejenko
+ * @since 1.0
+ * @see eu.svjatoslav.commons.string.tokenizer.Tokenizer
+ * @see eu.svjatoslav.commons.string.tokenizer.Terminator
+ * @see eu.svjatoslav.commons.string.tokenizer.TokenizerMatch
+ */
+package eu.svjatoslav.commons.string.tokenizer;
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.data;
+
+import org.junit.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+
+import static org.junit.Assert.assertEquals;
+
+public class BitInputStreamTest {
+
+ @Test
+ public void testReadSingleBit() throws IOException {
+ byte[] data = {(byte) 0b10000000};
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(data));
+
+ assertEquals(1, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ assertEquals(0, bis.readBits(1));
+ }
+
+ @Test
+ public void testReadMultipleBits() throws IOException {
+ byte[] data = {(byte) 0b11110000, (byte) 0b00001111};
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(data));
+
+ assertEquals(0b1111, bis.readBits(4));
+ assertEquals(0b0000, bis.readBits(4));
+ assertEquals(0b0000, bis.readBits(4));
+ assertEquals(0b1111, bis.readBits(4));
+ }
+
+ @Test
+ public void testReadAcrossByteBoundary() throws IOException {
+ byte[] data = {(byte) 0b11001100, (byte) 0b10101010};
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(data));
+
+ assertEquals(0b11001, bis.readBits(5));
+ assertEquals(0b1001010, bis.readBits(7));
+ assertEquals(0b1010, bis.readBits(4));
+ }
+
+ @Test
+ public void testReadFullByte() throws IOException {
+ byte[] data = {(byte) 0xFF, (byte) 0xAB, (byte) 0x00};
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(data));
+
+ assertEquals(0xFF, bis.readBits(8));
+ assertEquals(0xAB, bis.readBits(8));
+ assertEquals(0x00, bis.readBits(8));
+ }
+
+ @Test
+ public void testReadZeroBits() throws IOException {
+ byte[] data = {(byte) 0xFF};
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(data));
+
+ assertEquals(0, bis.readBits(0));
+ assertEquals(0xFF, bis.readBits(8));
+ }
+
+ @Test
+ public void testReadVariedBitWidths() throws IOException {
+ byte[] data = {(byte) 0b10101010, (byte) 0b11001100};
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(data));
+
+ assertEquals(0b101, bis.readBits(3));
+ assertEquals(0b010, bis.readBits(3));
+ assertEquals(0b1011, bis.readBits(4));
+ assertEquals(0b001100, bis.readBits(6));
+ }
+
+ @Test
+ public void testRoundTripWithBitOutputStream() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0xFF, 8);
+ bos.storeBits(0xAB, 8);
+ bos.storeBits(0x00, 8);
+ bos.finishByte();
+
+ byte[] written = baos.toByteArray();
+ BitInputStream bis = new BitInputStream(new ByteArrayInputStream(written));
+
+ assertEquals(0xFF, bis.readBits(8));
+ assertEquals(0xAB, bis.readBits(8));
+ assertEquals(0x00, bis.readBits(8));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.data;
+
+import org.junit.Test;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+
+public class BitOutputStreamTest {
+
+ @Test
+ public void testWriteSingleBits() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(1, 1);
+ bos.storeBits(0, 1);
+ bos.storeBits(0, 1);
+ bos.storeBits(0, 1);
+ bos.storeBits(0, 1);
+ bos.storeBits(0, 1);
+ bos.storeBits(0, 1);
+ bos.storeBits(0, 1);
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(1, result.length);
+ assertEquals((byte) 0b10000000, result[0]);
+ }
+
+ @Test
+ public void testWriteFullByte() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0xFF, 8);
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(1, result.length);
+ assertEquals((byte) 0xFF, result[0]);
+ }
+
+ @Test
+ public void testWriteAcrossByteBoundary() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0b11001, 5);
+ bos.storeBits(0b100, 3);
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(1, result.length);
+ assertEquals((byte) 0b11001100, result[0]);
+ }
+
+ @Test
+ public void testWriteMultipleBytes() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0b11110000, 8);
+ bos.storeBits(0b00001111, 8);
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(2, result.length);
+ assertEquals((byte) 0b11110000, result[0]);
+ assertEquals((byte) 0b00001111, result[1]);
+ }
+
+ @Test
+ public void testWriteZeroBits() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0xFF, 8);
+ bos.storeBits(0, 0);
+ bos.storeBits(0xAB, 8);
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(2, result.length);
+ assertEquals((byte) 0xFF, result[0]);
+ assertEquals((byte) 0xAB, result[1]);
+ }
+
+ @Test
+ public void testFinishByteWithPartialByte() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0b101, 3);
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(1, result.length);
+ assertEquals(5, result[0]);
+ }
+
+ @Test
+ public void testFinishByteTwice() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0b101, 3);
+ bos.finishByte();
+ bos.finishByte();
+
+ byte[] result = baos.toByteArray();
+ assertEquals(1, result.length);
+ }
+
+ @Test
+ public void testWriteVariedBitWidths() throws IOException {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ BitOutputStream bos = new BitOutputStream(baos);
+
+ bos.storeBits(0b101, 3);
+ bos.storeBits(0b010, 3);
+ bos.storeBits(0b1011, 4);
+ bos.storeBits(0b001100, 6);
+ bos.finishByte();
+
+ byte[] expected = {(byte) 0b10101010, (byte) 0b11001100};
+ byte[] result = baos.toByteArray();
+ assertArrayEquals(expected, result);
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.data;
+
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+public class HexConverterTest {
+
+ @Test
+ public void testBasicConversion() {
+ final String result = HexConverter.byteArrayToHex(new byte[]{1, 2, (byte) 255});
+ assertEquals("0102FF", result);
+ }
+
+ @Test
+ public void testEmptyArray() {
+ final String result = HexConverter.byteArrayToHex(new byte[]{});
+ assertEquals("", result);
+ }
+
+ @Test
+ public void testNullArray() {
+ final String result = HexConverter.byteArrayToHex(null);
+ assertNull(result);
+ }
+
+ @Test
+ public void testSingleByte() {
+ assertEquals("00", HexConverter.byteArrayToHex(new byte[]{0}));
+ assertEquals("0F", HexConverter.byteArrayToHex(new byte[]{15}));
+ assertEquals("FF", HexConverter.byteArrayToHex(new byte[]{(byte) 255}));
+ }
+
+ @Test
+ public void testAllZeros() {
+ final byte[] zeros = new byte[5];
+ assertEquals("0000000000", HexConverter.byteArrayToHex(zeros));
+ }
+
+ @Test
+ public void testAllOnes() {
+ final byte[] ones = new byte[3];
+ for (int i = 0; i < ones.length; i++) ones[i] = (byte) 0xFF;
+ assertEquals("FFFFFF", HexConverter.byteArrayToHex(ones));
+ }
+
+ @Test
+ public void testMixedValues() {
+ final byte[] data = {0x0A, 0x1B, 0x2C, 0x3D, 0x4E, 0x5F};
+ assertEquals("0A1B2C3D4E5F", HexConverter.byteArrayToHex(data));
+ }
+
+ @Test
+ public void testNegativeBytes() {
+ final byte[] data = {(byte) -1, (byte) -128, (byte) -2};
+ assertEquals("FF80FE", HexConverter.byteArrayToHex(data));
+ }
+
+ @Test
+ public void testUpperCaseOutput() {
+ final byte[] data = {0x0a, 0x1b, 0x2c};
+ final String result = HexConverter.byteArrayToHex(data);
+ assertTrue(result.equals(result.toUpperCase()));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.file;
+
+import org.junit.Test;
+
+import java.io.File;
+
+import static org.junit.Assert.assertEquals;
+
+public class FilePathParserTest {
+
+ @Test
+ public void testGetFileExtension() {
+ assertEquals("txt", FilePathParser.getFileExtension("document.txt"));
+ assertEquals("jpg", FilePathParser.getFileExtension("image.JPG"));
+ assertEquals("gz", FilePathParser.getFileExtension("archive.tar.gz"));
+ assertEquals("", FilePathParser.getFileExtension("noextension"));
+ assertEquals("", FilePathParser.getFileExtension(""));
+ }
+
+ @Test
+ public void testGetFileExtensionWithFile() {
+ File file = new File("test/document.pdf");
+ assertEquals("pdf", FilePathParser.getFileExtension(file));
+
+ File noExtFile = new File("test/README");
+ assertEquals("", FilePathParser.getFileExtension(noExtFile));
+ }
+
+ @Test
+ public void testGetFileExtensionCaseInsensitive() {
+ assertEquals("jpg", FilePathParser.getFileExtension("photo.JPG"));
+ assertEquals("png", FilePathParser.getFileExtension("image.PNG"));
+ assertEquals("pdf", FilePathParser.getFileExtension("document.PDF"));
+ }
+
+ @Test
+ public void testGetFileNameWithoutExtension() {
+ assertEquals("document", FilePathParser.getFileNameWithoutExtension("document.txt"));
+ assertEquals("archive.tar", FilePathParser.getFileNameWithoutExtension("archive.tar.gz"));
+ assertEquals("noextension", FilePathParser.getFileNameWithoutExtension("noextension"));
+ assertEquals("", FilePathParser.getFileNameWithoutExtension(""));
+ assertEquals("file", FilePathParser.getFileNameWithoutExtension("file."));
+ }
+
+ @Test
+ public void testGetFileNameWithoutExtensionWithFile() {
+ File file = new File("path/to/document.pdf");
+ assertEquals("document", FilePathParser.getFileNameWithoutExtension(file));
+
+ File noExtFile = new File("path/to/README");
+ assertEquals("README", FilePathParser.getFileNameWithoutExtension(noExtFile));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionBytes() {
+ assertEquals("0 b", FilePathParser.getFileSizeDescription(0));
+ assertEquals("100 b", FilePathParser.getFileSizeDescription(100));
+ assertEquals("1023 b", FilePathParser.getFileSizeDescription(1023));
+ assertEquals("1024 b", FilePathParser.getFileSizeDescription(1024));
+ assertEquals("5119 b", FilePathParser.getFileSizeDescription(5119));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionKibibytes() {
+ assertEquals("5 KiB", FilePathParser.getFileSizeDescription(5 * 1024));
+ assertEquals("10 KiB", FilePathParser.getFileSizeDescription(10 * 1024));
+ assertEquals("1024 KiB", FilePathParser.getFileSizeDescription(1024 * 1024));
+ assertEquals("5 MiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionMebibytes() {
+ assertEquals("5 MiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 + 1));
+ assertEquals("10 MiB", FilePathParser.getFileSizeDescription(10L * 1024 * 1024));
+ assertEquals("1024 MiB", FilePathParser.getFileSizeDescription(1024L * 1024 * 1024));
+ assertEquals("5 GiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionGibibytes() {
+ assertEquals("5 GiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024 + 1));
+ assertEquals("10 GiB", FilePathParser.getFileSizeDescription(10L * 1024 * 1024 * 1024));
+ assertEquals("1024 GiB", FilePathParser.getFileSizeDescription(1024L * 1024 * 1024 * 1024));
+ assertEquals("5 TiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024 * 1024));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionTebibytes() {
+ assertEquals("5 TiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024 * 1024 + 1));
+ assertEquals("10 TiB", FilePathParser.getFileSizeDescription(10L * 1024 * 1024 * 1024 * 1024));
+ assertEquals("1024 TiB", FilePathParser.getFileSizeDescription(1024L * 1024 * 1024 * 1024 * 1024));
+ assertEquals("5 PiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024 * 1024 * 1024));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionPebibytes() {
+ assertEquals("5 PiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024 * 1024 * 1024));
+ assertEquals("10 PiB", FilePathParser.getFileSizeDescription(10L * 1024 * 1024 * 1024 * 1024 * 1024));
+ }
+
+ @Test
+ public void testGetFileSizeDescriptionBoundary() {
+ assertEquals("5119 b", FilePathParser.getFileSizeDescription(5119));
+ assertEquals("5 KiB", FilePathParser.getFileSizeDescription(5120));
+ assertEquals("4999 KiB", FilePathParser.getFileSizeDescription(4999 * 1024));
+ assertEquals("5 MiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024));
+ assertEquals("4999 MiB", FilePathParser.getFileSizeDescription(4999L * 1024 * 1024));
+ assertEquals("5 GiB", FilePathParser.getFileSizeDescription(5L * 1024 * 1024 * 1024));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.file;
+
+import org.junit.After;
+import org.junit.Test;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+
+import static org.junit.Assert.*;
+
+public class IOHelperTest {
+
+ private static final String UTF_8 = "UTF-8";
+
+ private final File testDir = new File("testDir");
+ private final File testFile = new File("testFile.txt");
+
+ @After
+ public void cleanup() throws IOException {
+ if (testFile.exists()) testFile.delete();
+ if (testDir.exists()) IOHelper.deleteRecursively(testDir);
+ }
+
+ @Test
+ public void testOverwriteFileIfContentDiffers() throws IOException {
+ assertTrue(IOHelper.overwriteFileIfContentDiffers(testFile, "aoa".getBytes(UTF_8)));
+ assertFalse(IOHelper.overwriteFileIfContentDiffers(testFile, "aoa".getBytes(UTF_8)));
+ assertTrue(IOHelper.overwriteFileIfContentDiffers(testFile, "1234".getBytes(UTF_8)));
+ }
+
+ @Test
+ public void testSaveAndReadBytes() throws IOException {
+ final byte[] content = "hello world".getBytes(UTF_8);
+ IOHelper.saveToFile(testFile, content);
+
+ final byte[] readContent = IOHelper.getFileContents(testFile);
+ assertArrayEquals(content, readContent);
+ }
+
+ @Test
+ public void testSaveAndReadString() throws IOException {
+ final String content = "hello world";
+ IOHelper.saveToFile(testFile, content);
+
+ final String readContent = IOHelper.getFileContentsAsString(testFile);
+ assertEquals(content, readContent);
+ }
+
+ @Test
+ public void testGetFileContentsEmptyFile() throws IOException {
+ IOHelper.saveToFile(testFile, "");
+ final String content = IOHelper.getFileContentsAsString(testFile);
+ assertEquals("", content);
+ }
+
+ @Test
+ public void testDeleteRecursivelyFile() throws IOException {
+ IOHelper.saveToFile(testFile, "test");
+ assertTrue(testFile.exists());
+ IOHelper.deleteRecursively(testFile);
+ assertFalse(testFile.exists());
+ }
+
+ @Test
+ public void testDeleteRecursivelyDirectory() throws IOException {
+ testDir.mkdirs();
+ final File subDir = new File(testDir, "subdir");
+ subDir.mkdirs();
+ IOHelper.saveToFile(new File(testDir, "file1.txt"), "content1");
+ IOHelper.saveToFile(new File(subDir, "file2.txt"), "content2");
+
+ assertTrue(testDir.exists());
+ assertTrue(subDir.exists());
+
+ IOHelper.deleteRecursively(testDir);
+ assertFalse(testDir.exists());
+ }
+
+ @Test
+ public void testDeleteRecursivelyEmptyDirectory() throws IOException {
+ testDir.mkdirs();
+ assertTrue(testDir.exists());
+ IOHelper.deleteRecursively(testDir);
+ assertFalse(testDir.exists());
+ }
+
+ @Test
+ public void testDeleteNonExistentFile() throws IOException {
+ final File nonExistent = new File("nonexistent_" + System.currentTimeMillis());
+ IOHelper.deleteRecursively(nonExistent);
+ assertFalse(nonExistent.exists());
+ }
+
+ @Test
+ public void testOverwriteIdenticalContentLengthButDifferent() throws IOException {
+ final byte[] content1 = "abcd".getBytes(UTF_8);
+ final byte[] content2 = "dcba".getBytes(UTF_8);
+
+ IOHelper.saveToFile(testFile, content1);
+ assertTrue(IOHelper.overwriteFileIfContentDiffers(testFile, content2));
+ }
+
+ @Test
+ public void testOverwriteExistingFileDifferentLength() throws IOException {
+ IOHelper.saveToFile(testFile, "short");
+ assertTrue(IOHelper.overwriteFileIfContentDiffers(testFile, "longer content".getBytes(UTF_8)));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string;
+
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+public class GlobMatcherTest {
+
+ @Test
+ public void testStarWildcard() {
+ assertTrue(GlobMatcher.match("IMG_9770.JPG", "*.J*"));
+ assertTrue(GlobMatcher.match("1", "*"));
+ assertTrue(GlobMatcher.match("Hello !", "Hell*!***"));
+ assertTrue(GlobMatcher.match("Hello !", "Hell*!"));
+ assertTrue(GlobMatcher.match("Hello !", "Hell*"));
+ assertTrue(GlobMatcher.match("Hello !", "* *"));
+ assertFalse(GlobMatcher.match("Hello !", "Hell"));
+ }
+
+ @Test
+ public void testQuestionWildcard() {
+ assertTrue(GlobMatcher.match("cat", "c?t"));
+ assertTrue(GlobMatcher.match("bat", "?at"));
+ assertTrue(GlobMatcher.match("cat", "ca?"));
+ assertFalse(GlobMatcher.match("cart", "c?t"));
+ assertFalse(GlobMatcher.match("at", "?at"));
+ }
+
+ @Test
+ public void testMultipleQuestionWildcards() {
+ assertTrue(GlobMatcher.match("test", "t??t"));
+ assertTrue(GlobMatcher.match("abcd", "????"));
+ assertFalse(GlobMatcher.match("abc", "????"));
+ assertFalse(GlobMatcher.match("abcde", "????"));
+ }
+
+ @Test
+ public void testMixedWildcards() {
+ assertTrue(GlobMatcher.match("document.txt", "*.???"));
+ assertTrue(GlobMatcher.match("file123.txt", "file*.???"));
+ assertTrue(GlobMatcher.match("test123", "test?*"));
+ assertTrue(GlobMatcher.match("a1b2c3", "?*?*?*"));
+ assertFalse(GlobMatcher.match("ab", "?*?*?*"));
+ }
+
+ @Test
+ public void testExactMatch() {
+ assertTrue(GlobMatcher.match("1", "1"));
+ assertTrue(GlobMatcher.match("test", "test"));
+ assertFalse(GlobMatcher.match("f", "1"));
+ assertFalse(GlobMatcher.match("test", "Test"));
+ }
+
+ @Test
+ public void testEmptyStrings() {
+ assertTrue(GlobMatcher.match("", ""));
+ assertTrue(GlobMatcher.match("", "*"));
+ assertFalse(GlobMatcher.match("", "?"));
+ assertFalse(GlobMatcher.match("test", ""));
+ }
+
+ @Test
+ public void testNullInputs() {
+ assertFalse(GlobMatcher.match(null, "*"));
+ assertFalse(GlobMatcher.match("test", null));
+ assertFalse(GlobMatcher.match(null, null));
+ }
+
+ @Test
+ public void testOnlyStars() {
+ assertTrue(GlobMatcher.match("anything", "***"));
+ assertTrue(GlobMatcher.match("", "***"));
+ assertTrue(GlobMatcher.match("x", "***"));
+ }
+
+ @Test
+ public void testStarAtEnd() {
+ assertTrue(GlobMatcher.match("filename.txt", "filename*"));
+ assertTrue(GlobMatcher.match("filename", "filename*"));
+ assertTrue(GlobMatcher.match("filename_xyz", "filename*"));
+ }
+
+ @Test
+ public void testStarAtBeginning() {
+ assertTrue(GlobMatcher.match(".txt", "*.txt"));
+ assertTrue(GlobMatcher.match("file.txt", "*.txt"));
+ assertTrue(GlobMatcher.match("anything.txt", "*.txt"));
+ assertFalse(GlobMatcher.match("anything.pdf", "*.txt"));
+ }
+
+ @Test
+ public void testQuestionAtBeginning() {
+ assertTrue(GlobMatcher.match("a.txt", "?*.txt"));
+ assertTrue(GlobMatcher.match("x", "?"));
+ assertFalse(GlobMatcher.match("", "?"));
+ }
+
+ @Test
+ public void testComplexPatterns() {
+ assertTrue(GlobMatcher.match("IMG_9770.JPG", "IMG_*.JPG"));
+ assertTrue(GlobMatcher.match("photo_2023.png", "photo_*.???"));
+ assertTrue(GlobMatcher.match("test_file_v1.java", "test_*_v?.java"));
+ assertFalse(GlobMatcher.match("test_file_v12.java", "test_*_v?.java"));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string;
+
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+public class String2Test {
+
+ @Test
+ public void testTrimPrefix() {
+ final String2 s = new String2("this is a test");
+
+ assertEquals("is a test", s.trimPrefix(5).toString());
+ assertEquals("a test", s.trimPrefix(3).toString());
+ assertEquals("test", s.trimPrefix(2).toString());
+ assertEquals("", s.trimPrefix(500).toString());
+ }
+
+ @Test
+ public void testTrimPrefixZero() {
+ final String2 s = new String2("test");
+ s.trimPrefix(0);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testTrimPrefixIfExists() {
+ final String2 s = new String2("prefix_content");
+ s.trimPrefixIfExists("prefix_");
+ assertEquals("content", s.toString());
+
+ s.trimPrefixIfExists("nonexistent");
+ assertEquals("content", s.toString());
+ }
+
+ @Test
+ public void testTrimPrefixIfExistsNull() {
+ final String2 s = new String2("test");
+ s.trimPrefixIfExists(null);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testTrimSuffix() {
+ final String2 s = new String2("this is a test");
+
+ assertEquals("this is a", s.trimSuffix(5).toString());
+ assertEquals("this is", s.trimSuffix(2).toString());
+ assertEquals("this", s.trimSuffix(3).toString());
+ assertEquals("", s.trimSuffix(500).toString());
+ }
+
+ @Test
+ public void testTrimSuffixZero() {
+ final String2 s = new String2("test");
+ s.trimSuffix(0);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testTrimSuffixIfExists() {
+ final String2 s = new String2("content_suffix");
+ s.trimSuffixIfExists("_suffix");
+ assertEquals("content", s.toString());
+
+ s.trimSuffixIfExists("ent");
+ assertEquals("cont", s.toString());
+ }
+
+ @Test
+ public void testEnforceLength() {
+ final String2 s = new String2("12345678");
+ s.enforceLength(3);
+ assertEquals("123", s.toString());
+
+ s.enforceLength(5);
+ assertEquals("123 ", s.toString());
+ }
+
+ @Test
+ public void testEnforceLengthExact() {
+ final String2 s = new String2("test");
+ s.enforceLength(4);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testSuffixAndPrefix() {
+ final String2 s = new String2("experiment");
+ s.prepend("The ").append(" !");
+
+ assertEquals("The experiment !", s.toString());
+ }
+
+ @Test
+ public void testPrependNull() {
+ final String2 s = new String2("test");
+ s.prepend(null);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testAppendNull() {
+ final String2 s = new String2("test");
+ s.append(null);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testConstructorNull() {
+ final String2 s = new String2((String) null);
+ assertEquals("", s.toString());
+ }
+
+ @Test
+ public void testRepeat() {
+ final String2 s = new String2("ab");
+ s.repeat(3);
+ assertEquals("ababab", s.toString());
+ }
+
+ @Test
+ public void testRepeatOnce() {
+ final String2 s = new String2("test");
+ s.repeat(1);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testRepeatZero() {
+ final String2 s = new String2("test");
+ s.repeat(0);
+ assertEquals("", s.toString());
+ }
+
+ @Test
+ public void testRepeatNegative() {
+ final String2 s = new String2("test");
+ s.repeat(-5);
+ assertEquals("", s.toString());
+ }
+
+ @Test
+ public void testAppendWithSeparator() {
+ final String2 s = new String2("a");
+ s.appendWithSeparator(",", "b");
+ assertEquals("a,b", s.toString());
+
+ s.appendWithSeparator(",", "c");
+ assertEquals("a,b,c", s.toString());
+ }
+
+ @Test
+ public void testAppendWithSeparatorEmptyString() {
+ final String2 s = new String2();
+ s.appendWithSeparator(",", "first");
+ assertEquals("first", s.toString());
+ }
+
+ @Test
+ public void testAppendMultipleTimes() {
+ final String2 s = new String2();
+ s.append("x", 3);
+ assertEquals("xxx", s.toString());
+ }
+
+ @Test
+ public void testAppendMultipleTimesZero() {
+ final String2 s = new String2("test");
+ s.append("x", 0);
+ assertEquals("test", s.toString());
+ }
+
+ @Test
+ public void testHasPrefix() {
+ final String2 s = new String2("prefix_content");
+ assertTrue(s.hasPrefix("prefix_"));
+ assertTrue(s.hasPrefix("prefix"));
+ assertFalse(s.hasPrefix("content"));
+ }
+
+ @Test
+ public void testHasPrefixLongerThanString() {
+ final String2 s = new String2("short");
+ assertFalse(s.hasPrefix("very_long_prefix"));
+ }
+
+ @Test
+ public void testHasSuffix() {
+ final String2 s = new String2("content_suffix");
+ assertTrue(s.hasSuffix("_suffix"));
+ assertTrue(s.hasSuffix("suffix"));
+ assertFalse(s.hasSuffix("other"));
+ }
+
+ @Test
+ public void testContains() {
+ final String2 s = new String2("hello world");
+ assertTrue(s.contains("hello", 0));
+ assertTrue(s.contains("world", 6));
+ assertTrue(s.contains("lo wo", 3));
+ assertFalse(s.contains("hello", 1));
+ assertFalse(s.contains("xyz", 0));
+ }
+
+ @Test
+ public void testIsEmpty() {
+ assertTrue(new String2().isEmpty());
+ assertTrue(new String2("").isEmpty());
+ assertFalse(new String2("test").isEmpty());
+ }
+
+ @Test
+ public void testGetLength() {
+ assertEquals(0, new String2().getLength());
+ assertEquals(0, new String2("").getLength());
+ assertEquals(4, new String2("test").getLength());
+ }
+
+ @Test
+ public void testGetSubString() {
+ final String2 s = new String2("hello world");
+ assertEquals("hello", s.getSubString(0, 5));
+ assertEquals("world", s.getSubString(6, 11));
+ assertEquals("lo wo", s.getSubString(3, 8));
+ assertEquals("", s.getSubString(5, 5));
+ }
+
+ @Test
+ public void testClear() {
+ final String2 s = new String2("test");
+ s.clear();
+ assertEquals("", s.toString());
+ assertTrue(s.isEmpty());
+ }
+
+ @Test
+ public void testGetGroups() {
+ String[] groups = String2.getGroups("abc 123 def", "(\\w+)\\s+(\\w+)\\s+(\\w+)");
+ assertEquals(3, groups.length);
+ assertEquals("abc", groups[0]);
+ assertEquals("123", groups[1]);
+ assertEquals("def", groups[2]);
+ }
+
+ @Test
+ public void testFluentChaining() {
+ final String2 s = new String2()
+ .append("hello")
+ .appendWithSeparator(" ", "world")
+ .prepend("Say: ")
+ .append("!");
+
+ assertEquals("Say: hello world!", s.toString());
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+public class TerminatorTest {
+
+ @Test
+ public void testMatches() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "/\\*.+\\*/",
+ "test");
+
+ assertTrue(terminator.match("/* bla bla bla */", 0).find());
+ assertFalse(terminator.match("/* bla bla bla */", 1).find());
+ assertFalse(terminator.match("/", 0).find());
+ }
+
+ @Test
+ public void testTerminationStrategyPreserve() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "\\d+",
+ null);
+
+ assertEquals(Terminator.TerminationStrategy.PRESERVE, terminator.termination);
+ }
+
+ @Test
+ public void testTerminationStrategyDrop() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.DROP,
+ "\\s+",
+ null);
+
+ assertEquals(Terminator.TerminationStrategy.DROP, terminator.termination);
+ }
+
+ @Test
+ public void testGroupProperty() {
+ Terminator withGroup = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "\\d+",
+ "number");
+
+ assertEquals("number", withGroup.group);
+
+ Terminator withoutGroup = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "\\d+",
+ null);
+
+ assertNull(withoutGroup.group);
+ }
+
+ @Test
+ public void testActiveFlag() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "\\d+",
+ null);
+
+ assertTrue(terminator.active);
+
+ terminator.active = false;
+ assertFalse(terminator.active);
+ }
+
+ @Test
+ public void testToString() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "\\d+",
+ "number");
+
+ terminator.active = true;
+
+ String str = terminator.toString();
+ assertTrue(str.contains("\\d+"));
+ assertTrue(str.contains("PRESERVE"));
+ assertTrue(str.contains("number"));
+ assertTrue(str.contains("true"));
+ }
+
+ @Test
+ public void testMatchAtDifferentPositions() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "abc",
+ null);
+
+ assertTrue(terminator.match("abc", 0).find());
+ assertTrue(terminator.match("xyzabc", 3).find());
+ assertFalse(terminator.match("xyzabc", 0).find());
+ assertFalse(terminator.match("xyzabc", 4).find());
+ }
+
+ @Test
+ public void testMatchWithComplexPattern() {
+ Terminator terminator = new Terminator(
+ Terminator.TerminationStrategy.PRESERVE,
+ "\\d{4}-\\d{2}-\\d{2}",
+ "date");
+
+ assertTrue(terminator.match("2023-01-15", 0).find());
+ assertTrue(terminator.match("date: 2023-01-15", 6).find());
+ assertFalse(terminator.match("2023", 0).find());
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+import org.junit.Test;
+
+import static eu.svjatoslav.commons.string.tokenizer.Terminator.TerminationStrategy.DROP;
+import static eu.svjatoslav.commons.string.tokenizer.Terminator.TerminationStrategy.PRESERVE;
+import static org.junit.Assert.*;
+
+public class TokenizerMatchTest {
+
+ @Test
+ public void testIsGroupWithNoTerminator() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertNull(match.terminator);
+ assertTrue(match.isGroup(null));
+ assertFalse(match.isGroup("someGroup"));
+ }
+
+ @Test
+ public void testIsGroupWithTerminatorNoGroup() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("'hello'");
+ tokenizer.addTerminator(PRESERVE, "'[^']*'");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertNotNull(match.terminator);
+ assertNull(match.terminator.group);
+ assertTrue(match.isGroup(null));
+ assertFalse(match.isGroup("string"));
+ }
+
+ @Test
+ public void testIsGroupWithTerminatorWithGroup() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("'hello'");
+ tokenizer.addTerminator(PRESERVE, "'[^']*'", "string");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertNotNull(match.terminator);
+ assertEquals("string", match.terminator.group);
+ assertTrue(match.isGroup("string"));
+ assertFalse(match.isGroup("number"));
+ assertFalse(match.isGroup(null));
+ }
+
+ @Test
+ public void testGetRegExpGroupsWithNoMatcher() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("hello");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertNull(match.matcher);
+ String[] groups = match.getRegExpGroups();
+ assertNotNull(groups);
+ assertEquals(0, groups.length);
+ }
+
+ @Test
+ public void testGetRegExpGroupsWithGroups() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("123 abc");
+ tokenizer.addTerminator(PRESERVE, "(\\d+)\\s+(\\w+)");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertNotNull(match.matcher);
+
+ String[] groups = match.getRegExpGroups();
+ assertNotNull(groups);
+ assertEquals(2, groups.length);
+ assertEquals("123", groups[0]);
+ assertEquals("abc", groups[1]);
+ }
+
+ @Test
+ public void testGetRegExpGroupsWithNoGroups() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("hello");
+ tokenizer.addTerminator(PRESERVE, "\\w+");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertNotNull(match.matcher);
+
+ String[] groups = match.getRegExpGroups();
+ assertNotNull(groups);
+ assertEquals(0, groups.length);
+ }
+
+ @Test
+ public void testGetTokenizer() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("hello");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertSame(tokenizer, match.getTokenizer());
+ }
+
+ @Test
+ public void testTokenField() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ assertEquals("hello", match.token);
+ }
+
+ @Test
+ public void testToString() throws InvalidSyntaxException {
+ Tokenizer tokenizer = new Tokenizer("(abc)");
+ tokenizer.addTerminator(PRESERVE, "\\(([^)]+)\\)");
+
+ TokenizerMatch match = tokenizer.getNextToken();
+ assertNotNull(match);
+ String str = match.toString();
+ assertTrue(str.contains("(abc)"));
+ }
+
+}
\ No newline at end of file
--- /dev/null
+/*
+ * Svjatoslav Commons - shared library of common functionality. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.commons.string.tokenizer;
+
+import org.junit.Test;
+
+import static eu.svjatoslav.commons.string.tokenizer.Terminator.TerminationStrategy.DROP;
+import static eu.svjatoslav.commons.string.tokenizer.Terminator.TerminationStrategy.PRESERVE;
+import static org.junit.Assert.*;
+
+public class TokenizerTest {
+
+ @Test
+ public void testPeeking() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("this is a N'2015-03-18 09:48:54.360' test");
+ tokenizer.addTerminator(DROP, "\\s");
+ tokenizer.addTerminator(PRESERVE, "N'.*'");
+
+ tokenizer.expectAndConsumeNextStringToken("this");
+
+ assertEquals("is", tokenizer.peekNextToken().token);
+ assertEquals("is", tokenizer.peekNextToken().token);
+
+ assertTrue(tokenizer.peekIsOneOf("maybe", "is", "that"));
+ }
+
+ @Test
+ public void testTokenization() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("\"hello world\" /** comment **/ (( is a N'2015-03-18 09:48:54.360' test");
+ tokenizer.addTerminator(DROP, "\\s");
+ tokenizer.addTerminator(PRESERVE, "\\(");
+ tokenizer.addTerminator(PRESERVE, "\\\".*\\\"");
+ tokenizer.addTerminator(PRESERVE, "N'.*'");
+ tokenizer.addTerminator(DROP, "/\\*.*\\*/");
+
+ assertTokenEquals("\"hello world\"", tokenizer);
+ assertTokenEquals("(", tokenizer);
+ assertTokenEquals("(", tokenizer);
+ assertTokenEquals("is", tokenizer);
+ assertTokenEquals("a", tokenizer);
+ assertTokenEquals("N'2015-03-18 09:48:54.360'", tokenizer);
+ assertTokenEquals("test", tokenizer);
+
+ assertNull(tokenizer.getNextToken());
+ assertFalse(tokenizer.hasMoreContent());
+ }
+
+ @Test
+ public void testMultilineTokenization() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("* heading\r\nnormal text\r\nnormal text 2");
+ tokenizer.addTerminator(PRESERVE, "\\*[ \\t]+.*\\r?\\n");
+ tokenizer.addTerminator(DROP, "\\r?\\n", "normalText");
+
+ assertTokenEquals("* heading\r\n", tokenizer);
+ assertTokenEquals("normal text", tokenizer);
+ assertTokenEquals("normal text 2", tokenizer);
+
+ assertNull(tokenizer.getNextToken());
+ assertFalse(tokenizer.hasMoreContent());
+ }
+
+ @Test
+ public void testConsumeIfNextTokenMatch() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertTrue(tokenizer.consumeIfNextToken("hello"));
+ assertFalse(tokenizer.consumeIfNextToken("hello"));
+ assertTrue(tokenizer.consumeIfNextToken("world"));
+ assertFalse(tokenizer.hasMoreContent());
+ }
+
+ @Test
+ public void testConsumeIfNextTokenNoMatch() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertFalse(tokenizer.consumeIfNextToken("wrong"));
+ assertEquals("hello", tokenizer.getNextToken().token);
+ }
+
+ @Test
+ public void testUnreadToken() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("a b c");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertEquals("a", tokenizer.getNextToken().token);
+ assertEquals("b", tokenizer.getNextToken().token);
+ tokenizer.unreadToken();
+ assertEquals("b", tokenizer.getNextToken().token);
+ tokenizer.unreadToken();
+ tokenizer.unreadToken();
+ assertEquals("a", tokenizer.getNextToken().token);
+ }
+
+ @Test
+ public void testSetSourceReset() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("first");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertEquals("first", tokenizer.getNextToken().token);
+ assertFalse(tokenizer.hasMoreContent());
+
+ tokenizer.setSource("second source");
+ assertTrue(tokenizer.hasMoreContent());
+ assertEquals("second", tokenizer.getNextToken().token);
+ assertEquals("source", tokenizer.getNextToken().token);
+ }
+
+ @Test
+ public void testEmptySource() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertFalse(tokenizer.hasMoreContent());
+ assertNull(tokenizer.getNextToken());
+ }
+
+ @Test
+ public void testNullSource() {
+ Tokenizer tokenizer = new Tokenizer();
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertFalse(tokenizer.hasMoreContent());
+ }
+
+ @Test
+ public void testNullSourceWithSetSource() throws Exception {
+ Tokenizer tokenizer = new Tokenizer();
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertFalse(tokenizer.hasMoreContent());
+
+ tokenizer.setSource("hello");
+ assertTrue(tokenizer.hasMoreContent());
+ assertEquals("hello", tokenizer.getNextToken().token);
+ }
+
+ @Test
+ public void testSkipUntilDataEnd() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("a b c d e");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ assertEquals("a", tokenizer.getNextToken().token);
+ tokenizer.skipUntilDataEnd();
+ assertFalse(tokenizer.hasMoreContent());
+ }
+
+ @Test
+ public void testExpectAndConsumeNextTerminatorToken() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("(content)");
+ Terminator openParen = tokenizer.addTerminator(PRESERVE, "\\(", "paren");
+ Terminator closeParen = tokenizer.addTerminator(PRESERVE, "\\)", "paren");
+
+ TokenizerMatch match = tokenizer.expectAndConsumeNextTerminatorToken(openParen);
+ assertEquals("(", match.token);
+ assertEquals(openParen, match.terminator);
+
+ assertEquals("content", tokenizer.getNextToken().token);
+
+ match = tokenizer.expectAndConsumeNextTerminatorToken(closeParen);
+ assertEquals(")", match.token);
+ assertEquals(closeParen, match.terminator);
+ }
+
+ @Test(expected = InvalidSyntaxException.class)
+ public void testExpectAndConsumeNextTerminatorTokenWrongTerminator() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("a b");
+ Terminator whitespace = tokenizer.addTerminator(DROP, "\\s");
+ tokenizer.addTerminator(PRESERVE, "\\(");
+
+ tokenizer.expectAndConsumeNextTerminatorToken(whitespace);
+ }
+
+ @Test(expected = InvalidSyntaxException.class)
+ public void testExpectAndConsumeNextStringTokenWrongValue() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ tokenizer.expectAndConsumeNextStringToken("wrong");
+ }
+
+ @Test
+ public void testPeekExpectNoneOf() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ tokenizer.peekExpectNoneOf("wrong", "other");
+ assertEquals("hello", tokenizer.getNextToken().token);
+ }
+
+ @Test(expected = InvalidSyntaxException.class)
+ public void testPeekExpectNoneOfViolation() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("hello world");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ tokenizer.peekExpectNoneOf("hello", "other");
+ }
+
+ @Test
+ public void testFindTerminatorMatch() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("(hello)");
+ tokenizer.addTerminator(PRESERVE, "\\(");
+ tokenizer.addTerminator(PRESERVE, "\\)");
+
+ TokenizerMatch match = tokenizer.findTerminatorMatch();
+ assertNotNull(match);
+ assertEquals("(", match.token);
+ }
+
+ @Test
+ public void testFindTerminatorMatchNoMatch() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("hello");
+ tokenizer.addTerminator(PRESERVE, "\\(");
+
+ assertNull(tokenizer.findTerminatorMatch());
+ }
+
+ @Test
+ public void testTerminatorActiveFlag() throws Exception {
+ Tokenizer tokenizer = new Tokenizer("/* comment */ text");
+ Terminator comment = tokenizer.addTerminator(DROP, "/\\*.*\\*/");
+ tokenizer.addTerminator(DROP, "\\s");
+
+ comment.active = false;
+ assertTokenEquals("/*", tokenizer);
+ assertTokenEquals("comment", tokenizer);
+
+ tokenizer.setSource("/* comment */ text");
+ comment.active = true;
+ assertTokenEquals("text", tokenizer);
+ }
+
+ private void assertTokenEquals(String expectedValue, Tokenizer tokenizer) {
+ assertEquals(expectedValue, tokenizer.getNextToken().token);
+ }
+
+}
\ No newline at end of file
projects / svjatoslav_commons.git / commitdiff