tinycode 0.1.0

data/README.md

@@ -0,0 +1,159 @@
+# Tinycode
+
+This gem provides an encoder and decoder for tinycode, which is a bencode like
+encoding that supports more data-types and slightly smaller encoded sizes.
+
+The encoder supports arrays, hashes, strings, symbols, and integers, as well as
+specialized fixed-width integers: `Tinycode::U8`, `Tinycode::U16`,
+`Tinycode::U32`, and `Tinycode::U64`.
+Like [YAML] but unlike [JSON], this encoder maintains a distinction between
+strings and symbols.
+
+The encoding is inspired by [BEncode]'s tag-length-value construction for strings, which eliminates the need for escaping in Strings.
+This makes this encoding particularly appropriate for serializing binary strings
+directly.
+
+[YAML]: https://ruby-doc.org/stdlib-3.0.2/libdoc/yaml/rdoc/YAML.html
+[JSON]: https://ruby-doc.org/stdlib-3.0.2/libdoc/json/rdoc/JSON.html
+[BEncode]: https://en.wikipedia.org/wiki/Bencode
+
+## Demo
+
+Consider the following data structure:
+
+```ruby
+[
+  {
+  location: 'Chicago',
+  currently: {
+    temperature: 72,
+    condition: ['Partly cloudy', 'Chance of rain']
+  },
+  narrative: "High: 81, low: 56\nCooler than yesterday.",
+  high: 81,
+  low: 56
+  },
+  {
+  location: 'New York',
+  currently: {
+    temperature: 45,
+    condition: ['Rainy']
+  },
+  narrative: "High: 56, low: -2\nWinter Weather Alert in effect.",
+  high: 56,
+  low: -2
+  }
+]
+```
+
+The resulting structure looks something like this. In actuality, there is not
+this much whitespace, and the \xNN codes represent binary values.
+
+```plain
+[
+  {
+    currently:{
+      condition:[
+        Partly cloudy'
+        Chance of rain'
+      ]
+      temperature:+\x48
+    }
+    high:+\x51
+    location:Chicago'
+    low:+\x38
+    narrative:'\x28High: 81, low: 56\nCooler than yesterday.
+  }
+  {
+    currently:{condition:[Rainy']temperature:+\x2D}
+    high:+\x38
+    location:New York'
+    low:-\x02
+    narrative:'\x31High: 56, low: -2\nWinter Weather Alert in effect.
+  }
+]
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tinycode'
+```
+
+And then execute:
+
+```sh
+$ bundle install
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install tinycode
+```
+
+## Usage
+
+### Dumping a data structure
+
+```ruby
+require 'tinycode'
+
+42.tinycode
+['some', 'array'].tinycode
+# and so on
+```
+
+Alternatively you can use `Tinycode.dump`:
+
+```ruby
+# can use 'tinycode/no_core_ext' instead if class extensions are unwanted
+require 'tinycode'
+
+Tinycode.dump(42)
+Tinycode.dump(['some', 'array'])
+# and so on
+```
+
+### Restoring a data structure
+
+```ruby
+require 'tinycode'
+
+Tinycode.load("+\x2A".b) # => 42
+Tinycode.load("[some'array']".b) # => ['some', 'array']
+# and so on
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then,
+run `rake watch` to run yard, tests, and linting on every file save.
+
+To install this gem onto your local machine, run `rake install`.
+
+To release a new version, update the version number in `version.rb`.
+Then run `rake release`, which will create/push a git tag for the version and
+publish the `.gem` file to [rubygems.org].
+
+[rubygems.org]: https://rubygems.org
+
+## License
+
+All copyright rights are held by the authors as recorded in git.
+See the commit history for a comprehensive listing of copyright holders and
+copyright dates.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+See LICENSE in this repository for the full license text.

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:lint) do |task|
+  task.options = %w[--except Metrics]
+end
+YARD::Rake::YardocTask.new
+
+task :watch do
+  sh 'rerun -p "{**/*.{rb,gemspec},exe/**/*,Gemfile*,Rakefile}" -x rake yard spec lint:auto_correct'
+end
+
+task default: [:yard, :spec, :lint]

data/lib/tinycode/core_ext.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/Documentation
+
+
+class Array
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class Hash
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class String
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class Symbol
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class Integer
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class TrueClass
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class FalseClass
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+class NilClass
+  def tinycode
+    Tinycode.dump(self)
+  end
+end
+
+# rubocop:enable Style/Documentation

data/lib/tinycode/fixed_integer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Tinycode
+  # Mixin module for U8, U16, U32, and U64 classes
+  module FixedInteger
+    attr_reader :value
+    alias to_i value
+    alias to_int value
+
+    def initialize(value)
+      raise ArgumentError, "#{value.class} cannot be converted to integer" unless value.respond_to?(:to_int)
+
+      @value = value.to_int
+
+      raise RangeError, "#{@value.inspect} out of range for #{self.class}" unless self.class.range.include?(@value)
+    end
+
+    def tinycode
+      Tinycode.dump(self)
+    end
+
+    def to_s
+      value.to_s
+    end
+
+    def inspect
+      "#<#{self.class} value=#{value.inspect}>"
+    end
+
+    def ==(other)
+      value == other.value
+    end
+  end
+
+  # an unsigned integer that takes up exactly 8 bits
+  class U8
+    include FixedInteger
+    def self.range
+      0x00..0xFF
+    end
+  end
+
+  # an unsigned integer that takes up exactly 16 bits
+  class U16
+    include FixedInteger
+    def self.range
+      0x0000..0xFFFF
+    end
+  end
+
+  # an unsigned integer that takes up exactly 32 bits
+  class U32
+    include FixedInteger
+    def self.range
+      0x00000000..0xFFFFFFFF
+    end
+  end
+
+  # an unsigned integer that takes up exactly 64 bits
+  class U64
+    include FixedInteger
+    def self.range
+      0x00000000_00000000..0xFFFFFFFF_FFFFFFFF
+    end
+  end
+end

data/lib/tinycode/module.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative 'fixed_integer'
+require_relative 'version'
+
+# An encoder and decoder for tinycode, which is a bencode like encoding that
+# supports more data-types and slightly smaller encoded sizes.
+module Tinycode
+  class ParseError < StandardError; end
+
+  class << self
+    def dump(obj)
+      case obj
+      when Array then dump_array(obj)
+      when Hash then dump_hash(obj)
+      when String then dump_string(obj)
+      when Symbol then dump_symbol(obj)
+      when Integer then dump_integer(obj)
+      when U8 then dump_fixed_integer(obj, code: '%', pack: 'aC')
+      when U16 then dump_fixed_integer(obj, code: '$', pack: 'aS>')
+      when U32 then dump_fixed_integer(obj, code: '!', pack: 'aL>')
+      when U64 then dump_fixed_integer(obj, code: '#', pack: 'aQ>')
+      when nil then "\0".b
+      when true then '?T'.b
+      when false then '?F'.b
+      else raise ArgumentError, "Don't know how to dump #{obj.class}"
+      end
+    end
+
+    def load(tinycode)
+      raise ArgumentError, "Cannot convert #{Tinycode.class} to String" if !tinycode.respond_to?(:to_str)
+
+      tinycode = tinycode.to_str.b
+      struct, length = load_with_length(tinycode)
+      raise ParseError, 'Input is longer than expected' if length != tinycode.length
+
+      struct
+    end
+
+    private
+
+    def load_with_length(tinycode)
+      case tinycode[0]
+      when /[\w \t\n]/ then load_id(tinycode)
+      when '['         then load_array(tinycode)
+      when '{'         then load_hash(tinycode)
+      when "'"         then load_string(tinycode)
+      when ':'         then load_symbol(tinycode)
+      when '-', '+'    then load_integer(tinycode)
+      when '%'         then load_fixed_integer(tinycode, U8, length: 1, unpack: 'C')
+      when '$'         then load_fixed_integer(tinycode, U16, length: 2, unpack: 'S>')
+      when '!'         then load_fixed_integer(tinycode, U32, length: 4, unpack: 'L>')
+      when '#'         then load_fixed_integer(tinycode, U64, length: 8, unpack: 'Q>')
+      when "\0"        then [nil, 1]
+      when '?'         then load_boolean(tinycode)
+      else raise ParseError, "Unexpected character: #{tinycode[0]}"
+      end
+    end
+
+    def dump_array(ary)
+      "[#{ary.map(&method(:dump)).join}]".b
+    end
+
+    def load_array(tinycode)
+      offset = 1
+      result = []
+      until tinycode[offset] == ']'
+        value, length = load_with_length(tinycode[offset..])
+        result << value
+        offset += length
+      end
+      [result, offset + 1]
+    end
+
+    def dump_hash(hash)
+      "{#{hash.sort.flatten(1).map(&method(:dump)).join}}".b
+    end
+
+    def load_hash(tinycode)
+      offset = 1
+      result = {}
+      until tinycode[offset] == '}'
+        key, key_length = load_with_length(tinycode[offset..])
+        offset += key_length
+        value, value_length = load_with_length(tinycode[offset..])
+        offset += value_length
+        raise if result.key?(key)
+
+        result[key] = value
+      end
+      [result, offset + 1]
+    end
+
+    def dump_string(str, code: "'")
+      str = str.encode('UTF-8').b unless str.encoding == Encoding::ASCII_8BIT
+      if str =~ /\A[\w \t\n]+\z/
+        [str, code].pack('a*a')
+      else
+        [code, str.length, str].pack('awa*')
+      end
+    end
+
+    def load_id(tinycode)
+      length = tinycode.index(/[':]/)
+      value = tinycode[...length]
+      value = if tinycode[length] == ':'
+                value.to_sym
+              else
+                value.force_encoding('UTF-8')
+              end
+      [value, length + 1]
+    end
+
+    def load_string(tinycode)
+      str_length, offset = load_varint(tinycode[1..])
+      [tinycode[(1 + offset)...(1 + offset + str_length)].force_encoding('UTF-8'), 1 + offset + str_length]
+    end
+
+    def dump_symbol(sym)
+      dump_string(sym.name, code: ':')
+    end
+
+    def load_symbol(sym)
+      value, offset = load_string(sym)
+      [value.to_sym, offset]
+    end
+
+    def dump_integer(num)
+      if num < 0
+        ['-', -num].pack('aw')
+      else
+        ['+', num].pack('aw')
+      end
+    end
+
+    def load_integer(tinycode)
+      value, offset = load_varint(tinycode[1..])
+      value = -value if tinycode[0] == '-'
+
+      [value, 1 + offset]
+    end
+
+    def dump_fixed_integer(num, code:, pack:)
+      [code, num].pack(pack)
+    end
+
+    def load_fixed_integer(tinycode, clazz, length:, unpack:)
+      [clazz.new(tinycode[1...(1 + length)].unpack1(unpack)), 1 + length]
+    end
+
+    def load_varint(tinycode)
+      length = tinycode.each_byte.lazy.take_while {|b| b > 0x7F }.count + 1
+      [tinycode[...length].unpack1('w'), length]
+    end
+
+    def load_boolean(tinycode)
+      case tinycode[1]
+      when 'T' then [true, 2]
+      when 'F' then [false, 2]
+      else raise ParseError, 'Malformed boolean'
+      end
+    end
+  end
+end

data/lib/tinycode/no_core_ext.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'module'

data/lib/tinycode/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tinycode
+  VERSION = '0.1.0'
+end

data/lib/tinycode.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'tinycode/core_ext'
+require_relative 'tinycode/module'

data/tinycode.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/tinycode/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'tinycode'
+  spec.version = Tinycode::VERSION
+  spec.summary = 'An encoder and decoder for tinycode'
+  spec.description = 'tinycode is a bencode like encoding that supports more ' \
+    'data-types and slightly smaller encoded sizes.'
+  spec.authors = ['Alex Gittemeier']
+  spec.license = 'GPL-3.0'
+  spec.email = ['me@a.lexg.dev']
+  spec.metadata['source_code_uri'] = 'https://gitlab.com/windows93/tinycode'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  # spec.metadata['changelog_uri'] =
+
+  spec.homepage = spec.metadata['source_code_uri']
+  spec.metadata['homepage_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) {|f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rerun', '~> 0.13'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.21'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.6'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.6'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: tinycode
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Gittemeier
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-11-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rerun
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: tinycode is a bencode like encoding that supports more data-types and
+  slightly smaller encoded sizes.
+email:
+- me@a.lexg.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- lib/tinycode.rb
+- lib/tinycode/core_ext.rb
+- lib/tinycode/fixed_integer.rb
+- lib/tinycode/module.rb
+- lib/tinycode/no_core_ext.rb
+- lib/tinycode/version.rb
+- tinycode.gemspec
+homepage: https://gitlab.com/windows93/tinycode
+licenses:
+- GPL-3.0
+metadata:
+  source_code_uri: https://gitlab.com/windows93/tinycode
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://gitlab.com/windows93/tinycode
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: An encoder and decoder for tinycode
+test_files: []