code_error 0.9.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d3630c871f307f8a79b4c038efac86c2e7f7031
-  data.tar.gz: 9c7b3e960adb94896f0d062e5eebffc45bf77ccd
+  metadata.gz: 756c0d9596e3aae0b398e504ca18dd1b1fb0ccd3
+  data.tar.gz: 74379767b93b60733dfe447bfca14ecfd44a3b08
 SHA512:
-  metadata.gz: 0ffd780bcf90b43be9c7fa2e6c52ff973623a154ce99edeb1962c25805da98aad659e7969a5461087cd5dc5b84fd3ddae09130308c9b5b9c747a7e26931cc073
-  data.tar.gz: 225ab9e1a644db1de28e03d6b3f4518e10a39905f5868d2ab890c174240c18a342f422b8a919b57c754200a67f0f9c44d724212019aac18b4f4942b44cb782e7
+  metadata.gz: 70918bb3ff585a75edff5cd5a6fb4d674b18ff4e143b8ac6e2806bd27d0d7737b45278821ad6709a4ea8b230564be1b728f113df7b7eb6d5b397da025bc99a9a
+  data.tar.gz: 88f6a362ec25aa5dcd7eed85eeb5fdf54a6f44107d8f5adafbc4bb7441d7239e31583fac19e36b4f788bbfb5ca6a83c218a4ba4afdd7c3d208c8e74f292feed1

data/HISTORY.md

@@ -0,0 +1,4 @@
+## v1.0.0 / 2014-12-02
+
+* [Init] Initial Release
+

data/README.md

@@ -2,7 +2,15 @@
 
 A code-based customized error.
 
-    raise MyError.new(10002)
+[![Gem Version](https://badge.fury.io/rb/code_error.png)][gem]
+[![Build Status](https://travis-ci.org/sibevin/code_error.svg?branch=build)][travis]
+[![Coverage Status](https://coveralls.io/repos/sibevin/code_error/badge.png?branch=cover-check)][coverall]
+
+[gem]: https://rubygems.org/gems/code_error
+[travis]: https://travis-ci.org/sibevin/code_error
+[coverall]: https://coveralls.io/r/sibevin/code_error?branch=cover-check
+
+    raise MyError.gen(:wrong_format)
 
 ## Why?
 
@@ -16,47 +24,44 @@ It is a standard error but it provides more.
 
 ### Basic
 
-Inherit CodeError::Base to create your own code-based error. You need to implement the "error_codes" method which provides a hash to define your own error code map.
+Inherit CodeError::Base to create your own code-based error. You need to assign "error_codes" with a hash to define your own error code map.
 
     class MyError < CodeError::Base
 
-      private
-
-      def error_codes
-        {
-          20001 => {
-            status: :failed,
-            msg: 'Purchase information format is incorrect.'
-          },
-          20002 => {
-            status: :failed,
-            msg: 'Device information format is incorrect.'
-          },
-          20003 => {
-            status: :failed,
-            msg: 'Unknown store.'
-          },
-          20100 => {
-            status: :duplicated,
-            msg: 'A duplicated IAP request is sent.'
-          },
-          20200 => {
-            status: :retry,
-            msg: 'Client should send the IAP request again.'
-          }
+      error_codes({
+        purchase_info_incorrect: {
+          status: :failed,
+          msg: 'Purchase information format is incorrect.'
+        },
+        device_info_incorrect: {
+          status: :failed,
+          msg: 'Device information format is incorrect.'
+        },
+        unknown_store: {
+          status: :failed,
+          msg: 'Unknown store.'
+        },
+        duplicated_request: {
+          status: :duplicated,
+          msg: 'A duplicated IAP request is sent.'
+        },
+        resend_iap: {
+          status: :retry,
+          msg: 'Client should send the IAP request again.'
         }
-      end
+      })
+
     end
 
 Raise an error with a code when you need.
 
-    raise MyError.new(20001)
+    raise MyError.gen(:purchase_info_incorrect)
 
 Rescue and handle it.
 
     begin
       #...
-      raise MyError.new(20001)
+      raise MyError.gen(:purchase_info_incorrect)
       #...
     rescue MyError => e
       raise e if e.internal?
@@ -75,93 +80,93 @@ Rescue and handle it.
       #...
     end
 
-### Customize error code hash
-
-A customized code-based error class need to implement the "error_codes" method which provides a hash like:
-
-    def error_codes
-      {
-        20001 => {
-          status: :failed,
-          msg: 'Purchase information format is incorrect.'
-        },
-        20002 => {
-          status: :failed,
-          msg: 'Device information format is incorrect.'
-        },
-        20003 => {
-          status: :failed,
-          msg: 'Unknown store.'
-        },
-        20100 => {
-          status: :duplicated,
-          msg: 'A duplicated IAP request is sent.',
-          masked: true
-        },
-        20200 => {
-          status: :retry,
-          msg: 'Client should send the IAP request again.'
-        }
+#### Customize error code hash
+
+A customized code-based error class need to assign the "error_codes" method with a hash like:
+
+    error_codes({
+      purchase_info_incorrect: {
+        status: :failed,
+        msg: 'Purchase information format is incorrect.'
+      },
+      device_info_incorrect: {
+        status: :failed,
+        msg: 'Device information format is incorrect.'
+      },
+      unknown_store: {
+        status: :failed,
+        msg: 'Unknown store.',
+        masked: true
+      },
+      duplicated_request: {
+        status: :duplicated,
+        msg: 'A duplicated IAP request is sent.',
+        masked: true
+      },
+      resend_iap: {
+        status: :retry,
+        msg: 'Client should send the IAP request again.'
       }
-    end
+    })
 
-where keys are the supported codes and each value is an another hash to store the code information corresponding each codes. The code information hash contains the following keys:
+where the hash key is the supported code which can be a symbol, number or string and the hash value is an another hash to store the code information corresponding each codes. The code information hash contains the following keys:
 
 * :status - [any type you like] The error status to define the error handling flow. You can get it by calling the "status" method.
-* :msg - [String] The error message. You can get it by calling the "msg" method.
-* :masked - (optional)[Boolean] To define the error message is masked by default or not. The default value is false if no `:masked` is given.
+* :msg - [String] The error message. You can get it by calling the `msg` method.
+* :masked - [Boolean] To define the error message is masked by default or not. The default value is `false`. Please see [Mask the error message].
+* :pos - [:none,:append,:prepend] Define how to show the code in the error message. The default value is `:none`. Please see [Show code in the error message].
 
-### Raise a code-based error
+#### Raise a code-based error
 
-Once you define the error_codes method, raising a code-based error is easy.
+Once you setup the error codes, raising a code-based error is easy.
 
-    raise MyError.new(20001)
+    raise MyError.gen(:purchase_info_incorrect)
 
-There are three argments in the new method, `MyError.new(code, msg, info)`. If the given code is defined in the error_codes, the error would contain the corresponding status and msg.
+There are two argments in the code error constructor, `MyError.gen(code, options)`. If the given code is defined in the error_codes, the error would contain the corresponding status and msg.
 
-    e = MyError.new(20001)
-    e.code # 20001
+    e = MyError.gen(:purchase_info_incorrect)
+    e.code # :purchase_info_incorrect
     e.status # :failed
-    e.msg # "Purchase information format is incorrect.(20001)"
+    e.msg # "Purchase information format is incorrect."
 
-You can give another string in "msg" arg to overwrite the original message:
+You can give another string with the "msg" option to overwrite the original message:
 
-    e = MyError.new(20001, "The another message which would override the original one.")
-    e.code # 20001
+    e = MyError.gen(:purchase_info_incorrect, msg: "The another message which would override the original one.")
+    e.code # :purchase_info_incorrect
     e.status # :failed
-    e.msg # "The another message which would override the original one.(20001)"
+    e.msg # "The another message which would override the original one."
 
 If the given code is unknown, the error would become an internal error, i.e., the status is the `:internal` status.
 
-    e = MyError.new(1111)
-    e.code # 1111
+    e = MyError.gen(:unknown_error)
+    e.code # :unknown_error
     e.status # :internal
-    e.msg # "An internal error occurs.(1111)"
+    e.msg # "An internal error occurs."
     e.internal? # true
 
 If a string is given, the error is also an internal error, but the "msg" would keep this string.
 
-    e = MyError.new("Invalid input!!")
-    e.code # 99999
+    e = MyError.gen("Invalid input!!")
+    e.code # :internal_error
     e.status # :internal
-    e.msg # "Invalid input!!"(99999)
+    e.msg # "Invalid input!!"
     e.internal? # true
 
-You can pass anything to the error handling you want through the "info" arg.
+You can pass anything you want to the error handling through the "info" option.
 
     something = 'what you want...'
-    e = MyError.new(20001, nil, something)
+    e = MyError.gen(:purchase_info_incorrect, info: something)
     e.info # 'what you want...'
 
 There is a special code `:success` which used in the success case.
 
-    e = MyError.new(:success)
-    e.code # 0
+    e = MyError.gen(:success)
+    e.code # :success
     e.status # :success
     e.msg # ""
     e.internal? # false
 
-### Handle the code-base error
+#### Handle the code-base error
 
 When you rescue a code-based error, some useful methods are ready to use.
 
@@ -174,147 +179,91 @@ When you rescue a code-based error, some useful methods are ready to use.
 
 Here is an example:
 
-    e = MyError.new(20001, nil, 'some information')
-    e.code # 20001
+    e = MyError.gen(:purchase_info_incorrect, info: 'some information')
+    e.code # :purchase_info_incorrect
     e.status # :failed
-    e.msg # "Purchase information format is incorrect.(20001)"
+    e.msg # "Purchase information format is incorrect."
     e.info # "some information"
-    e.data # { code: 20001, status: :failed, msg: "Purchase information format is incorrect.(20001)", info: 'some information' }
+    e.data # { code: :purchase_info_incorrect, status: :failed, msg: "Purchase information format is incorrect.", info: 'some information' }
     e.internal? # false
 
 ### Configure your code-base error
 
-You can override the `config` method in your code-based error to customize the default behavior. Here is an example:
+You can customize the default behavior in your code-based error. Here is an example:
 
     class MyError < CodeError::Base
 
-      private
-
-      def error_codes
+      error_codes({
         #...
-      end
+      })
+
+      success_config({
+        code: :ok,
+        status: :success,
+        msg: "My success message."
+      })
+
+      internal_config({
+        code: :oops,
+        status: :failed,
+        msg: "My internal error message."
+      })
+
+      masked_msg "My masked message."
 
-      def config
-        super.merge({
-          success: {
-            code: CodeError::SUCCESS_CODE,
-            status: CodeError::SUCCESS_STATUS,
-            msg: "My own success message." 
-          },
-          internal: {
-            code: CodeError::INTERNAL_CODE,
-            status: CodeError::INTERNAL_STATUS,
-            msg: "My own internal error message."
-          },
-          masked_msg: "My own masked message",
-          append_code_in_msg: :none
-        })
-      end
     end
 
-where the config hash contains the following keys:
+where the configures are:
 
-* :success - Define the success code, status and message.
-* :internal - Define the internal error code, status and message.
-* :masked_msg - [String] Define the message to replace the masked one.
-* :code_in_msg - [:append/:prepend/:none] Define how to embed code in the message. The default option is :append.
+* success_config - [Hash] Define the success code, status and message. The default value is `{ code: CodeError::SUCCESS_CODE, status: CodeError::SUCCESS_STATUS, msg: "" }`.
+* internal_config - [Hash] Define the internal error code, status and message. The default value is `{ code: CodeError::INTERNAL_CODE, status: CodeError::INTERNAL_STATUS, msg: "" }`.
+* masked_msg - [String] Define the message to replace the masked one. The default value is `CodeError::MASKED_MSG`.
+* masked - [Boolean] To define the error message is masked by default or not. The default value is `false`. Please see [Mask the error message].
+* pos - [:none,:append,:prepend] Define how to show the code in the error message. The default value is `:none`. Please see [Show code in the error message].
 
-### Mask the error message
+#### Mask the error message
 
 You can mask an error message if you don't want to show it. A masked message would be replaced with the default masked message. There are several ways to do it, they are listed below sorted by the precedence.
 
-* Pass `true` to the "masked" arg in the "msg" or "data" method.
+* Pass `masked: true` to the `msg` or `data` method.
 
-    e = MyError.new(20001)
-    e.msg(ture) # "An error occurs.(20001)"
-    e.data(true) # { code: 20001, status: :failed, msg: "An error occurs.(20001)", info: {} }
+    e = MyError.gen(:purchase_info_incorrect)
+    e.msg(masked: ture) # "An error occurs."
+    e.data(masked: true) # { code: :purchase_info_incorrect, status: :failed, msg: "An error occurs.", info: {} }
 
-* Pass the `:masked` to the "msg" arg in the "new" method. 
+* Pass the `masked: true` to the `gen` method.
 
-    e = MyError.new(20001, :masked)
-    e.msg # "An error occurs.(20001)"
+    e = MyError.gen(:purchase_info_incorrect, masked: true)
+    e.msg # "An error occurs."
 
 * Add `masked: true` in the error_codes hash for particular error. Please see [Customize error code hash].
 
-The default masked message can be customized to your own message by overwriting the `:masked_msg` in your config hash. Please see [Configure your code-base error].
+* Call `masked true` in your error class. Please see [Configure your code-base error].
 
-## I18n
+The default masked message can be customized to your own message by calling the `masked_msg` in your error class. Please see [Configure your code-base error].
 
-We don't support the i18n for simpleness but you can do it yourself. Here is an example:
+#### Show code in the error message
 
-    class MyError < CodeError::Base
+You can show code in the error message by giving a `pos` option. The supported options are `:none`, `:append`, and `:prepend`.
 
-      private
-
-      def error_codes
-        {
-          20001 => {
-            status: :failed,
-            msg: 'code_error.my_error.purchase_info_incorrect' 
-          },
-          20002 => {
-            status: :failed,
-            msg: 'code_error.my_error.device_info_incorrect'
-          },
-          20003 => {
-            status: :failed,
-            msg: 'code_error.my_error.unknown_store'
-          },
-          20100 => {
-            status: :duplicated,
-            msg: 'code_error.my_error.duplicated_request' 
-          },
-          20200 => {
-            status: :retry,
-            msg: 'code_error.my_error.retry'
-          }
-        }
-      end
+* :none - (Default) Don't show code in the error message.
+* :append - Append the code after the error message. For example: "Purchase information format is incorrect. (purchase_info_incorrect)"
+* :prepend - Prepend the code before the error message. For example: "(purchase_info_incorrect) Purchase information format is incorrect."
 
-      def config
-        super.merge({
-          success: {
-            code: CodeError::SUCCESS_CODE,
-            status: CodeError::SUCCESS_STATUS,
-            msg: 'code_error_my_error.success_msg' 
-          },
-          internal: {
-            code: CodeError::INTERNAL_CODE,
-            status: CodeError::INTERNAL_STATUS,
-            msg: 'code_error_my_error.internal_msg' 
-          },
-          masked_msg: 'code_error_my_error.masked_msg',
-          append_code_in_msg: :append
-        })
-      end
-    end
+Same as the "mask" feature, there are several ways to do it, they are listed below sorted by the precedence.
 
-    def show_message(code, msg, masked = false)
-      masked = masked || @masked || false
-      m = masked ? I18n.t(config[:masked_msg]) : I18n.t(msg)
-      code_in_msg = config[:code_in_msg]
-      if code != config[:success][:code]
-        if code_in_message == :append
-          m = I18n.t('code_error.my_error.append_code_msg', msg: m, code: code)
-        elsif code_in_message == :prepand
-          m = I18n.t('code_error.my_error.prepend_code_msg', msg: m, code: code)
-        end
-      end
-      m
-    end
+* Pass `pos` option to the `msg` or `data` method.
+
+    e = MyError.gen(:purchase_info_incorrect)
+    e.msg(pos: :append) # "Purchase information format is incorrect. (purchase_info_incorrect)"
+    e.data(pos: :prepend, masked: true) # { code: :purchase_info_incorrect, status: :failed, msg: "(purchase_info_incorrect) An error occurs.", info: {} }
+
+* Pass the `pos` option to the `gen` method.
 
-And the i18n yml file is:
+    e = MyError.gen(:purchase_info_incorrect, pos: :append)
+    e.msg # "Purchase information format is incorrect. (purchase_info_incorrect)"
 
-    en:
-      code_error:
-        my_error:
-          append_code_msg: "%{msg}(%{code})"
-          prepend_code_msg: "(%{code})%{msg}"
-          purchase_info_invalid: "Purchase information format is incorrect."
-          device_info_invalid: "Device information format is incorrect."
-          unknown_store: "Unknown Store."
-          duplicated_request: "A duplicated IAP request is sent."
-          retry: "Client should send the IAP request again."
+* Call `pos` in your error class. Please see [Configure your code-base error].
 
 ## Test
 
@@ -328,4 +277,4 @@ Sibevin Wang
 
 ## Copyright
 
-Copyright (c) 2013 Sibevin Wang. Released under the MIT license.
+Copyright (c) 2013 - 2014 Sibevin Wang. Released under the MIT license.