physical 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f89e02fd4f91f6d5c79999264b3ff44fb8d60b7b
-  data.tar.gz: d71b79a2cc53f21c8e1a2d42fc62a29c823e6ec9
+  metadata.gz: fdda01f27d8c75a1b222e13ca9f84e54e1f2a4c0
+  data.tar.gz: ee3cdd019c063a04141e29a6a1e83f2d25d3b483
 SHA512:
-  metadata.gz: 3dcd6833ee6c653af7e7a8aca7f9ccf535e5725ef5dd31b41f90572f99b3f470457caf7bdadcf85495c3523f85a610cfc8ffdbf62a61ac039792bac8a64848dc
-  data.tar.gz: c2dff46cb937bc709f4df6f8b06551c3112bd34198086033fdc3df12b593755b4f7e3bf66b2c9948231cfd4681cc6076eccb5edcdcb2d3eeeceb023eb14c66f2
+  metadata.gz: 48f2da61f204e7ebb71339f5be3c0379928121ce1a94af7e2cc84179e49331789d8316a85fe66c3d1f45557a1089595df1a4ee990634abd4dc30e7f27303edc4
+  data.tar.gz: a3170e37c25c1d677bb2028d31bdc8905c4418b3fdb9ff49cf81c9deb7a73faa4e87463ce4b4cdc3a3fb45a42fe98a4dcd6a27bdc1e3245fe74e1f5ed820bbfd

data/README.md

@@ -34,42 +34,108 @@ Or install it yourself as:
 
 ## Usage
 
+### Basic Package
+
+A basic Package has no items and is simply assigned a weight and dimensions. Weights and Dimensions have to be given as `Measured::Weight` or as an Array of `Measured::Length` objects:
+
 ```ruby
-one_sku = Physical::Item.new(
+Physical::Package.new(
+  weight: Measured::Weight(1, :pound),
+  dimensions: [
+    Measured::Length(3, :inch),
+    Measured::Length(4, :inch),
+    Measured::Length(5, :inch)
+  ]
+)
+```
+You will be able to retrieve the package's weight and dimensions using the `#weight` and `#dimensions` attribute reader methods.
+
+### Convenience methods
+
+The length, width and height of a package are defined as the package's longest, middle, and shortest side, respectively. For the package from the previous example, `package.length` will be 5 inches, `package.width` will be 4 inches, and `package.height` will be 3 inches. Packages do not have a notion of "right side up" yet.
+
+The package's `length` is also accessible as `package.x`. The package's `width` is also accessible as `package.y`. The package's `height` is also accessible as `package.z` as well as `package.depth`.
+
+### Packages with Items
+
+The following example is a somewhat more elaborate package: We know the items inside! `Physical::Item` objects are Cuboids, so they have three dimensions and a weight. They also have a `properties` hash that can hold things like any hazardous properties that might impede shipping.
+
+
+```ruby
+sku_one = Physical::Item.new(
   id: '12345',
-  dimensions: [2, 4, 5],
-  dimension_unit: :inch,
-  weight: 1,
-  weight_unit: :kg
+  dimensions: [
+    Measured::Length(2, :inch),
+    Measured::Length(4, :inch),
+    Measured::Length(5, :inch)
+  ],
+  weight: Measured::Weight(1, :kg),
 )
 
-two_sku = Physical::Item.new(
+sku_two = Physical::Item.new(
   id: "54321",
-  dimensions: [1, 1, 1],
-  dimension_unit: :cm,
-  weight: 2.3,
-  weight_unit: :g
+  dimensions: [
+    Measured::Length(1, :cm),
+    Measured::Length(1, :cm),
+    Measured::Length(1, :cm)
+  ],
+  weight: Measured::Weight(23, :g)
+)
+```
+
+You can initialize a package with items as follows:
+
+```ruby
+package_with_items = Physical::Package.new(
+  items: [sku_one, sku_two]
 )
+```
+
+This package has no defined container. This means we assume a box that is infinitely large, and that has zero weight. Thus the weight of this `package_with_items` will be 1023 gram (1 kg + 23 g = 1000 g + 23 g).
 
+### Packages with Boxes
+
+A package also has a box that wraps it. This box is assumed to be a Cuboid, too - but one that has inner dimensions, and a weight that is it's own weight which must be added to any item's weight in order to find out the total weight of a package.
+
+```ruby
 my_carton = Physical::Box.new(
-  dimensions: [10, 15, 15],
-  dimension_unit: :cm,
-  weight: 0.8,
-  weight_unit: :lbs
+  dimensions: [
+    Measured::Length(10, :cm),
+    Measured::Length(15, :cm),
+    Measured::Length(15, :cm)
+  ],
+  inner_dimensions: [
+    Measured::Length(9, :cm),
+    Measured::Length(14, :cm),
+    Measured::Length(14, :cm)
+  ],
+  weight: Measured::Weight(350, :g),
 )
+```
 
+If you create a carton and omit the inner dimensions, we will assume that the carton's inner dimensions are equal to its outer dimensions. This will, in many cases, be good enough (but in some you'll need the extra precision).
+
+### Calculating Void Fill
+
+For an elaborate package with a container box and items, we still cannot find out the full weight of the package without taking into account void fill (styrofoam, bubble wrap or crumpled newspaper maybe). We can instruct the package to fill up all the volume not used up by items with void fill. You can pass the density as a `Measured::Weight` object that refers to the weight of 1 cubic centimeter of void fill:
+
+```ruby
 package = Physical::Package.new(
   id: "my_package",
   container: my_carton,
-  items: [one_sku, two_sku],
-  void_fill_density: 0.007
+  items: [sku_one, sku_two],
+  void_fill_density: Measured::Weight(0.007, :g)
 )
+```
+
+In this case, the package's weight will be slightly above the sum of carton weight and the sum of item weights, as we incorporate the approximate weight of the void fill material:
 
+```ruby
 package.weight
-=> #<Measured::Weight: 1376.32851808 #<Measured::Unit: g (gram, grams)>>
+=> #<Measured::Weight: 1380.75262208 #<Measured::Unit: g (gram, grams)>>
 
 package.remaining_volume
-=> #<Measured::Volume: 1593.51744 #<Measured::Unit: ml (milliliter, millilitre, milliliters, millilitres) 1/1000 l>>
+=> #<Measured::Volume: 1107.51744 #<Measured::Unit: ml (milliliter, millilitre, milliliters, millilitres) 1/1000 l>>
 ```
 ## Development
 

data/lib/physical/box.rb

@@ -5,5 +5,27 @@ require 'measured'
 module Physical
   class Box < Cuboid
     DEFAULT_LENGTH = BigDecimal::INFINITY
+    attr_reader :inner_dimensions,
+                :inner_length,
+                :inner_width,
+                :inner_height
+
+    def initialize(inner_dimensions: [], **args)
+      super args
+      @inner_dimensions = fill_dimensions(Types::Dimensions[inner_dimensions])
+      @inner_length, @inner_width, @inner_height = *@inner_dimensions.reverse
+    end
+
+    alias :inner_x :inner_length
+    alias :inner_y :inner_width
+    alias :inner_z :inner_height
+    alias :inner_depth :inner_height
+
+    def inner_volume
+      Measured::Volume(
+        inner_dimensions.map { |d| d.convert_to(:cm).value }.reduce(1, &:*),
+        :ml
+      )
+    end
   end
 end

data/lib/physical/cuboid.rb

@@ -6,11 +6,11 @@ module Physical
   class Cuboid
     attr_reader :dimensions, :length, :width, :height, :weight, :id, :properties
 
-    def initialize(id: nil, dimensions: [], dimension_unit: :cm, weight: 0, weight_unit: :g, properties: {})
+    def initialize(id: nil, dimensions: [], weight: Measured::Weight(0, :g), properties: {})
       @id = id || SecureRandom.uuid
-      @weight = Measured::Weight(weight, weight_unit)
-      @dimensions = dimensions.map { |dimension| Measured::Length.new(dimension, dimension_unit) }.sort
-      @dimensions.fill(Measured::Length(self.class::DEFAULT_LENGTH, dimension_unit), @dimensions.length..2)
+      @weight = Types::Weight[weight]
+      @dimensions = []
+      @dimensions = fill_dimensions(Types::Dimensions[dimensions])
       @length, @width, @height = *@dimensions.reverse
       @properties = properties
     end
@@ -27,5 +27,13 @@ module Physical
     def ==(other)
       id == other.id
     end
+
+    private
+
+    def fill_dimensions(dimensions)
+      dimensions.fill(dimensions.length..2) do |index|
+        @dimensions[index] || Measured::Length(self.class::DEFAULT_LENGTH, :cm)
+      end.sort
+    end
   end
 end

data/lib/physical/package.rb

@@ -5,14 +5,14 @@ module Physical
     extend Forwardable
     attr_reader :container, :items, :void_fill_density, :id
 
-    def initialize(id: nil, container: Physical::Box.new, items: [], void_fill_density: 0, void_fill_density_unit: :g)
+    def initialize(id: nil, container: nil, items: [], void_fill_density: Measured::Weight(0, :g), dimensions: nil, weight: nil, properties: {})
       @id = id || SecureRandom.uuid
-      @void_fill_density = measured_void_fill_density(void_fill_density, void_fill_density_unit)
-      @container = container
+      @void_fill_density = Types::Weight[void_fill_density]
+      @container = container || Physical::Box.new(dimensions: dimensions || [], weight: weight || Measured::Weight(0, :g), properties: properties)
       @items = Set[*items]
     end
 
-    delegate [:dimensions, :width, :length, :height, :depth, :x, :y, :z] => :container
+    delegate [:dimensions, :width, :length, :height, :depth, :x, :y, :z, :properties] => :container
 
     def <<(item)
       @items.add(item)
@@ -27,7 +27,7 @@ module Physical
     end
 
     def remaining_volume
-      container.volume - items.map(&:volume).reduce(Measured::Volume(0, :ml), &:+)
+      container.inner_volume - items.map(&:volume).reduce(Measured::Volume(0, :ml), &:+)
     end
 
     def void_fill_weight
@@ -35,14 +35,5 @@ module Physical
 
       Measured::Weight(void_fill_density.value * remaining_volume.value, void_fill_density.unit)
     end
-
-    def measured_void_fill_density(void_fill_density, void_fill_density_unit)
-      case void_fill_density
-      when Measured::Weight
-        void_fill_density
-      else
-        Measured::Weight(void_fill_density, void_fill_density_unit)
-      end
-    end
   end
 end

data/lib/physical/spec_support/factories/box_factory.rb

@@ -4,10 +4,9 @@ require 'factory_bot'
 
 FactoryBot.define do
   factory :physical_box, class: "Physical::Box" do
-    dimensions { [4, 5, 6] }
-    dimension_unit { :dm }
-    weight { 0.1 }
-    weight_unit { :kg }
+    dimensions { [4, 5, 6].map { |d| Measured::Length(d, :dm) } }
+    inner_dimensions { dimensions.map { |d| d - Measured::Length(1, :cm) } }
+    weight { Measured::Weight(0.1, :kg) }
     initialize_with { new(attributes) }
   end
 end

data/lib/physical/spec_support/factories/item_factory.rb

@@ -4,10 +4,8 @@ require 'factory_bot'
 
 FactoryBot.define do
   factory :physical_item, class: "Physical::Item" do
-    dimensions { [1, 2, 3] }
-    dimension_unit { :cm }
-    weight { 50 }
-    weight_unit { :g }
+    dimensions { [1, 2, 3].map { |d| Measured::Length(d, :cm)} }
+    weight { Measured::Weight(50, :g) }
     initialize_with { new(attributes) }
   end
 end

data/lib/physical/spec_support/factories/package_factory.rb

@@ -6,7 +6,7 @@ FactoryBot.define do
   factory :physical_package, class: "Physical::Package" do
     container { FactoryBot.build(:physical_box) }
     items { build_list(:physical_item, 2) }
-    void_fill_density { 0.01 }
+    void_fill_density { Measured::Weight(0.01, :g) }
     initialize_with { new(attributes) }
   end
 end

data/lib/physical/spec_support/shared_examples.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 RSpec.shared_examples 'a cuboid' do
-  let(:args) { {dimensions: [1.1, 2.2, 3.3].shuffle, dimension_unit: :cm} }
+  let(:args) do
+    {
+      dimensions: [
+        Measured::Length.new(1.1, :cm),
+        Measured::Length.new(2.2, :cm),
+        Measured::Length.new(3.3, :cm)
+      ].shuffle
+    }
+  end
 
   it { is_expected.to be_a(Physical::Cuboid) }
 

data/lib/physical/types.rb

@@ -0,0 +1,14 @@
+require 'measured'
+require 'dry-types'
+
+module Physical
+  module Types
+    include Dry::Types.module
+
+    Weight = Types.Instance(::Measured::Weight)
+    Length = Types.Instance(::Measured::Length)
+    Volume = Types.Instance(::Measured::Volume)
+
+    Dimensions = Types::Strict::Array.of(Length)
+  end
+end

data/lib/physical/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Physical
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

data/lib/physical.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "physical/types"
 require "physical/version"
 require "physical/cuboid"
 require "physical/box"

data/physical.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.4'
   spec.add_runtime_dependency "carmen", "~> 1.0"
   spec.add_runtime_dependency "measured", "~> 2.4.0"
+  spec.add_runtime_dependency "dry-types", "~> 1.0.0"
 
   spec.add_development_dependency "bundler", [">= 1.16", "< 3"]
   spec.add_development_dependency "factory_bot", "~> 4.8"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: physical
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Martin Meyerhoff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-13 00:00:00.000000000 Z
+date: 2019-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carmen
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -134,6 +148,7 @@ files:
 - lib/physical/spec_support/factories/package_factory.rb
 - lib/physical/spec_support/factories/shipment_factory.rb
 - lib/physical/spec_support/shared_examples.rb
+- lib/physical/types.rb
 - lib/physical/version.rb
 - physical.gemspec
 homepage: https://github.com/mamhoff/physical