hachi64 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf15a3dea562b3cc659afb7ea4d550c9f84e0eba3de75afc63718c03cdf03390
+  data.tar.gz: 4d3c5105fa319c23505b627e66f573ee174a3d51ab7672dc8d9ce2c0f59651ee
+SHA512:
+  metadata.gz: 1e96d902febbdd44958b7923b633d57b4df54a7508396b3e7b0e22558d89961b6bd93af12a3a31917d28e05fd00a982c34f8bfbb8c0d63580b7bebb0b68d8175
+  data.tar.gz: e2366de73b2df4586440e90c293c7b4228fc14ae11b3e4f93635fdbc2bb8fc98fbc2a2ce127c054ef722a9ad3d230706de4645a440d51237247a56e3801a1d90

data/README.md

@@ -0,0 +1,182 @@
+# Hachi64 Ruby Implementation
+
+哈吉米64 编解码器的 Ruby 实现 - 使用64个中文字符进行 Base64 风格的编码和解码。
+
+## 安装
+
+### 从源码安装
+
+```bash
+cd ruby
+gem build hachi64.gemspec
+gem install hachi64-0.1.0.gem
+```
+
+### 在项目中使用
+
+如果不想安装 gem，可以直接在项目中引用：
+
+```ruby
+require_relative 'lib/hachi64'
+```
+
+### 运行示例
+
+查看并运行 `example.rb` 来了解基本用法：
+
+```bash
+ruby example.rb
+```
+
+## 使用方法
+
+### 基本使用
+
+```ruby
+require 'hachi64'
+
+# 编码
+data = "Hello, World!"
+encoded = Hachi64.encode(data)
+puts encoded # 输出: 豆米啊拢嘎米多拢迷集伽漫咖苦播库迷律==
+
+# 解码
+decoded = Hachi64.decode(encoded)
+puts decoded # 输出: Hello, World!
+```
+
+### 不使用填充
+
+```ruby
+# 编码时不使用填充
+encoded = Hachi64.encode("Hello", padding: false)
+puts encoded # 输出: 豆米啊拢嘎米多
+
+# 解码时指定无填充
+decoded = Hachi64.decode(encoded, padding: false)
+puts decoded # 输出: Hello
+```
+
+### 处理二进制数据
+
+```ruby
+# Hachi64 可以处理任意二进制数据
+binary_data = File.read("image.png", mode: "rb")
+encoded = Hachi64.encode(binary_data)
+decoded = Hachi64.decode(encoded)
+
+# 验证数据完整性
+puts binary_data == decoded # 输出: true
+```
+
+## API 文档
+
+### `Hachi64.encode(data, padding: true)`
+
+将字节字符串编码为哈吉米64字符串。
+
+**参数:**
+- `data` (String): 要编码的数据（二进制字符串）
+- `padding` (Boolean): 是否使用 `=` 进行填充（默认为 `true`）
+
+**返回:**
+- (String): 编码后的字符串
+
+**示例:**
+```ruby
+Hachi64.encode("Hello")  # => "豆米啊拢嘎米多="
+Hachi64.encode("Hello", padding: false)  # => "豆米啊拢嘎米多"
+```
+
+### `Hachi64.decode(encoded_str, padding: true)`
+
+将哈吉米64字符串解码为字节字符串。
+
+**参数:**
+- `encoded_str` (String): 要解码的字符串
+- `padding` (Boolean): 输入字符串是否使用 `=` 进行填充（应与编码时的设置一致，默认为 `true`）
+
+**返回:**
+- (String): 解码后的字节字符串
+
+**异常:**
+- `ArgumentError`: 如果输入包含无效字符
+
+**示例:**
+```ruby
+Hachi64.decode("豆米啊拢嘎米多=")  # => "Hello"
+Hachi64.decode("豆米啊拢嘎米多", padding: false)  # => "Hello"
+```
+
+### `Hachi64::HACHI_ALPHABET`
+
+哈吉米64字符集常量，包含64个中文字符。
+
+```ruby
+puts Hachi64::HACHI_ALPHABET
+# => "哈蛤呵吉急集米咪迷南男难北背杯绿律虑豆斗抖啊阿额西希息嘎咖伽花华哗压鸭呀库酷苦奶乃耐龙隆拢曼慢漫波播玻叮丁订咚东冬囊路陆多都弥济"
+```
+
+## 编码示例
+
+以下是一些使用哈吉米64编码的示例：
+
+| 原始数据 | 编码结果 |
+|---------|---------|
+| `Hello` | `豆米啊拢嘎米多=` |
+| `abc` | `西阿南呀` |
+| `Python` | `抖咪酷丁息米都慢` |
+| `Hello, World!` | `豆米啊拢嘎米多拢迷集伽漫咖苦播库迷律==` |
+| `Base64` | `律苦集叮希斗西丁` |
+| `Hachi64` | `豆米集呀息米库咚背哈==` |
+
+## 测试
+
+运行单元测试：
+
+```bash
+cd ruby
+bundle install  # 安装开发依赖
+bundle exec rspec
+```
+
+或者直接使用 RSpec（如果已全局安装）：
+
+```bash
+cd ruby
+rspec
+```
+
+## 特性
+
+- ✅ 完整的编码/解码功能
+- ✅ 支持有/无填充模式
+- ✅ 处理任意二进制数据
+- ✅ 与其他语言实现兼容
+- ✅ 完整的 RSpec 测试覆盖
+- ✅ 清晰的错误处理
+- ✅ 符合 Ruby 编码规范
+
+## 开发
+
+### 安装依赖
+
+```bash
+bundle install
+```
+
+### 运行测试
+
+```bash
+bundle exec rspec
+```
+
+### 构建 gem
+
+```bash
+gem build hachi64.gemspec
+```
+
+## 许可证
+
+本项目遵循父项目的许可证。

data/lib/hachi64.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Hachi64: 哈吉米64 Encoding and Decoding
+# This module provides encoding and decoding using the Hachi64 character set.
+
+module Hachi64
+  # The Hachi64 alphabet - 64 unique Chinese characters
+  HACHI_ALPHABET = "哈蛤呵吉急集米咪迷南男难北背杯绿律虑豆斗抖啊阿额西希息嘎咖伽花华哗压鸭呀库酷苦奶乃耐龙隆拢曼慢漫波播玻叮丁订咚东冬囊路陆多都弥济"
+
+  # Encodes a byte string into a Hachi64 string using the Hachi64 alphabet.
+  #
+  # @param data [String] The bytes to encode (binary string)
+  # @param padding [Boolean] Whether to use '=' for padding (default: true)
+  # @return [String] The encoded string
+  def self.encode(data, padding: true)
+    alphabet = HACHI_ALPHABET
+    result = []
+    data_len = data.bytesize
+    i = 0
+
+    while i < data_len
+      chunk = data.byteslice(i, 3)
+      i += 3
+
+      byte1 = chunk.getbyte(0)
+      byte2 = chunk.bytesize > 1 ? chunk.getbyte(1) : 0
+      byte3 = chunk.bytesize > 2 ? chunk.getbyte(2) : 0
+
+      idx1 = byte1 >> 2
+      idx2 = ((byte1 & 0x03) << 4) | (byte2 >> 4)
+      idx3 = ((byte2 & 0x0F) << 2) | (byte3 >> 6)
+      idx4 = byte3 & 0x3F
+
+      result << alphabet[idx1]
+      result << alphabet[idx2]
+
+      if chunk.bytesize > 1
+        result << alphabet[idx3]
+      elsif padding
+        result << '='
+      end
+
+      if chunk.bytesize > 2
+        result << alphabet[idx4]
+      elsif padding
+        result << '='
+      end
+    end
+
+    result.join
+  end
+
+  # Decodes a Hachi64 string into bytes using the Hachi64 alphabet.
+  #
+  # @param encoded_str [String] The string to decode
+  # @param padding [Boolean] Whether the input string uses '=' for padding (default: true)
+  # @return [String] The decoded bytes (binary string)
+  # @raise [ArgumentError] If the input string contains invalid characters
+  def self.decode(encoded_str, padding: true)
+    alphabet = HACHI_ALPHABET
+    reverse_map = {}
+    alphabet.each_char.with_index { |char, i| reverse_map[char] = i }
+
+    # Handle empty string
+    return ''.b if encoded_str.empty?
+
+    pad_count = 0
+    if padding
+      pad_count = encoded_str.count('=')
+      if pad_count > 0
+        encoded_str = encoded_str[0...-pad_count]
+      end
+    end
+
+    result = []
+    data_len = encoded_str.length
+    i = 0
+
+    while i < data_len
+      chunk_end = [i + 4, data_len].min
+      chunk = encoded_str[i...chunk_end]
+      i += 4
+
+      idx1 = reverse_map[chunk[0]]
+      idx2 = chunk.length > 1 ? reverse_map[chunk[1]] : 0
+      idx3 = chunk.length > 2 ? reverse_map[chunk[2]] : 0
+      idx4 = chunk.length > 3 ? reverse_map[chunk[3]] : 0
+
+      raise ArgumentError, "Invalid character in input" if idx1.nil? || (chunk.length > 1 && idx2.nil?)
+
+      byte1 = (idx1 << 2) | (idx2 >> 4)
+      result << byte1
+
+      if chunk.length > 2
+        byte2 = ((idx2 & 0x0F) << 4) | (idx3 >> 2)
+        result << byte2
+      end
+
+      if chunk.length > 3
+        byte3 = ((idx3 & 0x03) << 6) | idx4
+        result << byte3
+      end
+    end
+
+    result.pack('C*')
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: hachi64
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- fengb3
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: Hachi64 provides encoding and decoding using a custom 64-character Chinese
+  character set, similar to Base64 but with Hachimi-style characters.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hachi64.rb
+homepage: https://github.com/fengb3/Hachi64
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fengb3/Hachi64
+  source_code_uri: https://github.com/fengb3/Hachi64
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: 哈吉米64 encoding and decoding
+test_files: []