philiprehberger-encoding_kit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f28c4abaf812bdda01287ea83ef2c48cdef622a082db01adb3f81899ae715809
-  data.tar.gz: 113cd2df4e35e9f49955209662d37aa091bb749fb819d7e1597d7c50c11cdb14
+  metadata.gz: a328360d24956ba2fbcbc7888da4ddfb6dbe1bfac53aa65c6d7431ea6f0c1a16
+  data.tar.gz: f82f1a192f75e1ed0bf7ac386bb17cc4f259b4847af1a83cd5356ed63a2b675c
 SHA512:
-  metadata.gz: c9b0b01dbeb5e0362854c5a66b36e86a7d18c3b05949f70f5496cbe9c5ca784305dc61b9cd330b2f4e7549b0430381ab55ab2c387c24c28b64f9232a843f0c06
-  data.tar.gz: 1754851e434597696433549da529b471e2307da5c6282433c1b8fe5bf624cba3d3210c5e51d6d4f0656b561c5dea27336c9ce8ac8f09c9e53ac56165a848f536
+  metadata.gz: 91b0e02d2d301db41bdc4eda1d3298db4fb517e0ec2bce4c4f79deae7787947db55eb0fdbe12557e9cf317b6b1d000c42ffb02b6901774afa531185b7ae46f1f
+  data.tar.gz: bbab15360e72374f5c9a540c3c8b0c54ae4b673f3bee24ff31ea47ebf2daa29c982564b69069a4f2ead487d5afbefdf606a04fc701c1d6bffd3c75038fd17026

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Standardize README badges, support section, and license format
+
 ## [0.2.0] - 2026-03-28
 
 ### Added

data/README.md

@@ -2,12 +2,7 @@
 
 [![Tests](https://github.com/philiprehberger/rb-encoding-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-encoding-kit/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-encoding_kit.svg)](https://rubygems.org/gems/philiprehberger-encoding_kit)
-[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-encoding-kit)](https://github.com/philiprehberger/rb-encoding-kit/releases)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-encoding-kit)](https://github.com/philiprehberger/rb-encoding-kit/commits/main)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-encoding-kit)](LICENSE)
-[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-encoding-kit/bug)](https://github.com/philiprehberger/rb-encoding-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
-[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-encoding-kit/enhancement)](https://github.com/philiprehberger/rb-encoding-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
-[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 Character encoding detection, conversion, and normalization
 
@@ -136,6 +131,27 @@ 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
+```
+
 ### Validity Check
 
 ```ruby
@@ -160,6 +176,9 @@ 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 |
 
 ## Development
 
@@ -171,10 +190,21 @@ bundle exec rubocop
 
 ## Support
 
-If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-encoding-kit)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-encoding-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-encoding-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
 
-[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
-[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
 
 ## License
 

data/lib/philiprehberger/encoding_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module EncodingKit
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/encoding_kit.rb

@@ -169,6 +169,38 @@ 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
+
     # 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.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-11 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