kharon 0.5.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NzczMmFkMWJhZGQ5ODMwN2NjYTE2YTE0N2IxMGQzYWEzNmNiZjRmYg==
+  data.tar.gz: !binary |-
+    OTc5ZTY2MDUyOTQ0MTU4MWY4NGMxMjRlOTE4NzkyNzE5MTMxYTE3Mw==
+SHA512:
+  metadata.gz: !binary |-
+    MzZhNDIxNjY3ODI4NWY5NzA4NTU2NzZkY2QzNzJkYjI3NjM1YTI0YThiNjEz
+    NmFiNzM0NjQ1YzE1OTA5ZjQ1MjM1N2Y5YWFjODk4MTcwODMyMTIwMWRlZjlk
+    MzE1ZWIzZjhkYWYzZWZjNWM1ODdjODc5MmJiZjM0MmQ0OWE0ZGY=
+  data.tar.gz: !binary |-
+    MmNjNGU0OTlhMGI5MTBmYWI4Yzg2NGY2N2ZiZmVjMzJlNmJjODFjNjAyZDc2
+    YzljNjc1N2QyM2U5NGRmNDY5MmRkZTIzMWUyMGY4ODMzOWJhZTQ1NmFjYzQz
+    YWE1Mzc3OWU1N2NmMGNhZTMwMjExZmJlNDFjYzM3ZWUyZTlhYzg=

data/.gitignore

@@ -0,0 +1 @@
+.yardoc

data/.rspec

@@ -1,2 +1,3 @@
 --color
---format documentation
+--format html
+--out spec/results.html

data/Gemfile

@@ -1,10 +1 @@
-source "https://rubygems.org/"
-ruby   "1.9.3"
-
-gem "bson", "2.2.2"
-
-# These gems are only used for testing purposes, and shouldn't be used in another environment than the local development one.
-group :test do
-  gem "rack-test", "0.6.2"
-  gem "rspec"    , "3.0.0.beta2"
-end
+gemspec

data/Gemfile.lock

@@ -1,28 +1,41 @@
+PATH
+  remote: .
+  specs:
+    kharon (1.1.0)
+      bson (~> 2.2, >= 2.2.2)
+
 GEM
   remote: https://rubygems.org/
   specs:
-    bson (2.2.2)
+    bson (2.3.0)
     diff-lcs (1.2.5)
-    rack (1.5.2)
+    rack (1.6.1)
     rack-test (0.6.2)
       rack (>= 1.0)
-    rspec (3.0.0.beta2)
-      rspec-core (= 3.0.0.beta2)
-      rspec-expectations (= 3.0.0.beta2)
-      rspec-mocks (= 3.0.0.beta2)
-    rspec-core (3.0.0.beta2)
-      rspec-support (= 3.0.0.beta2)
-    rspec-expectations (3.0.0.beta2)
+    rake (10.4.2)
+    redcarpet (3.3.1)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (= 3.0.0.beta2)
-    rspec-mocks (3.0.0.beta2)
-      rspec-support (= 3.0.0.beta2)
-    rspec-support (3.0.0.beta2)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bson (= 2.2.2)
-  rack-test (= 0.6.2)
-  rspec (= 3.0.0.beta2)
+  bundler (~> 1.8)
+  kharon!
+  rack-test (~> 0.6.2)
+  rake (~> 10.0)
+  redcarpet (= 3.3.1)
+  rspec (~> 3.0, >= 3.0.0)
+  yard (~> 0.8)

data/README.md

@@ -8,7 +8,7 @@ It validates the datas in a hash given criterias about its keys, and let the exe
 
 ## Contact me
 
-For any question or advice, contact me at vincent.courtois@mycar-innovations.com. I'll answer as soon as possible, and thank you by advance for giving me some of your time.
+For any question or advice, contact me at courtois.vincent@outlook.com. I'll answer as soon as possible, and thank you by advance for giving me some of your time.
 
 ## Requirements
 
@@ -31,9 +31,11 @@ And... That's it ! Now it's installed and you can learn how to properly use it !
 Add it to your Gemfile :
 
 ```
-gem "kharon", "~> 0.4.0"
+gem "kharon", "<version>"
 ```
 
+<version> being the version of the gem you want to install.
+
 then run the following command :
 
 ```
@@ -45,29 +47,34 @@ bundle install
 Clone this repository whenether you want, go inside, then type the following command :
 
 ```
-gem install kharon-0.3.0
+gem install dist/kharon-<version>
 ```
 
+<version> being the version of the gem you want to install.
+
 The gem will be installed on your system, from then on you can use it inside your applications.
 
 ## Configuration
 
-The configuration of the module is simple, juste use the #configure method from the Kharon::Factory module as follow :
+### Use exceptions or not use exceptions, that is the question
 
-```ruby
-Kharon::Factory.configure do |configuration|
-  # Decides whether you want to use exceptions or not. Default is TRUE.
-  configuration.use_exceptions(true)
-end
+In some cases you could want to not raise an exception each and every time an error occurs in the validation process. To stop using exceptions, just type :
+
+```
+Kharon.use_exceptions(false)
 ```
 
+and put it somewhere in your application, typically in a /config/initializers/kharon.rb file for a rails application.
+
+You can put back the original behaviour by calling it and passing true as the first parameter, or no parameter, instead of false.
+
 ## Run tests
 
 This gem is tested using RSpec, to run the tests, clone the repository, go in, then type :
 
 ```
 % bundle install
-% bundle exec rspec --format documentation --color
+% bundle exec rspec
 ```
 
 ## How to use the gem
@@ -83,7 +90,7 @@ require "kharon"
 The Kharon::Validator class is the main class of this gem, it offers an interface to validate hashes and see if they fulfill requirements. first, you have to create an instance of the validator :
 
 ```ruby
-validator = Kharon::Factory.validator(hash_to_validate)
+validator = Kharon::Validator.new(hash_to_validate)
 ```
 
 Now your validator knows which hash it has to validate, now you can do :
@@ -115,9 +122,14 @@ This code is strictly equivalent to the one presented above, it uses the block s
 
 ## Full documentation
 
+### Generated documentation
+
+Generated documentation can be displayed by displaying the doc/index.html file in a browser.
+
 ### Methods
 
 Methods signification are pretty straight-forward as it validates type :
+
 - :integer
 - :numeric
 - :text
@@ -131,7 +143,7 @@ Methods signification are pretty straight-forward as it validates type :
 
 #### :any
 
-This method will validate any value associated to the given key, it's useful if you just want to pass options like :required or :dependency
+This method will validate any value associated to the given key, it's useful if you just want to pass options like :required or :dependency without checking for a particular type.
 
 #### :mongoid
 
@@ -145,7 +157,7 @@ This option can be given to say that a key has to be in the hash for it to be va
 
 #### :dependency
 
-This options say that this key needs another key to be present for the hash to be validated. It can be used with all methods.
+This option says that this key needs another key to be present for the hash to be validated. It can be used with all methods.
 
 #### :dependencies
 
@@ -191,30 +203,127 @@ This option, if not given, is set to TRUE. If given at false, doesn't extract th
 
 #### :floor
 
-The value of round must be a boolean to work properly. If given at TRUE, floor the decimal number identified by this key. This option can be used with the :numeric method.
+If given and TRUE, floors the decimal number identified by this key. This option can be used with the :numeric method.
 
 #### :ceil
 
-The value of round must be a boolean to work properly. If given at TRUE, ceil the decimal number identified by this key. This option can be used with the :numeric method.
+If given and TRUE, ceils the decimal number identified by this key. This option can be used with the :numeric method.
 
 #### :round
 
-The value of round must be an integer to work properly. If given, round the decimal number keeping the given number of digits after the comma. This option can be used with the :numeric method.
+If given, as an integer, rounds the decimal number keeping the given number of digits after the comma ; if given as a boolean, rounds the decimal number, leaving no decimal digits. This option can be used with the :numeric method.
 
 #### :regex
 
 The value of this option must be passed as a string. If given as a string, verity that the associated string matches the given regular expression. This option can be used with the :text method.
 
-### Example god damn it !
+#### :at_most
 
-Here is an example to demonstrate the power of Kharon (made with the helper) :
+The value of this option must be passed as a box. When given, this option indicates the maximum value for the associated box. The associated box can't cross any of these coordinates.
 
-```ruby
-@validated = validate(parameters) do
-  numeric  "price", required: true, min: 0
-  datetime "added"
-  text     "added_by", dependency: "added"
-end
-```
+#### :at_least
+
+The value of this option must be passed as a box. When given, this option indicates the minimum value for the associated box. The associated box can't be tinier than the given box.
+
+### Errors formats
+
+In Kharon, errors are formatted in a particular way. Each error contains a hash (or associative array) describing its type, and giving special caracteristics if necessary.
+
+#### Type error
+
+The most common error. It's raised when a type is expected for a key, and the given type for this key is different. It's formatted as followed :
+
+- type : always has the value "type"
+- key : the key concerned by the error in the validated hash
+- supposed : the type of which the value associated with the key is supposed to be
+- given : the type effectively given for the value associated with the key
+
+#### required error
+
+This error is raised when a key was required in the validated hash, but was not given. It's formatted as followed :
+
+- type : always has the value "required"
+- key : the required, but not provided, key
+
+#### dependency error
+
+This error is raised when a dependency was needed, but not provided, for a key. It's formatted as followed :
+
+- type : always has the value "dependency"
+- key : the key needing another key to properly work
+- dependency : the needed, but not provided, dependency
+
+#### min/max error
+
+This error is raised when a key must have a minimum or maximum value, but the provided value is below the minimum or above the maximum. It's formatted as followed :
+
+- type : has either "min" or "max" value
+- supposed : the maximum or minimum value the provided value mustn't exceed
+- key : the key concerned byt the error
+- value : the value not respecting the minimum or maximum asked
+
+#### in_array error
+
+This error is raised when the value associated with a key should belong to a range of values, and doesn't. It's formatted as followed :
+
+- type : always has the "array.in" value
+- key : the key concerned byt the error
+- supposed : the range of values in which the value associated with the key should belong to
+- value : the value provided with the key
+
+#### equals error
+
+This error is raised when the value associated to a key was expected to be equal to a value, but wasn't. It's formatted as followed :
+
+- type : always has the "equals" value
+- key : the key concerned byt the error
+- supposed : the value the key was supposed to have
+- value : the effective value associated to the key
+
+#### contains keys error
+
+This error is raised when a key, which type is a hash, doesn't contain the provided values as keys. It's formatted as followed :
+
+- type : always has the "contains.keys" value
+- key : the key concerned byt the error
+- required : the keys that must be contained in the value hash
+- value : the hash provided with the validated key
+
+#### contains values error
+
+This error is raised when a key, which type is an array or a hash, doesn't contain the provided values. It's formatted as followed :
+
+- type : always has the "contains.values" value
+- key : the key concerned byt the error
+- required : the values that must be contained in the value hash
+- value : the hash provided with the validated key
+
+#### regex error
+
+This error is raised when a value was expecting to respect a regular expression, but didn't. It's formatted as followed :
+
+- type : always has the "regex" value
+- key : the key concerned by the error
+- regex : the regular expression expected to be respected
+- value : the effective value not respecting the regular expression
+
+#### box format error
+
+This error is raised when a geographic box is not well formatted. It's formatted as followed :
+
+- type : always has the "box.format" value
+- key : the key concerned by the error
+- value : the effective value of the box, not respecting the format of a box
+
+#### box containment error
+
+This error is raised when a given key, as a box, is not contained in the box it should be (with the :at_most and :at_least options). It's formatted as followed :
+
+- type : always has the "box.containment" value
+- key : the key concerned by the error
+- container : the box whithin which the contained box must be
+- contained : the box that must be contained in the container
+
+### Does it work ?
 
-This example could validate the datas coming in the application in a search engine route for products in a supermarket.
+Yes, it works, unit tests results can be found here : {file:doc/results.html results of unit tests}

data/doc/Kharon.html

@@ -0,0 +1,364 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Module: Kharon
+  
+    &mdash; Documentation by YARD 0.8.7.6
+  
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '';
+  framesUrl = "frames.html#!Kharon.html";
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div id="header">
+      <div id="menu">
+  
+    <a href="_index.html">Index (K)</a> &raquo;
+    
+    
+    <span class="title">Kharon</span>
+  
+
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+
+      <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+      Class List
+    </a>
+  
+    <a class="full_list_link" id="method_list_link"
+        href="method_list.html">
+      Method List
+    </a>
+  
+    <a class="full_list_link" id="file_list_link"
+        href="file_list.html">
+      File List
+    </a>
+  
+</div>
+      <div class="clear"></div>
+    </div>
+
+    <iframe id="search_frame"></iframe>
+
+    <div id="content"><h1>Module: Kharon
+  
+  
+  
+</h1>
+
+<dl class="box">
+  
+  
+    
+  
+    
+  
+  
+  
+    <dt class="r1 last">Defined in:</dt>
+    <dd class="r1 last">lib/kharon.rb<span class="defines">,<br />
+  lib/kharon/errors.rb,<br /> lib/kharon/version.rb,<br /> lib/kharon/handlers.rb,<br /> lib/kharon/validator.rb,<br /> lib/kharon/errors/validation.rb,<br /> lib/kharon/handlers/messages.rb,<br /> lib/kharon/handlers/exceptions.rb</span>
+</dd>
+  
+</dl>
+<div class="clear"></div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Main module of the application.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Author:</p>
+<ul class="author">
+  
+    <li>
+      
+      
+      
+      
+        
+        <div class='inline'>
+<p>Vincent Courtois &lt;courtois.vincent@outlook.com&gt;</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div><h2>Defined Under Namespace</h2>
+<p class="children">
+  
+    
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Kharon/Errors.html" title="Kharon::Errors (module)">Errors</a></span>, <span class='object_link'><a href="Kharon/Handlers.html" title="Kharon::Handlers (module)">Handlers</a></span>
+    
+  
+    
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Kharon/Validator.html" title="Kharon::Validator (class)">Validator</a></span>
+    
+  
+</p>
+
+  <h2>Constant Summary</h2>
+  
+    <dl class="constants">
+      
+        <dt id="VERSION-constant" class="">VERSION =
+          <div class="docstring">
+  <div class="discussion">
+    
+<p>Current version of the application.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
+        </dt>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>1.1.0</span><span class='tstring_end'>&quot;</span></span></pre></dd>
+      
+        <dt id="use_exceptions-classvariable" class="">@@use_exceptions =
+          
+        </dt>
+        <dd><pre class="code"><span class='kw'>true</span></pre></dd>
+      
+    </dl>
+  
+
+
+
+
+
+
+
+  
+    <h2>
+      Class Method Summary
+      <small>(<a href="#" class="summary_toggle">collapse</a>)</small>
+    </h2>
+
+    <ul class="summary">
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#errors_handler-class_method" title="errors_handler (class method)">+ (Object) <strong>errors_handler</strong> </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>Returns the current error handler, defined by if you use exceptions or not.</p>
+</div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#use_exceptions-class_method" title="use_exceptions (class method)">+ (Object) <strong>use_exceptions</strong>(use = true) </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>Configuration method used to tell the module if it uses exceptions or
+stores error messages.</p>
+</div></span>
+  
+</li>
+
+      
+    </ul>
+  
+
+
+
+  <div id="class_method_details" class="method_details_list">
+    <h2>Class Method Details</h2>
+
+    
+      <div class="method_details first">
+  <h3 class="signature first" id="errors_handler-class_method">
+  
+    + (<tt>Object</tt>) <strong>errors_handler</strong> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Returns the current error handler, defined by if you use exceptions or not.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>an instance of Kharon::Handlers::Exceptions if you use exceptions, an
+instance of Kharon::Handlers::Messages else.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+17
+18
+19</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/kharon.rb', line 17</span>
+
+<span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_errors_handler'>errors_handler</span>
+  <span class='cvar'>@@use_exceptions</span> <span class='op'>?</span> <span class='const'>Kharon</span><span class='op'>::</span><span class='const'>Handlers</span><span class='op'>::</span><span class='const'>Exceptions</span><span class='period'>.</span><span class='id identifier rubyid_instance'>instance</span> <span class='op'>:</span> <span class='const'>Kharon</span><span class='op'>::</span><span class='const'>Handlers</span><span class='op'>::</span><span class='const'>Messages</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+      <div class="method_details ">
+  <h3 class="signature " id="use_exceptions-class_method">
+  
+    + (<tt>Object</tt>) <strong>use_exceptions</strong>(use = true) 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Configuration method used to tell the module if it uses exceptions or
+stores error messages.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>use</span>
+      
+      
+        <span class='type'>(<tt>Boolean</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>true</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>TRUE if you want to use exceptions, FALSE else.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+11
+12
+13</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/kharon.rb', line 11</span>
+
+<span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_use_exceptions'>use_exceptions</span><span class='lparen'>(</span><span class='id identifier rubyid_use'>use</span> <span class='op'>=</span> <span class='kw'>true</span><span class='rparen'>)</span>
+  <span class='cvar'>@@use_exceptions</span> <span class='op'>=</span> <span class='id identifier rubyid_use'>use</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
+
+</div>
+
+    <div id="footer">
+  Generated on Tue Sep 15 10:54:07 2015 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.8.7.6 (ruby-1.9.3).
+</div>
+
+  </body>
+</html>