base85 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f8a6088b3843d55dae49087d58126a5527c36804fbcee912db569db9950ab40
-  data.tar.gz: 5da6748b35556b5723052547d4c10cc0e55a5c1f85ab88f29df32760e164c4ce
+  metadata.gz: cbae229dec12dca96d21882da5944e4370e6f4d3096e85dad9ce0183a21c18d6
+  data.tar.gz: 8bfb829e5a5b61d5f6169940a55d74cc1534699350a2c563d0fe3feb51373d67
 SHA512:
-  metadata.gz: 6e63afeb1c585b407dc2bb154ecc1a363e28919b7a354a9ae1c355293c5ed7b3e91c51a98f4adc8bd88c84391f47b4ccf825a545017a96fbb263d0863e5935c9
-  data.tar.gz: d0e243fb0f19e05733836879cb47577b0127439e5145f5e11939eb3fab34837ebcba486681061a3f2a53cb8c5d3a161bac73e11b4184a64e937a3c46b749e738
+  metadata.gz: 894e13e4725732b656aa9b97194c7e81ef0fc9b87d4fa7d255e23762586a88b0396da955004de092677c5423de6384f7faf23fcc6b4c093c6fd5e82a5ada6cdd
+  data.tar.gz: f10eb21ea204e722f99b6b2c8f08fc7147bb48737b77b91c64cd9db95b72ad8925cd61f4ca380aedba01aa0390c556a521c61de54786049564fc99cd65da1aab

data/.rubocop.yml

@@ -10,12 +10,21 @@ AllCops:
 Layout/LineLength:
   Max: 120
 
+Metrics/AbcSize:
+  Max: 18
+
+Metrics/ClassLength:
+  Enabled: false
+
 Metrics/MethodLength:
   Max: 20
 
 RSpec/DescribedClass:
   Enabled: false
 
+RSpec/MultipleExpectations:
+  Max: 2
+
 Style/RaiseArgs:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## [0.2.0] - 20025-06-25
+## [0.3.0] - 2025-06-xx
+
+- Add Ascii85 alphabet (Adobe flavor)
+- Add base85 command line tool
+
+## [0.2.0] - 2025-06-25
 
 - Add Z85 and RFC1924 alphabets
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 TODO: Write your name
+Copyright (c) 2025 sd77
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,10 +1,13 @@
+[![Gem Version](https://badge.fury.io/rb/base85.svg)](https://badge.fury.io/rb/base85)
+
 # Base85
 
-Base85 is a pure Ruby gem to encode/decode data using Base85 encoding.
+Base85 is a pure Ruby gem to encode/decode data using Base85 encodings.
 
 It handles mulitple alphabets:
 
 * standard (original) one,
+* Ascii85 (Adobe version, very similar to standard one but with start and end markers, and a special 'z' character for 4 null bytes),
 * Z85 from [ZeroMQ](https://github.com/zeromq/libzmq),
 * [RFC1924](https://www.rfc-editor.org/rfc/rfc1924).
 
@@ -20,6 +23,33 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+### CLI
+
+`base85` command line tool may be used to decode/encode base85 dialects on command line.
+
+```bash
+# Encode data from STDIN to STDOUT
+echo "text to encode" | base85
+# Encode using given alphabet (standard (default one), z85, ascii85 or rfc1924)
+echo "text to encode" | base85 -a z85
+# Output data is wrapped to 72 columns by default (as do base64)
+# To change this value, use -w option (0 to deactivate wrapping)
+echo "text to encode" | base85 -a rfc1924 -w 0
+
+# Encode file to STDOUT
+base85 -a ascii85 -w 40 myfile
+
+# Decode data from STDIN to STDOUT
+echo "aaaaa" | base85 -d
+# Encode using given alphabet (standard (default one), z85, ascii85 or rfc1924)
+echo "aaaaa" | base85 -d -a z85
+
+# Decode file to STDOUT
+base85 -d -a rfc1924 myfile
+```
+
+### Ruby library
+
 To encode a string:
 
 ```ruby
@@ -29,6 +59,9 @@ require "base85"
 Base85.encode("test1")  #=> "FCfN80`"
 Base85.encode("test1", alphabet: :standard)  #=> "FCfN80`"
 
+# Use Ascii85 alphabet
+Base85.encode("test1", alphabet: :ascii85)  #=> "<~FCfN80`~>"
+
 # Use Z85 alphabet
 Base85.encode("test1", alphabet: :z85)  #=> "By/Jnf-"
 
@@ -45,6 +78,13 @@ require "base85"
 Base85.decode("ASu!rA7]9")  #=> "encoded"
 Base85.decode("ASu!rA7]9", alphabet: :standard)  #=> "encoded"
 
+# Use Ascii85 alphabet
+Base85.decode("<~ASu!rA7]9~>", alphabet: :ascii85)  #=> "encoded"
+# Special z character
+Base85.decode("<~z~>", alphabet: :ascii85)  #=> "\u0000\u0000\u0000\u0000"
+# Also accept string without markers
+Base85.decode("ASu!rA7]9", alphabet: :ascii85)  #=> "encoded"
+
 # Use Z85 alphabet
 Base85.decode("wO#0@wmYo", alphabet: :z85)  #=> "encoded"
 
@@ -52,12 +92,6 @@ Base85.decode("wO#0@wmYo", alphabet: :z85)  #=> "encoded"
 Base85.decode("Wo~0{WMyO", alphabet: :rfc1924)  #=> "encoded"
 ```
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bundle exec bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on Codeberg at <https://codeberg.org/sd77/base85>.

data/Rakefile

@@ -10,3 +10,13 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+begin
+  require "yard"
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ["lib/**/*.rb", "-", "README.md", "LICENSE.txt"]
+    t.options = %w[--no-private]
+  end
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end

data/exe/base85

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "base85/cli"
+
+Base85::CLI.start(ARGV)

data/lib/base85/ascii85.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Base85
+  # Ascii85 base85 encoding. This encoding uses +!+ to +u+ ASCII characters to encode data. +z+ is used to represent
+  # 32-bit 0 value. The encoded string is surrounded by +<~+ and +~>+ markers.
+  # @author sd77
+  module Ascii85
+    extend ModuleMethods
+
+    # ASCII value for character +!+
+    BASE_ASCII_VALUE = "!".ord
+    # Ascii85 defines +z+ as a special character
+    SPECIAL_Z = true
+
+    # ASCII85 start marker
+    START_MARKER = "<~"
+    # ASCII85 end marker
+    END_MARKER = "~>"
+
+    # Encode a value (0..84 integer) to a Ascii85 character
+    # @param [Integer] value
+    # @return [String]
+    def self.encode_value(value)
+      (BASE_ASCII_VALUE + value).chr
+    end
+
+    # Encode data using Ascii85 encoding
+    # @param [String] data
+    # @return [String] encoded data, surrounded by +<~+ and +~>+ markers
+    def self.encode(data)
+      "#{START_MARKER}#{super}#{END_MARKER}"
+    end
+
+    # Decode a character from Ascii85 and give its index in alphabet
+    # @param [String] char a acharacter from Ascii85 alphabet
+    # @return [Integer] index of this character in alphabet
+    # @raise DecodeError +char+ is not known in alphabet
+    def self.decode_char(char)
+      case char
+      when "!".."u" # rubocop:disable Lint/MixedCaseRange
+        char.ord - BASE_ASCII_VALUE
+      else
+        raise DecodeError, "unknown character '#{char}'"
+      end
+    end
+
+    # Decode data using Ascii85 encoding
+    # @param [String] data Encoded string, may be prefixed by +<~+ and suffixed by +~>+
+    # @return [String] Decoded data
+    # @raise [DecodeError] unknown character or invalid tuple
+    def self.decode(data)
+      start = data.start_with?(START_MARKER) ? 2 : 0
+      stop = data.end_with?(END_MARKER) ? -3 : -1
+      super(data[start..stop])
+    end
+  end
+end

data/lib/base85/cli.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base85"
+
+module Base85
+  # Base85 comman line interface
+  # @author sd77
+  class CLI
+    # Default wrap column count
+    DEFAULT_WRAP = 76
+    # @private
+    #   Max size to read from input at once
+    READ_MAX_SIZE = 4096
+    # Known alphabet codes for --alphabet option
+    ALPHABETS = Base85::SUPPORTED_ALPHABETS.map(&:to_s).freeze
+
+    # Decode (+true+) or encode (+false+)
+    # @return [Boolean]
+    attr_accessor :decode
+    # Alpahbet to use
+    # @param alphabet [:standard, :ascii85 :z85 :rfc1924]
+    attr_writer :alphabet
+    # column count after which output is wrapped
+    # @return [Integer]
+    attr_accessor :wrap
+
+    # Create a CLI object and parse arguments
+    # @param [Array[String]] argv
+    # @return [CLI]
+    def self.start(argv)
+      new.start(argv)
+    end
+
+    # @return [self]
+    def initialize
+      @decode = false
+      @alphabet = :standard
+      @wrap = DEFAULT_WRAP
+    end
+
+    # Alpahbet to use
+    # @return [:standard, :ascii85 :z85 :rfc1924]
+    def alphabet
+      @alphabet.to_sym
+    end
+
+    # Parse arguments
+    # @param [Array[String]] argv
+    # @return [self]
+    def start(argv)
+      parser = create_option_parser
+      parser.parse!(argv)
+
+      abort("---wrap may only be used when encoding") if decode && (wrap != DEFAULT_WRAP)
+
+      if argv.empty?
+        process($stdin)
+      elsif argv.size == 1
+        File.open(argv.shift) do |file|
+          process(file)
+        end
+      else
+        parser.abort("Too much operands")
+      end
+
+      self
+    end
+
+    # Process +input+
+    # @param [IO] input
+    # @return [void]
+    def process(input)
+      if decode
+        decode_input(input)
+      else
+        encode_input(input)
+      end
+    end
+
+    # Encode +input+ and print it to stdout
+    # @param [IO] input
+    # @return [void]
+    def encode_input(input)
+      rest = +""
+      current_col = handle_ascii85_start
+      until input.eof?
+        data = rest << input.read(READ_MAX_SIZE)
+        mod = data.size % 4
+        rest = mod.zero? ? +"" : data.slice!(-mod..)
+        current_col = print_wrapped(encode_data(data), current_col)
+      end
+
+      encoded_rest = handle_ascii85_end(encode_data(rest))
+      print_wrapped(encoded_rest, current_col)
+    end
+
+    # @param [String] data
+    # @return [String] encoded data
+    def encode_data(data)
+      encoded = Base85.encode(data, alphabet: alphabet)
+      ascii85_remove_markers(encoded)
+    end
+
+    # Decode +input+ and print it to stdout
+    # @param [IO] input
+    # @return [void]
+    def decode_input(input)
+      rest = +""
+      until input.eof?
+        data = rest << input.read(READ_MAX_SIZE)
+        ascii85_remove_markers(data)
+        mod = data.size % 5
+        rest = mod.zero? ? +"" : data.slice!(-mod..)
+        print decode_data(data)
+      end
+      print decode_data(rest)
+    end
+
+    # @param [String] data
+    # @return [String] decoded data
+    def decode_data(data)
+      Base85.decode(data, alphabet: alphabet)
+    end
+
+    private
+
+    def create_option_parser
+      OptionParser.new do |parser|
+        prepare_banner(parser)
+        parser.on("-d", "--decode", "Decode data.") { self.decode = true }
+        parser.on("-a", "--alphabet ALPHABET", ALPHABETS,
+                  "Alphabet to use: #{ALPHABETS.join(", ")}\n",
+                  "(default standard).") { |alphabet| self.alphabet = alphabet }
+        parser.on("-w", "--wrap COLS", Integer,
+                  "Wrap encoded lines after WRAP characters (default #{DEFAULT_WRAP}).\n",
+                  "Use 0 to disable wrapping.") { |cols| self.wrap = cols }
+        parser.on("--version", "Output version information and exit.") do
+          show_version
+          exit
+        end
+      end
+    end
+
+    def prepare_banner(parser)
+      parser.banner = "Usage: #{$PROGRAM_NAME} [options] [FILE]\n" \
+                      "Encode or decode FILE or standard input to standard output."
+      parser.separator ""
+      parser.separator "With no FILE, or when FILE is -, read standard input."
+      parser.separator ""
+      parser.separator "Options:"
+    end
+
+    def show_version
+      puts "base85 #{Base85::VERSION}"
+    end
+
+    def ascii85?
+      alphabet == :ascii85
+    end
+
+    def ascii85_remove_markers(data)
+      return data unless ascii85?
+
+      data.delete_prefix!("<~")
+      data.delete_suffix!("~>")
+      data
+    end
+
+    def handle_ascii85_start
+      if ascii85?
+        print Ascii85::START_MARKER
+        Ascii85::START_MARKER.size
+      else
+        0
+      end
+    end
+
+    def handle_ascii85_end(data)
+      data << Ascii85::END_MARKER if ascii85?
+      data
+    end
+
+    def print_wrapped(data, current_col)
+      if wrap.zero?
+        print data
+        return 0
+      end
+
+      puts data.slice!(0, wrap - current_col) if (data.size + current_col) > wrap
+      puts data.slice!(0, wrap) while data.size > wrap
+      print data
+      data.size
+    end
+  end
+end

data/lib/base85/module_methods.rb

@@ -12,6 +12,8 @@ module Base85
     # @param [Integer] word
     # @param [Integer] byte_count byte count of word. Must be in range 1..4
     def encode_word(word, byte_count: 4)
+      return "z" if const_defined?(:SPECIAL_Z) && word.zero? && (byte_count == 4)
+
       encoded = "~" * 5
       5.times do |i|
         word, r = word.divmod(85)
@@ -20,9 +22,9 @@ module Base85
       encoded[..byte_count]
     end
 
-    # Encode data using standard base85 encoding
-    # @param [String] data
-    # @return [String]
+    # Encode data in base85
+    # @param [String] data data to encode
+    # @return [String] base85 encoded string
     def encode(data)
       result = +""
       data.unpack("N*").each do |word|
@@ -36,17 +38,23 @@ module Base85
       result << encode_word(last_chars.unpack1("N"), byte_count: last_count)
     end
 
-    # Decode data using standard base85 encoding
-    # @param [String] data
-    # @return [String]
+    # Decode data from base85
+    # @param [String] data base85 encoded data
+    # @return [String] decoded data
     # @raise [DecodeError] unknown character or invalid tuple
     def decode(data)
       result = +""
       word = 0
       count = 0
       data.each_char do |c|
+        if c == "z" && const_defined?(:SPECIAL_Z)
+          raise DecodeError, "'z' cannot be in the middle of a tuple" if count.positive?
+
+          result << "\0\0\0\0"
+          next
+        end
+
         idx = decode_char(c)
-        p c if idx.nil?
 
         word += idx * LUT[count]
         count += 1

data/lib/base85/rfc1924.rb

@@ -2,7 +2,7 @@
 
 module Base85
   # RFC 1924 base85 encoding
-  # # @author sd77
+  # @author sd77
   module Rfc1924
     extend ModuleMethods
 

data/lib/base85/standard.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Base85
-  # Standard base85 encoding. This encoding uses '!' to 'u' ASCII characters to encode data.
+  # Standard base85 encoding. This encoding uses +!+ to +u+ ASCII characters to encode data.
   # @author sd77
   module Standard
     extend ModuleMethods
 
-    # ASCII value for character '!'
+    # ASCII value for character +!+
     BASE_ASCII_VALUE = "!".ord
 
     # Encode a value (0..84 integer) to a standard base85 character
@@ -17,7 +17,7 @@ module Base85
     end
 
     # Decode a character from standard base85 and give its index in alphabet
-    # @param [String] char a acharacter from base85 alphabet
+    # @param [String] char a character from base85 alphabet
     # @return [Integer] index of this character in alphabet
     # @raise DecodeError +char+ is not known in alphabet
     def self.decode_char(char)

data/lib/base85/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Base85
-  VERSION = "0.2.0"
+  # Base85 gem version
+  VERSION = "0.3.0"
 end

data/lib/base85.rb

@@ -5,6 +5,7 @@ require_relative "base85/module_methods"
 require_relative "base85/standard"
 require_relative "base85/z85"
 require_relative "base85/rfc1924"
+require_relative "base85/ascii85"
 
 # Provide methods to encode/decode Base85 formatted data
 # @author sd77
@@ -17,23 +18,31 @@ module Base85
 
   # Unknown alphabet exception
   class UnknownAlphabetError < Error
+    # @param [Symbol] name alphabet name
     def initialize(name)
       super
       @name = name
     end
 
+    # @return [String]
     def message
       "Uknown alphabet '#{@name}'"
     end
   end
 
   # Supported Base85 alphabets
-  SUPPORTED_ALPHABETS = %i[standard z85 rfc1924].freeze
+  SUPPORTED_ALPHABETS = %i[standard ascii85 z85 rfc1924].freeze
 
+  # Encode +data+ using given +alphabet+
+  # @param [String] data data to encode
+  # @param [:standard,:ascii85,:z85,:rfc1924] alphabet alphabet to use to encode
+  # @return [String] encoded string
   def self.encode(data, alphabet: :standard)
     case alphabet
     when :standard
       Standard.encode(data)
+    when :ascii85
+      Ascii85.encode(data)
     when :z85
       Z85.encode(data)
     when :rfc1924
@@ -43,10 +52,16 @@ module Base85
     end
   end
 
+  # Decode +data+ using given +alphabet+
+  # @param [String] data data to decode
+  # @param [:standard,:ascii85,:z85,:rfc1924] alphabet alphabet to use to decode
+  # @return [String] decoded string
   def self.decode(data, alphabet: :standard)
     case alphabet
     when :standard
       Standard.decode(data)
+    when :ascii85
+      Ascii85.decode(data)
     when :z85
       Z85.decode(data)
     when :rfc1924

metadata

@@ -1,20 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: base85
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - sd77
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-15 00:00:00.000000000 Z
+date: 2025-06-21 00:00:00.000000000 Z
 dependencies: []
-description: Encode and decode base85 data. Multiple alphabets are supported (standard,
-  Z85 or rfc1924)
+description: |
+  Encode and decode base85 data. Multiple alphabets are supported (standard,
+  Ascii85, Z85 or RFC 1924).
 email:
 - sd@ld77.eu
-executables: []
+executables:
+- base85
 extensions: []
 extra_rdoc_files: []
 files:
@@ -24,7 +26,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/base85
 - lib/base85.rb
+- lib/base85/ascii85.rb
+- lib/base85/cli.rb
 - lib/base85/module_methods.rb
 - lib/base85/rfc1924.rb
 - lib/base85/standard.rb