philiprehberger-encoding_kit 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13e2132a0833297e1443ae3c9fc280b2c75ca43c9092e2b6d4d1431981ab90af
-  data.tar.gz: 86091aa48e10920818add35a6e9c147095495096f284d8e00a93d6a3f0ab0596
+  metadata.gz: 135376935f830bcfabb9c706853c5a45d14b270d47cab9d5e54f1ddcfae5f1d4
+  data.tar.gz: 9b06d60d1fd8c3cea4c5197ecb0e26ababe21be31abd6ca92a029978039bc34a
 SHA512:
-  metadata.gz: 55423bdb247b979775199f4ff83043c5bfebff3963ae8f5c0256ca86482e2fd6ded64fe54aded1f06864c387e5a852129baa5a7e8ffb35f47e0dd756e5750b96
-  data.tar.gz: eb8ca82fa4fae2670b5381dca826e95bc7dd281811c97d9488080d2a7666771cc927f16ee8715a05a07418d1b0f4da6096e47f3dcb09bb419e9816c8e284a807
+  metadata.gz: 4e3f14286a3ee38a666a246bc513c972c7483b9b3f77f7ce9e2bfc7324d13eb5cd8a4dc1c3fd3b2d524219b5173679ccfcb5bc510f1f9cedf8eb1f865210b1aa
+  data.tar.gz: a71393c68877452b9005b69415b321ddc2287c57d87de20ec55abb6f57f242dcf64bebe0412e62d9b984371a5682c797c0c58614bcc629ba485570399abf496b

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-20
+
+### Added
+- `guess_from_filename(path)` — extract an encoding hint from filename extensions (`.utf8`, `.utf-16`, `.latin1`, `.cp1252`, `.sjis`, etc.). Returns `nil` when no hint is present so callers can fall back to byte-based detection
+- `FILENAME_ENCODING_HINTS` constant exposing the suffix → `Encoding` lookup table
+
+## [0.3.0] - 2026-04-11
+
+### Added
+- `detect_file(path, sample_size:)` for file-based encoding detection
+- `read_as_utf8(path, from:)` to read files directly as UTF-8
+- `file_valid?(path, encoding:)` to check file encoding validity
+
 ## [0.2.1] - 2026-03-31
 
 ### Changed

data/README.md

@@ -131,6 +131,32 @@ Philiprehberger::EncodingKit.bom?("\xEF\xBB\xBFhello")       # => true
 Philiprehberger::EncodingKit.strip_bom("\xEF\xBB\xBFhello")  # => "hello"
 ```
 
+### File Operations
+
+```ruby
+require "philiprehberger/encoding_kit"
+
+# Detect a file's encoding
+result = Philiprehberger::EncodingKit.detect_file("data.csv")
+result.encoding   # => Encoding::UTF_8
+result.confidence # => 0.9
+
+# Read a file as UTF-8 (auto-detects source encoding)
+content = Philiprehberger::EncodingKit.read_as_utf8("legacy.txt")
+content.encoding # => Encoding::UTF_8
+
+# Read with explicit source encoding
+content = Philiprehberger::EncodingKit.read_as_utf8("latin1.txt", from: Encoding::ISO_8859_1)
+
+# Check if a file's encoding is valid
+Philiprehberger::EncodingKit.file_valid?("data.csv", encoding: Encoding::UTF_8)  # => true
+
+# Guess encoding from a filename hint without reading the bytes
+Philiprehberger::EncodingKit.guess_from_filename("data.utf8.csv")    # => Encoding::UTF_8
+Philiprehberger::EncodingKit.guess_from_filename("legacy.latin1.txt") # => Encoding::ISO_8859_1
+Philiprehberger::EncodingKit.guess_from_filename("report.csv")        # => nil
+```
+
 ### Validity Check
 
 ```ruby
@@ -155,6 +181,10 @@ Philiprehberger::EncodingKit.valid?("hello", encoding: Encoding::US_ASCII)  # =>
 | `EncodingKit.convert(string, from:, to:)` | Convert between arbitrary encodings |
 | `EncodingKit.strip_bom(string)` | Remove byte order mark if present |
 | `EncodingKit.bom?(string)` | Check if string starts with a BOM |
+| `EncodingKit.detect_file(path, sample_size: 4096)` | Detect encoding of a file by reading a byte sample |
+| `EncodingKit.read_as_utf8(path, from: nil)` | Read a file and return its content as UTF-8 |
+| `EncodingKit.file_valid?(path, encoding: nil)` | Check if a file's content is valid in the given encoding |
+| `EncodingKit.guess_from_filename(path)` | Guess `Encoding` from filename suffixes (e.g. `.utf8`, `.latin1`), `nil` if unknown |
 
 ## Development
 

data/lib/philiprehberger/encoding_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module EncodingKit
-    VERSION = '0.2.1'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/encoding_kit.rb

@@ -169,6 +169,94 @@ module Philiprehberger
       BOMS.any? { |bom, _encoding| bytes.start_with?(bom) }
     end
 
+    # Detect the encoding of a file by reading a byte sample.
+    #
+    # @param path [String] path to the file
+    # @param sample_size [Integer] number of bytes to sample (default: 4096)
+    # @return [DetectionResult] the detected encoding with confidence score
+    def self.detect_file(path, sample_size: 4096)
+      File.open(path, 'rb') do |file|
+        detect_stream(file, sample_size: sample_size)
+      end
+    end
+
+    # Read a file and return its content as UTF-8.
+    # Auto-detects the source encoding unless specified via `from:`.
+    #
+    # @param path [String] path to the file
+    # @param from [String, Encoding, nil] source encoding (auto-detect if nil)
+    # @return [String] UTF-8 encoded file content
+    def self.read_as_utf8(path, from: nil)
+      raw = File.binread(path)
+      to_utf8(raw, from: from)
+    end
+
+    # Check if a file's content is valid in the detected or specified encoding.
+    #
+    # @param path [String] path to the file
+    # @param encoding [String, Encoding, nil] encoding to check against (auto-detect if nil)
+    # @return [Boolean]
+    def self.file_valid?(path, encoding: nil)
+      raw = File.binread(path)
+      valid?(raw, encoding: encoding)
+    end
+
+    # Filename suffix / extension hints that imply a specific encoding.
+    # Matched against the final two extension tokens of the filename.
+    FILENAME_ENCODING_HINTS = {
+      'utf8' => Encoding::UTF_8,
+      'utf-8' => Encoding::UTF_8,
+      'utf16' => Encoding::UTF_16,
+      'utf-16' => Encoding::UTF_16,
+      'utf16le' => Encoding::UTF_16LE,
+      'utf-16le' => Encoding::UTF_16LE,
+      'utf16be' => Encoding::UTF_16BE,
+      'utf-16be' => Encoding::UTF_16BE,
+      'utf32' => Encoding::UTF_32,
+      'utf-32' => Encoding::UTF_32,
+      'ascii' => Encoding::US_ASCII,
+      'us-ascii' => Encoding::US_ASCII,
+      'latin1' => Encoding::ISO_8859_1,
+      'latin-1' => Encoding::ISO_8859_1,
+      'iso88591' => Encoding::ISO_8859_1,
+      'iso-8859-1' => Encoding::ISO_8859_1,
+      'iso88592' => Encoding::ISO_8859_2,
+      'iso-8859-2' => Encoding::ISO_8859_2,
+      'cp1252' => Encoding::Windows_1252,
+      'windows1252' => Encoding::Windows_1252,
+      'windows-1252' => Encoding::Windows_1252,
+      'sjis' => Encoding::Shift_JIS,
+      'shiftjis' => Encoding::Shift_JIS,
+      'shift-jis' => Encoding::Shift_JIS,
+      'shift_jis' => Encoding::Shift_JIS,
+      'euc-jp' => Encoding::EUC_JP,
+      'eucjp' => Encoding::EUC_JP,
+      'gbk' => Encoding::GBK,
+      'gb2312' => Encoding::GB2312,
+      'big5' => Encoding::Big5
+    }.freeze
+
+    # Guess the encoding based on filename suffixes/extensions alone.
+    # Useful when a file name carries an explicit encoding hint
+    # (e.g., "data.utf8.csv", "legacy.latin1.txt"). Falls back to nil
+    # when no hint can be extracted — callers should then use
+    # {.detect_file} to inspect the bytes.
+    #
+    # Matching is case-insensitive and considers the final two
+    # file extension tokens; the rightmost recognizable hint wins.
+    #
+    # @param filename [String] filename or path
+    # @return [Encoding, nil] detected encoding or nil when no hint matches
+    def self.guess_from_filename(filename)
+      name = File.basename(filename.to_s).downcase
+      tokens = name.split('.').last(3) # extension + up to two modifiers
+      tokens.reverse_each do |token|
+        enc = FILENAME_ENCODING_HINTS[token]
+        return enc if enc
+      end
+      nil
+    end
+
     # Build a list of encoding candidates with confidence scores.
     #
     # @param bytes [String] binary string

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-encoding_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies: []
 description: Detect encoding from BOM and heuristics with confidence scores, convert
   between encodings, normalize to UTF-8, analyze byte distributions, and handle Windows
@@ -27,11 +27,11 @@ files:
 - lib/philiprehberger/encoding_kit/detection_result.rb
 - lib/philiprehberger/encoding_kit/detector.rb
 - lib/philiprehberger/encoding_kit/version.rb
-homepage: https://github.com/philiprehberger/rb-encoding-kit
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-encoding_kit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-encoding-kit
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-encoding_kit
   source_code_uri: https://github.com/philiprehberger/rb-encoding-kit
   changelog_uri: https://github.com/philiprehberger/rb-encoding-kit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-encoding-kit/issues