trackerific 0.3.1 → 0.3.2

data/doc/Trackerific/UPS.html

@@ -134,31 +134,6 @@ Provides package tracking support for UPS.
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#required_options-instance_method" title="#required_options (instance method)">- (Array) <strong>required_options</strong> </a>
-    
-
-    
-  </span>
-  
-  
-  
-  
-  
-  
-
-  
-    <span class="summary_desc"><div class='inline'><p>
-The required options for tracking a UPS package are :key, :user_id, and
-:password.
-</p>
-</div></span>
-  
-</li>
-
-      
-        <li class="public ">
-  <span class="summary_signature">
-    
       <a href="#track_package-instance_method" title="#track_package (instance method)">- (Trackerific::Details) <strong>track_package</strong>(package_id) </a>
     
 
@@ -207,83 +182,56 @@ Tracks a UPS package.
     
     
       <div class="method_details first">
-  <p class="signature first" id="required_options-instance_method">
+  <p class="signature first" id="track_package-instance_method">
   
-    - (<tt>Array</tt>) <strong>required_options</strong> 
+    - (<tt><span class='object_link'><a href="Details.html" title="Trackerific::Details (class)">Trackerific::Details</a></span></tt>) <strong>track_package</strong>(package_id) 
   
 
   
 </p><div class="docstring">
   <div class="discussion">
     <p>
-The required options for tracking a UPS package are :key, :user_id, and
-:password.
+Tracks a UPS package
 </p>
 
 
   </div>
 </div>
 <div class="tags">
-  <h3>Returns:</h3>
-<ul class="return">
+  
+  <div class="examples">
+    <h3>Examples:</h3>
+    
+      <h4><div class='inline'><p>
+Track a package
+</p>
+</div></h4>
+      <pre class="example code"><span class='id ups'>ups</span> <span class='op'>=</span> <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>UPS</span><span class='period'>.</span><span class='id new'>new</span> <span class='label'>key:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>api key</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>user_id:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>user</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>secret</span><span class='tstring_end'>'</span></span>
+<span class='id details'>details</span> <span class='op'>=</span> <span class='id ups'>ups</span><span class='period'>.</span><span class='id track_package'>track_package</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>1Z12345E0291980793</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span></pre>
+    
+  </div>
+<h3>Parameters:</h3>
+<ul class="param">
   
     <li>
       
+        <span class='name'>package_id</span>
       
-        <span class='type'>(<tt>Array</tt>)</span>
+      
+        <span class='type'>(<tt>String</tt>)</span>
       
       
       
         &mdash;
         <div class='inline'><p>
-the required options for tracking a UPS package.
+the package identifier
 </p>
 </div>
       
     </li>
   
 </ul>
-
-</div><table class="source_code">
-  <tr>
-    <td>
-      <pre class="lines">
-
-
-19
-20
-21</pre>
-    </td>
-    <td>
-      <pre class="code"><span class="info file"># File 'lib/ups.rb', line 19</span>
-
-<span class='kw'>def</span> <span class='id required_options'>required_options</span>
-  <span class='lbracket'>[</span><span class='symbol'>:key</span><span class='comma'>,</span> <span class='symbol'>:user_id</span><span class='comma'>,</span> <span class='symbol'>:password</span><span class='rbracket'>]</span>
-<span class='kw'>end</span></pre>
-    </td>
-  </tr>
-</table>
-</div>
-    
-      <div class="method_details ">
-  <p class="signature " id="track_package-instance_method">
-  
-    - (<tt><span class='object_link'><a href="Details.html" title="Trackerific::Details (class)">Trackerific::Details</a></span></tt>) <strong>track_package</strong>(package_id) 
-  
-
-  
-</p><div class="docstring">
-  <div class="discussion">
-    <p>
-Tracks a UPS package. A Trackerific::Error is raised when a package cannot
-be tracked.
-</p>
-
-
-  </div>
-</div>
-<div class="tags">
-  <h3>Returns:</h3>
+<h3>Returns:</h3>
 <ul class="return">
   
     <li>
@@ -301,6 +249,26 @@ the tracking details
       
     </li>
   
+</ul>
+<h3>Raises:</h3>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="Error.html" title="Trackerific::Error (class)">Trackerific::Error</a></span></tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>
+raised when the server returns an error (invalid credentials, tracking
+package, etc.)
+</p>
+</div>
+      
+    </li>
+  
 </ul>
 
 </div><table class="source_code">
@@ -309,6 +277,7 @@ the tracking details
       <pre class="lines">
 
 
+25
 26
 27
 28
@@ -321,11 +290,10 @@ the tracking details
 35
 36
 37
-38
-39</pre>
+38</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/ups.rb', line 26</span>
+      <pre class="code"><span class="info file"># File 'lib/ups.rb', line 25</span>
 
 <span class='kw'>def</span> <span class='id track_package'>track_package</span><span class='lparen'>(</span><span class='id package_id'>package_id</span><span class='rparen'>)</span>
   <span class='kw'>super</span>
@@ -351,7 +319,7 @@ the tracking details
 </div>
     
     <div id="footer">
-  Generated on Mon Jun 13 14:22:51 2011 by 
+  Generated on Mon Jun 13 16:20:05 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>

data/doc/Trackerific/USPS.html

@@ -134,56 +134,6 @@ Provides package tracking support for USPS.
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#initialize-instance_method" title="#initialize (instance method)">- (USPS) <strong>initialize</strong>(options = {}) </a>
-    
-
-    
-  </span>
-  
-    <span class="note title constructor">constructor</span>
-  
-  
-  
-  
-  
-  
-
-  
-    <span class="summary_desc"><div class='inline'><p>
-A new instance of USPS.
-</p>
-</div></span>
-  
-</li>
-
-      
-        <li class="public ">
-  <span class="summary_signature">
-    
-      <a href="#required_options-instance_method" title="#required_options (instance method)">- (Array) <strong>required_options</strong> </a>
-    
-
-    
-  </span>
-  
-  
-  
-  
-  
-  
-
-  
-    <span class="summary_desc"><div class='inline'><p>
-The required option for tracking a UPS package is :user_id.
-</p>
-</div></span>
-  
-</li>
-
-      
-        <li class="public ">
-  <span class="summary_signature">
-    
       <a href="#track_package-instance_method" title="#track_package (instance method)">- (Trackerific::Details) <strong>track_package</strong>(package_id) </a>
     
 
@@ -214,49 +164,15 @@ Tracks a USPS package.
   
   
   
-  <div id="constructor_details" class="method_details_list">
-  <h2>Constructor Details</h2>
-  
-    <div class="method_details first">
-  <p class="signature first" id="initialize-instance_method">
   
-    - (<tt><span class='object_link'><a href="" title="Trackerific::USPS (class)">USPS</a></span></tt>) <strong>initialize</strong>(options = {}) 
   
-
   
-</p><div class="docstring">
-  <div class="discussion">
-    <p>
-A new instance of USPS
-</p>
-
-
-  </div>
-</div>
-<div class="tags">
+  <h3 class="inherited">Methods inherited from <span class='object_link'><a href="Base.html" title="Trackerific::Base (class)">Base</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="Base.html#initialize-instance_method" title="Trackerific::Base#initialize (method)">#initialize</a></span></p>
+<div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
   
-</div><table class="source_code">
-  <tr>
-    <td>
-      <pre class="lines">
-
-
-16
-17
-18
-19</pre>
-    </td>
-    <td>
-      <pre class="code"><span class="info file"># File 'lib/usps.rb', line 16</span>
-
-<span class='kw'>def</span> <span class='id initialize'>initialize</span><span class='lparen'>(</span><span class='id options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
-  <span class='kw'>super</span>
-  <span class='ivar'>@options</span> <span class='op'>=</span> <span class='id options'>options</span>
-<span class='kw'>end</span></pre>
-    </td>
-  </tr>
-</table>
-</div>
+    <p class="notice">This class inherits a constructor from <span class='object_link'><a href="Base.html#initialize-instance_method" title="Trackerific::Base#initialize (method)">Trackerific::Base</a></span></p>
   
 </div>
 
@@ -266,82 +182,56 @@ A new instance of USPS
     
     
       <div class="method_details first">
-  <p class="signature first" id="required_options-instance_method">
+  <p class="signature first" id="track_package-instance_method">
   
-    - (<tt>Array</tt>) <strong>required_options</strong> 
+    - (<tt><span class='object_link'><a href="Details.html" title="Trackerific::Details (class)">Trackerific::Details</a></span></tt>) <strong>track_package</strong>(package_id) 
   
 
   
 </p><div class="docstring">
   <div class="discussion">
     <p>
-The required option for tracking a UPS package is :user_id
+Tracks a USPS package
 </p>
 
 
   </div>
 </div>
 <div class="tags">
-  <h3>Returns:</h3>
-<ul class="return">
+  
+  <div class="examples">
+    <h3>Examples:</h3>
+    
+      <h4><div class='inline'><p>
+Track a package
+</p>
+</div></h4>
+      <pre class="example code"><span class='id usps'>usps</span> <span class='op'>=</span> <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>USPS</span><span class='period'>.</span><span class='id new'>new</span> <span class='label'>user_id:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>user</span><span class='tstring_end'>'</span></span>
+<span class='id details'>details</span> <span class='op'>=</span> <span class='id ups'>ups</span><span class='period'>.</span><span class='id track_package'>track_package</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>EJ958083578US</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span></pre>
+    
+  </div>
+<h3>Parameters:</h3>
+<ul class="param">
   
     <li>
       
+        <span class='name'>package_id</span>
       
-        <span class='type'>(<tt>Array</tt>)</span>
+      
+        <span class='type'>(<tt>String</tt>)</span>
       
       
       
         &mdash;
         <div class='inline'><p>
-the required options for tracking a UPS package.
+the package identifier
 </p>
 </div>
       
     </li>
   
 </ul>
-
-</div><table class="source_code">
-  <tr>
-    <td>
-      <pre class="lines">
-
-
-24
-25
-26</pre>
-    </td>
-    <td>
-      <pre class="code"><span class="info file"># File 'lib/usps.rb', line 24</span>
-
-<span class='kw'>def</span> <span class='id required_options'>required_options</span>
-  <span class='lbracket'>[</span><span class='symbol'>:user_id</span><span class='rbracket'>]</span>
-<span class='kw'>end</span></pre>
-    </td>
-  </tr>
-</table>
-</div>
-    
-      <div class="method_details ">
-  <p class="signature " id="track_package-instance_method">
-  
-    - (<tt><span class='object_link'><a href="Details.html" title="Trackerific::Details (class)">Trackerific::Details</a></span></tt>) <strong>track_package</strong>(package_id) 
-  
-
-  
-</p><div class="docstring">
-  <div class="discussion">
-    <p>
-Tracks a USPS package. A Trackerific::Error is raised when a package cannot
-be tracked.
-</p>
-
-
-  </div>
-</div>
-<div class="tags">
-  <h3>Returns:</h3>
+<h3>Returns:</h3>
 <ul class="return">
   
     <li>
@@ -370,6 +260,13 @@ the tracking details
       
       
       
+        &mdash;
+        <div class='inline'><p>
+raised when the server returns an error (invalid credentials, tracking
+package, etc.)
+</p>
+</div>
+      
     </li>
   
 </ul>
@@ -380,6 +277,11 @@ the tracking details
       <pre class="lines">
 
 
+26
+27
+28
+29
+30
 31
 32
 33
@@ -404,18 +306,26 @@ the tracking details
 52
 53
 54
-55</pre>
+55
+56
+57</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/usps.rb', line 31</span>
+      <pre class="code"><span class="info file"># File 'lib/usps.rb', line 26</span>
 
 <span class='kw'>def</span> <span class='id track_package'>track_package</span><span class='lparen'>(</span><span class='id package_id'>package_id</span><span class='rparen'>)</span>
   <span class='kw'>super</span>
-  <span class='id response'>response</span> <span class='op'>=</span> <span class='kw'>self</span><span class='period'>.</span><span class='id class'>class</span><span class='period'>.</span><span class='id get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/ShippingAPITest.dll</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:query</span> <span class='op'>=&gt;</span> <span class='lbrace'>{</span><span class='symbol'>:API</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackV2</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:XML</span> <span class='op'>=&gt;</span> <span class='id build_xml_request'>build_xml_request</span><span class='rbrace'>}</span><span class='period'>.</span><span class='id to_query'>to_query</span><span class='rparen'>)</span>
-  <span class='id response'>response</span><span class='period'>.</span><span class='id error!'>error!</span> <span class='kw'>unless</span> <span class='id response'>response</span><span class='period'>.</span><span class='id code'>code</span> <span class='op'>==</span> <span class='int'>200</span>
-  <span class='id raise'>raise</span> <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>Error</span><span class='comma'>,</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Error</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Description</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='kw'>unless</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Error</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id nil?'>nil?</span>
+  <span class='comment'># connect to the USPS shipping API via HTTParty
+</span>  <span class='id response'>response</span> <span class='op'>=</span> <span class='kw'>self</span><span class='period'>.</span><span class='id class'>class</span><span class='period'>.</span><span class='id get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/ShippingAPITest.dll</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:query</span> <span class='op'>=&gt;</span> <span class='lbrace'>{</span><span class='symbol'>:API</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackV2</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:XML</span> <span class='op'>=&gt;</span> <span class='id build_xml_request'>build_xml_request</span><span class='rbrace'>}</span><span class='period'>.</span><span class='id to_query'>to_query</span><span class='rparen'>)</span>
+  <span class='comment'># throw any HTTP errors
+</span>  <span class='id response'>response</span><span class='period'>.</span><span class='id error!'>error!</span> <span class='kw'>unless</span> <span class='id response'>response</span><span class='period'>.</span><span class='id code'>code</span> <span class='op'>==</span> <span class='int'>200</span>
+  <span class='comment'># raise a Trackerific::Error if there is an error in the response, or if the
+</span>  <span class='comment'># tracking response is malformed
+</span>  <span class='id raise'>raise</span> <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>Error</span><span class='comma'>,</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Error</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Description</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='kw'>unless</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Error</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id nil?'>nil?</span>
   <span class='id raise'>raise</span> <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>Error</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Tracking information not found in response from server.</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackResponse</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id nil?'>nil?</span>
-  <span class='id tracking_info'>tracking_info</span> <span class='op'>=</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackResponse</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackInfo</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span>
+  <span class='comment'># get the tracking information from the response, and convert into a
+</span>  <span class='comment'># Trackerific::Details
+</span>  <span class='id tracking_info'>tracking_info</span> <span class='op'>=</span> <span class='id response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackResponse</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackInfo</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span>
   <span class='id details'>details</span> <span class='op'>=</span> <span class='lbracket'>[</span><span class='rbracket'>]</span>
   <span class='id tracking_info'>tracking_info</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackDetail</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id each'>each</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id d'>d</span><span class='op'>|</span>
     <span class='comment'># each tracking detail is a string in this format:
@@ -428,7 +338,8 @@ the tracking details
     <span class='id desc'>desc</span> <span class='op'>=</span> <span class='id d'>d</span><span class='lbracket'>[</span><span class='int'>4</span><span class='op'>..</span><span class='id d'>d</span><span class='period'>.</span><span class='id length'>length</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> </span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
     <span class='id details'>details</span> <span class='op'>&lt;&lt;</span> <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>Event</span><span class='period'>.</span><span class='id new'>new</span><span class='lparen'>(</span><span class='id date'>date</span><span class='comma'>,</span> <span class='id desc'>desc</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
   <span class='kw'>end</span>
-  <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>Details</span><span class='period'>.</span><span class='id new'>new</span><span class='lparen'>(</span>
+  <span class='comment'># return the details
+</span>  <span class='const'>Trackerific</span><span class='op'>::</span><span class='const'>Details</span><span class='period'>.</span><span class='id new'>new</span><span class='lparen'>(</span>
     <span class='id tracking_info'>tracking_info</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>ID</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
     <span class='id tracking_info'>tracking_info</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TrackSummary</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
     <span class='id details'>details</span>
@@ -444,7 +355,7 @@ the tracking details
 </div>
     
     <div id="footer">
-  Generated on Mon Jun 13 14:22:51 2011 by 
+  Generated on Mon Jun 13 16:20:06 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>