key_value_name 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c1f8780bde799ea40e2fd042acd3893a16d506b1
+  data.tar.gz: 0c8a821f32cf6cbdd8681c559f27498011d64e25
+SHA512:
+  metadata.gz: b13cf37a899c2be009c01cc3f94da5068bc2c495901f217d72f715444e8118f191cb96fcf9553527ac4f3f5879220c1a898e6a93d6c2545c8908462cf8dc8e34
+  data.tar.gz: eee937f19b07d827f3bd5bdf65b7c1b93935e8d4fe7f222b85c3f3e7afa0be570d008b1466db312ebff6bfab378e40c9e4712ca437e31e8ebd43318b470af650

data/README.md

@@ -0,0 +1,72 @@
+# key_value_name
+
+* https://github.com/jdleesmiller/key_value_name
+
+## Synopsis
+
+Store key-value pairs in file names, for example parameter names and parameters for experiments or simulation runs.
+
+This gem provides:
+
+1. Some standard naming conventions that work well across platforms by avoiding special characters in file names.
+
+2. Automatic formatting and type conversion for the parameters.
+
+## Usage
+
+```rb
+require 'key_value_name'
+
+ResultName = KeyValueName.new do |n|
+  n.key :seed, type: Numeric, format: '%d'
+  n.key :algorithm, type: Symbol
+  n.key :alpha, type: Numeric
+  n.extension :dat
+end
+
+name = ResultName.new(
+  seed: 123,
+  algorithm: :reticulating_splines,
+  alpha: 42.1)
+
+name.to_s
+# => seed-123.algorithm-reticulating_splines.alpha-42.1.dat
+
+name.in('/tmp')
+# => /tmp/seed-123.algorithm-reticulating_splines.alpha-42.1.dat
+
+# Assuming a matching file exists in /tmp.
+ResultName.glob('/tmp')
+# => [#<struct ResultName seed=123, algorithm=:reticulating_splines, alpha=42.1>]
+```
+
+## INSTALLATION
+
+```
+gem install key_value_name
+```
+
+## LICENSE
+
+(The MIT License)
+
+Copyright (c) 2017 John Lees-Miller
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/key_value_name.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#
+# A terrible idea, but also a useful one.
+#
+module KeyValueName
+  KEY_RX = /\w+/
+  KEY_VALUE_SEPARATOR = '-'
+  PAIR_SEPARATOR = '.'
+  PAIR_SEPARATOR_RX = /[.]/
+
+  def self.check_symbol(name)
+    raise ArgumentError, "bad symbol: #{name}" unless name =~ /\A#{KEY_RX}\z/
+  end
+
+  def self.new
+    builder = Builder.new
+    yield builder
+    builder.build
+  end
+end
+
+require_relative 'key_value_name/version'
+require_relative 'key_value_name/marshalers'
+require_relative 'key_value_name/spec'
+require_relative 'key_value_name/builder'

data/lib/key_value_name/builder.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Yield-based Domain-Specific Language (DSL) to build a `KeyValueName`.
+  #
+  class Builder
+    #
+    # Class methods of the returned `KeyValueName` class.
+    #
+    module ClassMethods
+      def read_hash(name)
+        key_value_name_spec.read(name)
+      end
+
+      def read(name)
+        new(read_hash(name))
+      end
+
+      def glob(path)
+        Dir.glob(File.join(path, '*')).map do |name|
+          basename = File.basename(name)
+          new(read_hash(basename)) if key_value_name_spec.matches?(basename)
+        end.compact
+      end
+    end
+
+    #
+    # Instance methods of the returned `KeyValueName` class.
+    #
+    module InstanceMethods
+      def in(folder)
+        File.join(folder, to_s)
+      end
+
+      def to_s
+        self.class.key_value_name_spec.write(self)
+      end
+    end
+
+    def initialize
+      @marshalers = {}
+      @extension = nil
+    end
+
+    def include_keys(key_value_name_klass)
+      spec = key_value_name_klass.key_value_name_spec
+      spec.marshalers.each do |name, marshaler|
+        check_no_existing_marshaler(name)
+        @marshalers[name] = marshaler
+      end
+    end
+
+    def key(name, type:, **kwargs)
+      KeyValueName.check_symbol(name)
+      raise ArgumentError, "bad type: #{type}" unless MARSHALERS.key?(type)
+      check_no_existing_marshaler(name)
+      @marshalers[name] = MARSHALERS[type].new(**kwargs)
+    end
+
+    def extension(ext) # rubocop:disable Style/TrivialAccessors
+      @extension = ext
+    end
+
+    def build # rubocop:disable Metrics/MethodLength
+      raise 'no keys defined' if @marshalers.none?
+
+      klass = Struct.new(*@marshalers.keys) do
+        def initialize(**kwargs)
+          super(*kwargs.keys)
+          kwargs.each { |k, v| self[k] = v }
+        end
+
+        include InstanceMethods
+
+        class <<self
+          include ClassMethods
+          attr_accessor :key_value_name_spec
+        end
+      end
+      klass.key_value_name_spec = Spec.new(@marshalers, @extension)
+      klass
+    end
+
+    private
+
+    def check_no_existing_marshaler(key)
+      raise ArgumentError, "already have key: #{key}" if @marshalers.key?(key)
+    end
+  end
+end

data/lib/key_value_name/marshalers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+require_relative 'marshalers/base'
+require_relative 'marshalers/numeric_marshaler'
+require_relative 'marshalers/symbol_marshaler'
+
+module KeyValueName
+  MARSHALERS = {
+    Numeric => NumericMarshaler,
+    Symbol => SymbolMarshaler
+  }.freeze
+end

data/lib/key_value_name/marshalers/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # A Marshaler handles conversion of typed values to and from strings.
+  #
+  class MarshalerBase
+    def initialize(**kwargs)
+    end
+
+    def matcher
+      raise NotImplementedError
+    end
+
+    def read(_string)
+      raise NotImplementedError
+    end
+
+    def write(_value)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/key_value_name/marshalers/numeric_marshaler.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'scanf'
+
+module KeyValueName
+  #
+  # Read and write numeric types with a general format string for
+  # `Kernel#format` (or `Kernel#sprintf`) and `String#scanf`.
+  #
+  # This seems like a nice idea, but ruby's `scanf` doesn't seem to handle
+  # all possible format strings. For example, you can format with `%.1f`, but
+  # scanning with that string does not work. To work around this problem,
+  # you can specify a separate `scan_format` that `scanf` can handle; for this
+  # example, it would be just `%f`.
+  #
+  class NumericMarshaler < MarshalerBase
+    def initialize(format: '%g', scan_format: nil)
+      @format_string = format
+      @scan_format_string = scan_format
+    end
+
+    attr_reader :format_string
+
+    def scan_format_string
+      @scan_format_string || format_string
+    end
+
+    def matcher
+      # This is the usual regex, except that it also has to match `%x` formats,
+      # so it allows hexadecimal whole numbers.
+      /[-+]?[0-9]*\.?[0-9a-f]+(?:e[-+]?[0-9]+)?/i
+    end
+
+    def read(string)
+      values = string.scanf(scan_format_string)
+      raise "failed to scan: #{string}" if values.empty?
+      values.first
+    end
+
+    def write(value)
+      format(format_string, value)
+    end
+  end
+end

data/lib/key_value_name/marshalers/symbol_marshaler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Read and write symbol values.
+  #
+  class SymbolMarshaler < MarshalerBase
+    def matcher
+      KEY_RX
+    end
+
+    def read(string)
+      string.to_sym
+    end
+
+    def write(value)
+      KeyValueName.check_symbol(value)
+      value.to_s
+    end
+  end
+end

data/lib/key_value_name/spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Specify the keys and value types for a KeyValueName.
+  #
+  class Spec
+    def initialize(marshalers, extension)
+      @marshalers = marshalers
+      @extension = extension
+      @matcher = build_matcher
+
+      marshalers.freeze
+      freeze
+    end
+
+    attr_reader :marshalers
+    attr_reader :extension
+    attr_reader :matcher
+
+    def matches?(string)
+      string =~ matcher
+    end
+
+    def read(string)
+      raise ArgumentError, "bad filename: #{string}" unless string =~ matcher
+      Hash[marshalers.map.with_index do |(key, marshaler), index|
+        [key, marshaler.read(Regexp.last_match(index + 1))]
+      end]
+    end
+
+    def write(name)
+      string = name.each_pair.map do |key, value|
+        value_string = marshalers[key].write(value)
+        "#{key}#{KEY_VALUE_SEPARATOR}#{value_string}"
+      end.join(PAIR_SEPARATOR)
+      string += ".#{extension}" unless extension.nil?
+      string
+    end
+
+    private
+
+    def build_matcher
+      pair_rxs = marshalers.map do |name, marshaler|
+        /#{name}#{KEY_VALUE_SEPARATOR}(#{marshaler.matcher})/
+      end
+      pairs_matcher = pair_rxs.map(&:to_s).join(PAIR_SEPARATOR_RX.to_s)
+      extension_matcher = extension.nil? ? '' : /[.]#{extension}/.to_s
+      Regexp.new('\A' + pairs_matcher + extension_matcher + '\z')
+    end
+  end
+end

data/lib/key_value_name/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  VERSION_MAJOR = 0
+  VERSION_MINOR = 0
+  VERSION_PATCH = 1
+  VERSION = [VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH].join('.')
+end

data/test/key_value_name/key_value_name_test.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'fileutils'
+require 'tmpdir'
+
+require 'key_value_name'
+
+class TestKeyValueName < MiniTest::Test
+  TestInteger = KeyValueName.new do |n|
+    n.key :a, type: Numeric, format: '%d'
+  end
+
+  TestHexNumeric = KeyValueName.new do |n|
+    n.key :b, type: Numeric, format: '%x'
+  end
+
+  TestFormattedNumeric = KeyValueName.new do |n|
+    n.key :c, type: Numeric, format: '%.3f', scan_format: '%f'
+  end
+
+  TestPaddedNumeric = KeyValueName.new do |n|
+    n.key :d, type: Numeric, format: '%04d'
+  end
+
+  TestSymbol = KeyValueName.new do |n|
+    n.key :a, type: Symbol
+  end
+
+  TestFloat = KeyValueName.new do |n|
+    n.key :a, type: Numeric
+  end
+
+  TestTwoIntegers = KeyValueName.new do |n|
+    n.include_keys TestInteger
+    n.include_keys TestHexNumeric
+  end
+
+  TestMixed = KeyValueName.new do |n|
+    n.key :id, type: Symbol
+    n.key :ordinal, type: Numeric, format: '%d'
+    n.key :value, type: Numeric
+  end
+
+  TestExtension = KeyValueName.new do |n|
+    n.key :big_number, type: Numeric, format: '%04d'
+    n.extension 'bin'
+  end
+
+  TestEKey = KeyValueName.new do |n|
+    n.key :x, type: Numeric
+    n.key :e, type: Numeric
+  end
+
+  def roundtrip(klass, string, args)
+    name = klass.read(string)
+    assert_equal args.keys, name.to_h.keys
+    args.each do |key, value|
+      assert_equal value, name[key]
+    end
+    assert_equal string, name.to_s
+    name
+  end
+
+  def test_integer_roundtrip
+    roundtrip(TestInteger, 'a-123', a: 123)
+  end
+
+  def test_hex_numeric_roundtrip
+    roundtrip(TestHexNumeric, 'b-ff', b: 255)
+  end
+
+  def test_formatted_numeric_roundtrip
+    roundtrip(TestFormattedNumeric, 'c-0.100', c: 0.1)
+    roundtrip(TestFormattedNumeric, 'c--0.200', c: -0.2)
+  end
+
+  def test_formatted_numeric_parse
+    assert_equal(-0.0013, TestFormattedNumeric.read('c--1.3e-3').c)
+  end
+
+  def test_padded_numeric_roundtrip
+    roundtrip(TestPaddedNumeric, 'd-0012', d: 12)
+  end
+
+  def test_symbol_roundtrip
+    roundtrip(TestSymbol, 'a-foo', a: :foo)
+  end
+
+  def test_symbol_accepts_strings
+    assert_equal 'a-foo', TestSymbol.new(a: 'foo').to_s
+  end
+
+  def test_float_roundtrip
+    roundtrip(TestFloat, 'a-2.25', a: 2.25)
+  end
+
+  def test_two_integers_roundtrip
+    roundtrip(TestTwoIntegers, 'a-123.b-ff', a: 123, b: 255)
+  end
+
+  def test_mixed_roundtrip
+    name = roundtrip(
+      TestMixed,
+      'id-foo.ordinal-1234.value-2.5e-11',
+      id: :foo, ordinal: 1234, value: 2.5e-11
+    )
+    assert_equal :foo, name.id
+    assert_equal 1234, name.ordinal
+    assert_equal 2.5e-11, name.value
+  end
+
+  def test_extension_roundtrip
+    roundtrip(TestExtension, 'big_number-0123.bin', big_number: 123)
+  end
+
+  def test_e_key_roundtrip
+    # A file name called `x-1.e-2` could mean `x=1e-2` or `x=1`, `e=2`. It's
+    # still possible to distinguish between them if we know that we're looking
+    # for two keys.
+    roundtrip(TestEKey, 'x-1.e-2', x: 1, e: 2)
+  end
+
+  def test_missing_key
+    assert_raises do
+      TestInteger.new(b: 3)
+    end
+    assert_raises(ArgumentError) do
+      TestInteger.read('b-3')
+    end
+  end
+
+  def test_in_folder
+    assert_equal File.join('foo', 'a-1'), TestInteger.new(a: 1).in('foo')
+  end
+
+  def test_glob_with_integers
+    Dir.mktmpdir do |tmp|
+      FileUtils.touch TestInteger.new(a: 1).in(tmp)
+      FileUtils.touch TestInteger.new(a: 2).in(tmp)
+      names = TestInteger.glob(tmp).sort_by(&:a)
+      assert_equal 2, names.size
+      assert_equal 1, names[0].a
+      assert_equal 2, names[1].a
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: key_value_name
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- John Lees-Miller
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+description: Store key-value pairs in file names, e.g. parameter names and parameters.
+email:
+- jdleesmiller@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/key_value_name.rb
+- lib/key_value_name/builder.rb
+- lib/key_value_name/marshalers.rb
+- lib/key_value_name/marshalers/base.rb
+- lib/key_value_name/marshalers/numeric_marshaler.rb
+- lib/key_value_name/marshalers/symbol_marshaler.rb
+- lib/key_value_name/spec.rb
+- lib/key_value_name/version.rb
+- test/key_value_name/key_value_name_test.rb
+homepage: https://github.com/jdleesmiller/key_value_name
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+- "--title"
+- key_value_name-0.0.1 Documentation
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Store key-value pairs in file names, e.g. parameter names and parameters.
+test_files:
+- test/key_value_name/key_value_name_test.rb