ytry 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1d75a68288e060261679cfd5e4e94f9185230b2b
-  data.tar.gz: 90087e023cf2c15966ccc9069af417f9e9399b9c
+  metadata.gz: 445fb840f8d15382ce1b280cdc6f746b907e2dfb
+  data.tar.gz: 559d814425ba8e70f0e23932890922d99a5393d3
 SHA512:
-  metadata.gz: 2999648ea69177c1877b2ad818946be3216eb36d1ed2283b1d33044973ade655f3a2d06b761f2d0d60c2f23ae8e589404d1d8630e167b656626dbb8b236715a7
-  data.tar.gz: 763fedbdf00f4465687b105964bead8bc3efdb8a6eb1d1bdfdda17d3c632b0b60860ef6d04a708df1eae02a17bbbc067fc067985f229c40268f15233b2c38038
+  metadata.gz: e4dcc9c8e5518b8ed3ee38e9d2c6fed5c858f6bcb64dcb72adc86e6bc61950b211d4de880cb8ed0bbbb9f79f589ea9709fda6130bfd7499599fb16c5368c4d33
+  data.tar.gz: 3d65b7ee4d84e21b90f42c84ba11a91cc27f8d26bfa3235bb9377823dfa97b7d712ad7ff74a1866b3c945b834f6daaa57307683fc3defc3e75628f20025c32d6

data/README.md

@@ -23,9 +23,64 @@ Or install it yourself as:
 
 ## Basic usage
 
-The Try type represents a computation that may either result in an exception, or return a successfully computed value ([scala-docs](http://www.scala-lang.org/api/2.11.8/index.html#scala.util.Try))
+The Try type represents a computation that may either result in an error, or return a successfully computed value.
 
-[TODO]
+If the block passed to Try runs with no errors, then a `Success` wrapping the computed value is returned.
+
+An instance of `Failure` wrapping the error is returned otherwise.
+
+```ruby
+require 'ytry'
+include Ytry
+
+Try { 1 + 1 } # Success(2)
+
+Try { 1 / 0 } # Failure(#<ZeroDivisionError: divided by 0>)
+```
+
+`Success` and `Failure` provide a unified API that lets us express a sequence of tranformations in a fluent way, without error handling cluttering the flow:
+
+```ruby
+def load_and_parse json_file
+  Try { File.read(json_file) }
+    .map {|content| JSON.parse(content)}
+    .select {|table| table.is_a? Array}
+    .recover {|e| puts "Recovering from #{e.message}"; []}
+end
+
+load_and_parse(nonexisting_file) # prints "Recovering from No such file..." # Success([])
+
+load_and_parse(wrong_format_file) # prints "Recovering from Element not found" # Success([])
+
+load_and_parse(actual_file) # Success([{"id"=>1, "name"=>"Lorenzo", "dob"=>"22/07/1985"}])
+```
+
+`Try#map` and `Try#recover` are means to interact with the value wrapped by a Try in a safe way - i.e. with no risk of errors being raised.
+
+`Try#select` transforms a Success into a Failure when the underlying value does not satisfy the given predicate - i.e. the given block returns false. That can be useful when validating some input.
+
+`Try#get_or_else` provides a safe way of retrieving the possibly-missing value it contains. It returns the result of the given block when the Try is a Failure. It is equivalent to `Try#get` when the Try is a Success.
+
+```ruby
+invalid_json = "[\"missing_quote]"
+
+Try { JSON.parse(invalid_json) }
+  .get_or_else{ [] } # []
+
+Try { JSON.parse("[]") }
+  .get_or_else { fail "this block is ignored"} # []
+```
+
+It is preferable to use `Try#get_or_else` over `Try#get`, as `#get` will raise an error when called on a Failure. It is possible to check for failure via `#empty?`, but that tipically leads to non-idiomatic code
+
+## Why Try?
+
+Using Try instead of rescue blocks can make your software both clearer and safer as it
+
+- leads to less verbose error handling
+- simplifies the way we deal with operations that might fail for several reasons (such as IO operations)
+- privileges method chaining thus reducing the need for auxiliary variables to store intermediate results in a computation
+- encourages programming towards immutability, where the data is transformed rather than mutated in place.
 
 ## Development
 

data/lib/ytry.rb

@@ -15,11 +15,17 @@ module Ytry
       raise Try.invalid_argument('Argument must be an array-like object', value) unless value.respond_to? :to_ary
       return value if value.is_a? Try
       value.to_ary.empty? ?
-        Failure.new(RuntimeError.new("Could not convert empty array-like object to Success")) :
+        Failure.new(RuntimeError.new("Element not found").tap{|ex| ex.set_backtrace(caller)}) :
         Success.new(value.to_ary.first)
     end
-    def each &block
-      to_ary.each &block
+    def self.zip *try_array
+      first_failure = try_array.find(&:empty?)
+      first_failure.nil? ? Success.new(try_array.map(&:get)) : first_failure
+    end
+    def each
+      return enum_for(__method__) unless block_given?
+      yield self.get unless empty?
+      return self
     end
     %i(map select reject collect collect_concat).each do |method|
       define_method method, ->(&block) {
@@ -35,17 +41,14 @@ module Ytry
       Try.ary_to_type(wrapped_result.flatten)
     end
     def grep(pattern, &block)
-      Try.ary_to_type super
+      self.empty? ? self : Try.ary_to_type(Try{super}.flatten)
     end
     def flatten
       return self if empty?
       Try.ary_to_type self.get
     end
     def zip *others
-      # TODO return first Failure among arguments - if any
-      return Failure.new(Exception.new) if self.empty? || others.any?(&:empty?)
-      collection = others.reduce(self.to_a, &:concat)
-      Success.new collection
+      Try.zip(self, *others)
     end
     def | lambda
       self.flat_map &lambda # slow but easy to read + supports symbols out of the box
@@ -94,7 +97,7 @@ module Ytry
     end
     def get() raise @error end
     def empty?() true end
-    def to_s() "Failure(#{@error})" end
+    def to_s() "Failure(#{@error.inspect})" end
     def to_ary() [] end
     def == other
       other.is_a?(Failure) && self.error == other.error

data/lib/ytry/version.rb

@@ -1,3 +1,3 @@
 module Ytry
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ytry
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - lorenzo.barasti
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-25 00:00:00.000000000 Z
+date: 2016-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler