key_value_name 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c1f8780bde799ea40e2fd042acd3893a16d506b1
-  data.tar.gz: 0c8a821f32cf6cbdd8681c559f27498011d64e25
+SHA256:
+  metadata.gz: 3200bf0b2afdca95befb7a8ec9a3a5d6b815a68930726d6db4bb2df4767349be
+  data.tar.gz: a54d7369f421aa7ab93c0b4fae6258137c1a6e600656743ef9ce816b91a307a5
 SHA512:
-  metadata.gz: b13cf37a899c2be009c01cc3f94da5068bc2c495901f217d72f715444e8118f191cb96fcf9553527ac4f3f5879220c1a898e6a93d6c2545c8908462cf8dc8e34
-  data.tar.gz: eee937f19b07d827f3bd5bdf65b7c1b93935e8d4fe7f222b85c3f3e7afa0be570d008b1466db312ebff6bfab378e40c9e4712ca437e31e8ebd43318b470af650
+  metadata.gz: fa23bbc6568751705862b8c6d91eee57e0ab8ffd6a3d0a05c31bd7c07fd3094026b05d3bb4e3b19caa01e97572bf0f1c3e434d21dc2eb005fdac70ada2165105
+  data.tar.gz: ecf477eea90b3c33c30cf343d8a8bfa4ff87be743a674a28f1f45e81fe44980da6380dabd7a9f68085dd5a8ba35e105d8de290fdb28cc60087d7d47442d32b74

data/README.md

@@ -4,7 +4,7 @@
 
 ## Synopsis
 
-Store key-value pairs in file names, for example parameter names and parameters for experiments or simulation runs.
+An 'object-file system mapper' for managing data files. Key-value pairs describing the data in each file are stored in its name. Useful for managing data files for experiments or simulation runs.
 
 This gem provides:
 
@@ -12,32 +12,45 @@ This gem provides:
 
 2. Automatic formatting and type conversion for the parameters.
 
+3. A schema builder to organize files and folders and declare what parameters are allowed.
+
 ## 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
+Results = KeyValueName.schema do
+  folder :simulation do
+    key :seed, type: Integer, format: '%06d'
+    key :algorithm, type: Symbol
+    key :alpha, type: Float
+
+    file :stats, :csv
+  end
 end
 
-name = ResultName.new(
+results = Results.new(root: 'data/results')
+
+sim = results.simulation.new(
   seed: 123,
   algorithm: :reticulating_splines,
   alpha: 42.1)
 
-name.to_s
-# => seed-123.algorithm-reticulating_splines.alpha-42.1.dat
+sim.to_s
+# => "data/results/simulation-seed-000123.algorithm-reticulating_splines.alpha-42.1"
+
+sim.stats_csv.to_s
+# => "data/results/simulation-seed-000123.algorithm-reticulating_splines.alpha-42.1/stats.csv"
+
+# Pretend we've run a simulation and written the results...
+sim.stats_csv.touch!
 
-name.in('/tmp')
-# => /tmp/seed-123.algorithm-reticulating_splines.alpha-42.1.dat
+# List the results
+results.simulation.all
+# => [#<struct Results::Simulation seed=123, algorithm=:reticulating_splines, alpha=42.1>]
 
-# Assuming a matching file exists in /tmp.
-ResultName.glob('/tmp')
-# => [#<struct ResultName seed=123, algorithm=:reticulating_splines, alpha=42.1>]
+results.simulation.all.map(&:stats_csv).map(&:to_s)
+# => ["data/results/simulation-seed-000123.algorithm-reticulating_splines.alpha-42.1/stats.csv"]
 ```
 
 ## INSTALLATION
@@ -50,7 +63,7 @@ gem install key_value_name
 
 (The MIT License)
 
-Copyright (c) 2017 John Lees-Miller
+Copyright (c) 2017-2025 John Lees-Miller
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/key_value_name/builders/container_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # TODO
+  #
+  module ContainerBuilder
+    def file(...)
+      @builders << FileBuilder.new(...)
+    end
+
+    def folder(...)
+      @builders << FolderBuilder.new(...)
+    end
+
+    def extend_with_builders(klass)
+      @builders.each do |builder|
+        child_class = builder.build
+        klass.const_set(builder.class_name, child_class)
+        if builder.singular?
+          build_singular(builder, klass, child_class)
+        else
+          build_collection(builder, klass, child_class)
+        end
+      end
+      klass
+    end
+
+    private
+
+    def build_singular(builder, klass, child_class)
+      klass.class_eval do
+        define_method(builder.name) do
+          child = child_class.new
+          child.parent = self
+          child
+        end
+      end
+    end
+
+    def build_collection(builder, klass, child_class)
+      klass.class_eval do
+        define_method(builder.name) do
+          Collection.new(child_class, self)
+        end
+      end
+    end
+  end
+end

data/lib/key_value_name/builders/file_builder.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Build a file KeyValueName.
+  #
+  class FileBuilder < KeyValueBuilder
+    def initialize(name, *extension, class_name: nil, &block)
+      KeyValueName.check_symbol(name) if name
+      @name = name
+      @extension = extension
+      @class_name = class_name
+      super(&block)
+    end
+
+    def extension(extension)
+      raise 'extension already set' if @extension.any?
+      @extension = Array(extension)
+    end
+
+    def name
+      name_parts.join('_').to_sym
+    end
+
+    def class_name
+      @class_name || default_class_name
+    end
+
+    def build
+      klass = super
+      klass.class_eval do
+        include FileName::InstanceMethods
+
+        class <<self
+          include FileName::ClassMethods
+        end
+      end
+      klass.key_value_name_spec = make_spec
+      klass
+    end
+
+    private
+
+    def name_parts
+      [@name] + @extension
+    end
+
+    def default_class_name
+      name_parts.map { |part| KeyValueName.camelize(part) }.join('')
+    end
+
+    def make_spec
+      prefix = @name
+      prefix = "#{prefix}#{KEY_VALUE_SEPARATOR}" if prefix && @marshalers.any?
+      suffix = ".#{@extension.join('.')}" if @extension.any?
+      Spec.new(@marshalers, prefix, suffix)
+    end
+  end
+end

data/lib/key_value_name/builders/folder_builder.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Build a folder KeyValueName.
+  #
+  class FolderBuilder < KeyValueBuilder
+    include ContainerBuilder
+
+    def initialize(name, class_name: nil, &block)
+      KeyValueName.check_symbol(name)
+      @name = name
+      @class_name = class_name
+      @builders = []
+      super(&block)
+    end
+
+    attr_reader :name
+
+    def class_name
+      @class_name || KeyValueName.camelize(name)
+    end
+
+    def build
+      klass = super
+      klass.class_eval do
+        include FolderName::InstanceMethods
+
+        class <<self
+          include FolderName::ClassMethods
+        end
+      end
+      klass.key_value_name_spec = make_spec
+      extend_with_builders(klass)
+    end
+
+    private
+
+    def make_spec
+      prefix = @name
+      prefix = "#{prefix}#{KEY_VALUE_SEPARATOR}" if prefix && @marshalers.any?
+      Spec.new(@marshalers, prefix)
+    end
+  end
+end

data/lib/key_value_name/builders/key_value_builder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Yield-based Domain-Specific Language (DSL) to build a `KeyValueName`.
+  #
+  class KeyValueBuilder
+    def initialize(&block)
+      @marshalers = {}
+      instance_eval(&block) if block_given?
+    end
+
+    def singular?
+      @marshalers.none?
+    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)
+      KeyValueName.check_marshaler(type)
+      check_no_existing_marshaler(name)
+      @marshalers[name] = MARSHALERS[type].new(**kwargs)
+    end
+
+    def build
+      struct_args = @marshalers.any? ? @marshalers.keys : [nil]
+      Struct.new(*struct_args, keyword_init: true)
+    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/builders/schema_builder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # The root builder. Can contain files and folders only.
+  #
+  class SchemaBuilder
+    include ContainerBuilder
+
+    def initialize(&block)
+      @builders = []
+      instance_eval(&block)
+    end
+
+    def build
+      extend_with_builders(Class.new(Schema))
+    end
+  end
+end

data/lib/key_value_name/collection.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # A collection of KeyValueNames.
+  #
+  class Collection
+    include Enumerable
+
+    def initialize(klass, parent)
+      @klass = klass
+      @parent = parent
+    end
+
+    def new(*args)
+      object = @klass.new(*args)
+      object.parent = @parent
+      object
+    end
+
+    def each(&block)
+      all.each(&block)
+    end
+
+    def all
+      @klass.glob(@parent).sort
+    end
+
+    def where(**kwargs)
+      all.select do |name|
+        kwargs.all? do |key, value|
+          name[key] == value
+        end
+      end
+    end
+
+    def find_by(**kwargs)
+      where(**kwargs).first
+    end
+  end
+end

data/lib/key_value_name/marshalers/base.rb

@@ -5,19 +5,22 @@ module KeyValueName
   # A Marshaler handles conversion of typed values to and from strings.
   #
   class MarshalerBase
-    def initialize(**kwargs)
-    end
+    def initialize(**kwargs) end
 
     def matcher
       raise NotImplementedError
     end
 
-    def read(_string)
+    def parse(_string)
       raise NotImplementedError
     end
 
-    def write(_value)
+    def generate(_value)
       raise NotImplementedError
     end
+
+    def to_comparable(value)
+      value
+    end
   end
 end

data/lib/key_value_name/marshalers/boolean_marshaler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Read and write a boolean flag.
+  #
+  class BooleanMarshaler < MarshalerBase
+    def matcher
+      /true|false/i
+    end
+
+    def parse(string)
+      string == 'true'
+    end
+
+    def generate(value)
+      value ? 'true' : 'false'
+    end
+
+    def to_comparable(value)
+      value ? 1 : 0
+    end
+  end
+end

data/lib/key_value_name/marshalers/float_marshaler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Read and write float types.
+  #
+  class FloatMarshaler < MarshalerBase
+    def initialize(format: '%g')
+      @format_string = format
+    end
+
+    attr_reader :format_string
+
+    def matcher
+      /[-+]?[0-9]*\.?[0-9]+(?:e[-+]?[0-9]+)?/i
+    end
+
+    def parse(string)
+      string.to_f
+    end
+
+    def generate(value)
+      format(format_string, value.to_s)
+    end
+  end
+end

data/lib/key_value_name/marshalers/integer_marshaler.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module KeyValueName
+  #
+  # Read and write integer types. Positive binary, octal and hexadecimal numbers
+  # without prefixes are also supported. Padding with zeros is OK, but padding
+  # with spaces will not work.
+  #
+  class IntegerMarshaler < MarshalerBase
+    def initialize(format: '%d')
+      @format_string = format
+    end
+
+    attr_reader :format_string
+
+    def matcher
+      /[-+]?[0-9a-f]+/i
+    end
+
+    def base
+      case format_string
+      when /b\z/i then 2
+      when /o\z/i then 8
+      when /x\z/i then 16
+      else 10
+      end
+    end
+
+    def parse(string)
+      string.to_i(base)
+    end
+
+    def generate(value)
+      format(format_string, value)
+    end
+  end
+end

data/lib/key_value_name/marshalers/symbol_marshaler.rb

@@ -9,11 +9,11 @@ module KeyValueName
       KEY_RX
     end
 
-    def read(string)
+    def parse(string)
       string.to_sym
     end
 
-    def write(value)
+    def generate(value)
       KeyValueName.check_symbol(value)
       value.to_s
     end

data/lib/key_value_name/marshalers.rb

@@ -1,11 +1,23 @@
 # frozen_string_literal: true
+
 require_relative 'marshalers/base'
-require_relative 'marshalers/numeric_marshaler'
+require_relative 'marshalers/boolean_marshaler'
+require_relative 'marshalers/float_marshaler'
+require_relative 'marshalers/integer_marshaler'
 require_relative 'marshalers/symbol_marshaler'
 
+#
+#
+#
 module KeyValueName
   MARSHALERS = {
-    Numeric => NumericMarshaler,
+    boolean: BooleanMarshaler,
+    Float => FloatMarshaler,
+    Integer => IntegerMarshaler,
     Symbol => SymbolMarshaler
   }.freeze
+
+  def self.check_marshaler(type)
+    raise ArgumentError, "bad type: #{type}" unless MARSHALERS.key?(type)
+  end
 end

data/lib/key_value_name/mixins/file_name.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module KeyValueName
+  module FileName
+    #
+    # Instance method mixin for a file.
+    #
+    module InstanceMethods
+      include Name::InstanceMethods
+
+      def exist?
+        File.exist?(to_s)
+      end
+
+      #
+      # Ensure that the parent folder exists.
+      #
+      # @return [self]
+      #
+      def mkdir!
+        parent.mkdir!
+        self
+      end
+
+      def touch!
+        retried ||= false
+        FileUtils.touch(to_s)
+        self
+      rescue Errno::ENOENT
+        FileUtils.mkdir_p(File.dirname(to_s))
+        raise if retried
+        retried = true
+        retry
+      end
+
+      def destroy!
+        FileUtils.rm_f(to_s)
+      end
+    end
+
+    #
+    # Class methods of the returned `KeyValueName` class.
+    #
+    module ClassMethods
+      include Name::ClassMethods
+    end
+  end
+end

data/lib/key_value_name/mixins/folder_name.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module KeyValueName
+  module FolderName
+    #
+    # Instance methods of a KeyValueName for a folder.
+    #
+    module InstanceMethods
+      include Name::InstanceMethods
+
+      def exist?
+        Dir.exist?(to_s)
+      end
+
+      def mkdir!
+        FileUtils.mkdir_p(to_s)
+        self
+      end
+
+      def destroy!
+        FileUtils.rm_rf(to_s)
+      end
+    end
+
+    #
+    # Class methods of the returned `KeyValueName` class.
+    #
+    module ClassMethods
+      include Name::ClassMethods
+    end
+  end
+end

data/lib/key_value_name/mixins/name.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module KeyValueName
+  module Name
+    #
+    # Instance method mixin for a KeyValueName.
+    #
+    module InstanceMethods
+      attr_accessor :parent
+
+      def to_s
+        result = self.class.key_value_name_spec.generate(self)
+        if parent
+          File.join(parent.to_s, result)
+        else
+          result
+        end
+      end
+
+      def <=>(other)
+        self.class.key_value_name_spec.compare(self, other)
+      end
+    end
+
+    #
+    # Class methods of the returned `KeyValueName` class.
+    #
+    module ClassMethods
+      attr_accessor :key_value_name_spec
+
+      def parse_to_hash(name)
+        key_value_name_spec.parse(name)
+      end
+
+      def parse(name)
+        new(parse_to_hash(name))
+      end
+
+      def glob(parent)
+        Dir.glob(File.join(parent.to_s, key_value_name_spec.glob)).map do |name|
+          basename = File.basename(name)
+          next unless key_value_name_spec.matches?(basename)
+          name = parse(basename)
+          name.parent = parent
+          name
+        end.compact
+      end
+    end
+  end
+end

data/lib/key_value_name/schema.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+module KeyValueName
+  #
+  # Base class for user-defined schemas.
+  #
+  class Schema
+    def initialize(root:)
+      @root = root
+    end
+
+    def to_s
+      @root
+    end
+
+    def parent
+      nil
+    end
+
+    def mkdir!
+      Dir.mkdir_p(to_s)
+    end
+  end
+end