jtask 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0851a01dafb0753c4883abf034310c496a3181a8
-  data.tar.gz: ae407131ec5fd73379f5ffe2deeb327b7578eab1
+  metadata.gz: f589f44037f5f3b2e2032dee07d5a47ebea4b3a6
+  data.tar.gz: 80d389752aea2d76dafdb73448b89b1ab7998a11
 SHA512:
-  metadata.gz: 9de71bd836ab66469769925591e7764ba9753f81d98c7a5e6ca822cb6dafb2ff1f77dbcc13680cdd3e79b894bda54d337a140b2b0ef80e0c8ce3abf43c632673
-  data.tar.gz: 02e2d26f4009028e2cca6ca74f126ee1eec2bd7599ea4a62aab14c8e58089aceafe7be3b45077221ae81996bb8e404e56191fb99544babe76362a7ad6651b992
+  metadata.gz: 1f41a63d10b147aff1c1901e9ea171fcdd05b98f207fb767a7a868b9002a333c2ff0698b7d77dcf9eefa77bfb3293a7e8498eb2862860d76c382c33c4e563f72
+  data.tar.gz: b15a34adffb7429425bb5495cfb8e6760959ec2445498ec84a8628348e95c7727d08c53581140e6302a8b8b841c6d5f79cffae7c76976bcae2e0bc91857b118d

data/.gitignore

@@ -2,4 +2,4 @@
 tmp
 doc
 .DS_Store
-*.sublime-workspace
+*.sublime*

data/changelist.txt

@@ -1,14 +1,3 @@
-0.1.0 [Beta] [Current Version]
-=====================================
-- Released a major bug fix regarding the `JTask.get()` method (see: https://github.com/adammcarthur/jtask/issues/1)
-- Minor code enhancements to the Get module.
-- Error messages have been reformatted for both web and console use.
+Moved changelist to:
 
-0.0.2 [Beta]
-=====================================
-- Swapped gemspec description and summary (mix up error).
-
-
-0.0.1 [Beta]
-=====================================
-- Initial release
+https://github.com/adammcarthur/jtask/releases

data/jtask.gemspec

@@ -1,8 +1,8 @@
 Gem::Specification.new do |s|
   s.name        = 'jtask'
-  s.version     = '0.1.0'
+  s.version     = '0.2.0'
   s.platform    = Gem::Platform::RUBY
-  s.date        = '2014-03-23'
+  s.date        = '2014-04-01'
   s.description = "Provides CRUD actions for JSON files, plus a few extra goodies."
   s.summary     = "CRUD actions for JSON files."
   s.authors     = ["Adam McArthur"]
@@ -12,5 +12,5 @@ Gem::Specification.new do |s|
   s.files       = `git ls-files`.split($/)
   s.require_paths = ["lib"]
   s.add_runtime_dependency "json", "~> 1.4"
-  s.post_install_message = "\nThanks for installing JTask Beta. Check out the full documentation and contribute at https://github.com/adammcarthur/jtask\n\nIn this release (v0.1.0 Beta): Fixed a major flaw in the JTask.get() output. Read more about this error here: https://github.com/adammcarthur/jtask/issues/1\n\n- Adam (@adammcarth)\n-"
+  s.post_install_message = "\nThanks for installing JTask Beta. Check out the full documentation and contribute at https://github.com/adammcarthur/jtask\n\nIn this release (v0.2.0 Beta): JTask now outputs OpenStructs instead of Hashes. Read more about this update here: https://github.com/adammcarthur/jtask/issues/2\n\n- Adam (@adammcarth)\n-"
 end

data/lib/jtask.rb

@@ -1,5 +1,5 @@
 ###########################################################################
-# ` JTask v0.1.0 Beta                                                   ` #
+# ` JTask v0.2.0 Beta                                                   ` #
 # ` Provides CRUD actions for JSON files, plus a few extra goodies.     ` #
 # ` Created by Adam McArthur (@adammcarth)                              ` #
 # ` Released under the MIT licence                                      ` #
@@ -9,6 +9,7 @@
 class JTask
   # Dependencies
   require "rubygems"
+  require "ostruct"
   require "json"
 
   # Modules

data/lib/jtask/chop.rb

@@ -3,7 +3,11 @@ module Chop
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
     original_file = File.read(File.join(dir, filename))
     objects = JSON.parse(original_file)

data/lib/jtask/destroy.rb

@@ -3,11 +3,15 @@ module Destroy
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
     original_file = File.read(File.join(dir, filename))
     objects = JSON.parse(original_file)
-    
+
     if objects["#{id}"]
       # Delete the object with id n from the objects hash
       insert = objects.tap{ |x| x.delete("#{id}") }

data/lib/jtask/get.rb

@@ -6,7 +6,11 @@ module Get
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
     original_file = File.read(File.join(dir, filename))
     objects = JSON.parse(original_file)
@@ -21,7 +25,7 @@ module Get
       id = method
 
       if objects["#{id}"]
-        output = { "id" => id.to_i }.merge(objects["#{id}"])
+        output = OpenStruct.new({ "id" => id.to_i }.merge(objects["#{id}"]))
       else
         # id supplied doesn't exist
         raise NameError, "[JTask] The id #{method} could not be found in the file \"#{dir + filename}\"."
@@ -47,11 +51,9 @@ module Get
         end
       end
       # Loop through each required record and
-      # push each one to the blank output array.
-      output = []
-      required_records.each do |id, record|
-        output.push({ "id" => id.to_i }.merge(record))
-      end
+      # assemble each key-value into the open structure output.
+      # Map all openstructs to an array.
+      output = required_records.map { |id, record| OpenStruct.new({ "id" => id.to_i }.merge(record)) }
     end
 
     return output

data/lib/jtask/kill.rb

@@ -3,12 +3,16 @@ module Kill
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
 
     # Delete the file
     File.delete(File.join(dir, filename))
-    
+
     return true
   end
 end

data/lib/jtask/rename.rb

@@ -3,9 +3,13 @@ module Rename
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
-    
+
     # Rename the file
     File.rename(File.join(dir, filename), File.join(dir, new))
 

data/lib/jtask/save.rb

@@ -3,7 +3,11 @@ module Save
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
     # Check if the file already exists
     unless File.exists?(File.join(dir, filename))
@@ -14,7 +18,7 @@ module Save
     unless parameters.is_a?(Hash)
       raise SyntaxError, "[JTask] Invalid value supplied to the parameters variable. Ensure your parameters are in the symbol hash form, eg - {name: \"Adam\", city: \"Melbourne\"}"
     end
-    
+
     original_file = File.read(File.join(dir, filename))
     objects = JSON.parse(original_file)
     # Set the id of the new object
@@ -25,10 +29,10 @@ module Save
       # No current objects exist yet, so set the id to 1
       nextid = 1
     end
-    
+
     # Remove last character "}" from file.
     insert = File.read(File.join(dir, filename))[0..-2]
-    
+
     insert << "," if (objects.to_a).first # add a comma if at least one object already exists
     insert << "\"#{nextid.to_s}\":"
     insert << parameters.to_json
@@ -36,7 +40,7 @@ module Save
     insert << "}"
     # Re-write the file with the new version.
     File.write(File.join(dir, filename), insert)
-    
+
     return true
   end
 end

data/lib/jtask/update.rb

@@ -3,7 +3,11 @@ module Update
     # Check if user has specified a custom directory.
     unless dir
       # If not, a default folder is assigned.
-      dir = "models/"
+      if File.directory?("models/")
+        dir = "models/"
+      else
+        raise RuntimeError, "[JTask] The directory 'models/' doesn't exist in your current location. Please create it or refer to the documentation on how to change your file path."
+      end
     end
     original_file = File.read(File.join(dir, filename))
     objects = JSON.parse(original_file)
@@ -13,7 +17,7 @@ module Update
       # Update (or add) each parameter
       insert["#{id}"][k.to_s] = v
     end
-    
+
     # Re-write the file with the new version.
     File.write(File.join(dir, filename), insert.to_json)
 

data/readme.md

@@ -2,114 +2,156 @@
 
 JTask provides CRUD actions for storage of data in JSON format inside text files. It's very useful for times when databases cannot be used to store data, or a simple storage & retrieval mechanism is required. It can act just like a database, check it out:
 
-    require "jtask"
-    
-    JTask.save("preferences", {background_color: "black", font_size: "medium"})
-    #=> true
+``` ruby
+require "jtask"
 
-    JTask.get("preferences", 1)["font_size"]
-    #=> "medium"
+JTask.save("preferences", {background_color: "black", font_size: "medium"})
+#=> true
 
-The above example stores the settings in a file called `preferences` using JSON. We then get the object from the file with id `1`, and output the value of the `"font_size"` key.
+JTask.get("preferences", last: 1).font_size
+#=> "medium"
+```
 
-**Example of JTask storage file:**
-
-    {
-      "1": {
-        "background_colour": "black",
-        "font_size": "medium"
-      }
-    }
+The above example stores the settings in a file called `preferences` using JSON. We then get the last object saved to the file and output the value of the `"font_size"` key.
 
-Sequential ID's are automatically assigned to JSON objects on save.
+**Example of JTask storage file:**
 
-### JTask.save(filename, parameters, dir=nil)
+``` json
+{
+  "1": {
+    "background_colour": "black",
+    "font_size": "medium"
+  }
+}
+```
+
+JTask can even act as a management system for already exisiting json files. Please note that a few adjustments will need to be made to your files beforehand - check out the [JTask.convert()](https://github.com/adammcarthur/jtask/wiki/JTask.convert() "Configure existing json files for JTask") wiki guide for more information.
+
+## Getting Started
+``` bash
+gem install jtask
+```
+
+``` ruby
+# Include the jtask library where necassary
+require "jtask"
+
+# Tell JTask where your files are [optional]
+jtask.settings do |s|
+  s.file_dir = "path/to/jtask_files"
+end
+```
+
+### [JTask.save(filename, parameters, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.save() "View full guide")
 *Saves a hash of parameters to the requested file.*
 
-    JTask.save("foods", {entree: "cheese", main: "hamburger", desert: "cake"})
-    
+``` ruby
+JTask.save("foods", {entree: "cheese", main: "hamburger", desert: "cake"})
+```
+
 You can use file extensions if you want (makes no difference), as well as set a custom directory for the file. The default directory JTask will look in is `/models`.
 
-    JTask.save("users.json", {username: "adam", twitter: "@adammcarth"}, "files/")
-    
+``` ruby
+JTask.save("users.json", {username: "adam", twitter: "@adammcarth"}, "files/")
+```
+
 Notes:
 
  - **JTask will automatically create the files** for you on save if they don't exist.
  - To prepare already existing files for JTask operations, they must only contain `{}` inside.
  - When setting a custom directory, ensure it ends with `/`.
 
-### JTask.get(filename, method=nil, dir=nil)
-*Retrieves stored JSON data from the file and returns a hash.*
+### [JTask.get(filename, method=nil, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.get() "View full guide")
+*Retrieves stored JSON data from the file and returns an OpenStruct.*
+
+``` ruby
+JTask.get("email_subscribers")
+#=> [ <OpenStruct "id"=1 "email"=>"gary@google.com">, <OpenStruct "id"=>2 "email"=>"blah"> ... ]
+```
 
-    JTask.get("email_subscribers")
-    
-    #=> {"1"=>{"email"=>"gary@google.com"}, "2"=>{"email"=>"john@isp.net"}...}
-    
 As seen above - calling JTask.get() without a method argument will return **all** the records stored. Let's now try and get the 50th email subscriber's email address:
 
-    @subscriber = JTask.get("email_subscribers", 50)
-    #=> {"id"=>"50", "email"=>"yukihiro@matsumoto.net"}
-    
-    @subscriber["email"]
-    #=> "yukihiro@matsumoto.net"
-    
+``` ruby
+@subscriber = JTask.get("email_subscribers", 50)
+#=> <OpenStruct "id"="50" "email"="yukihiro@matsumoto.net">
+
+@subscriber.email
+#=> "yukihiro@matsumoto.net"
+```
+
 JTask also comes with a few retrieval methods similar to Active Record. Let's get the **first and last** `n` email subscribers:
 
-    JTask.get("email_subscribers", first: 25)
-    #=> {"1"=>{...}, "2"=>{...} ... "25"=>{...}}
-    
-    JTask.get("email_subscribers", last: 1)
-    #=> {"365"=>{..}}
+``` ruby
+JTask.get("email_subscribers", first: 25)
+#=> [ <OpenStruct "id"=1>, <OpenStruct "id"=2>, ..., <OpenStruct "id"=25> ]
+
+JTask.get("email_subscribers", last: 1)
+#=> <OpenStruct "id"=365 "email"="goo@goo.gl">
+```
 
-### JTask.update(filename, id, parameters, dir=nil)
-*Updates the record with `id` with a new set of parameters.*
+### [JTask.update(filename, id, parameters, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.update() "View full guide")
+*Updates the `id` json object with a new set of parameters.*
 
-    JTask.update("ui_settings", 42, {show_ads: "no", background: "grey"})
+``` ruby
+JTask.update("ui_settings", 42, {show_ads: "no", background: "grey"})
+```
 
 JTask upgrades records gracefully - parameters already existing inside the JSON object will be replaced with the new value, whereas new parameters will be added.
 
-    # Original Version
-    { "42" => { "show_ads": "yes" } }
-    
-    # Updated Version
-    { "42" => { "show_ads": "no", "background": "grey" } }
+``` ruby
+# Original Version
+<OpenStruct "id"=42 "show_ads"="yes">
+
+# Updated Version
+<OpenStruct "id"=42 "show_ads"="no" "background"="grey">
+```
 
 To completely remove parameters (the entire key-value pair) from objects, refer to the JTask.chop() method below.
 
-### JTask.destroy(filename, id, dir=nil)
+### [JTask.destroy(filename, id, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.destroy() "View full guide")
 *Removes an entire object from the file.*
 
-    JTask.destroy("twitter_names", 15)
-    
-### JTask.chop(filename, id, paramter, dir=nil)
+``` ruby
+JTask.destroy("twitter_names", 15)
+```
+
+### [JTask.chop(filename, id, paramter, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.chop() "View full guide")
 *Removes an entire key-value pair (or parameter) from one or all of the file's objects.*
 
-    JTask.chop("users", 4, "session_data")
-    
-    JTask.chop("users", :all, "session_data")
-    
+``` ruby
+JTask.chop("users", 4, "session_data")
+
+JTask.chop("users", :all, "session_data")
+```
+
 Impact:
 
-    # Old Version
-    { "4" => { "user_id" => "p18573", "session_data" => "34F3jkdf9azfvVak2" } }
-    
-    # New Version
-    { "4" => { "user_id" => "p18573" } }
-    
-The second example uses `:all` instead of an id. This would perform the same operation, but to all objects inside the target file (instead of a specific id).
+``` ruby
+# Old Version
+<OpenStruct "id"=4 "user_id"="p18573" "session_data"="34F3jkdf9azfvVak2">
 
-### JTask.rename(filename, new, dir=nil)
+# New Version
+<OpenStruct "id"=4 "user_id"="p18573">
+```
+
+The second example uses `:all` instead of an id. This would perform the same operation, but to all objects inside the target file (instead of a specific id). [Make sure you read the Chop wiki page](https://github.com/adammcarthur/jtask/wiki/JTask.chop()) to learn more.
+
+### [JTask.rename(filename, new, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.rename() "View full guide")
 *Simply renames the file to something different.*
 
-    JTask.rename("orders", "online_orders")
-    
-### JTask.kill(filename, dir=nil)
+``` ruby
+JTask.rename("orders", "online_orders")
+```
+
+### [JTask.kill(filename, dir=nil)](https://github.com/adammcarthur/jtask/wiki/JTask.kill() "View full guide")
 *Completely removes the entire file specified from the system.*
 
-    # Proceed with caution, the will delete the entire
-    # file and it cannot be recovered.
-    JTask.kill("not_needed_anymore.json")
-    
+``` ruby
+# Proceed with caution, the will delete the entire
+# file and it cannot be recovered.
+JTask.kill("not_needed_anymore.json")
+```
+
 ## Share your ideas and contribute
 
 I'd love to here what you plan to use JTask for. [Let me know via twitter](https://twitter.com/adammcarth), or email your thoughts and ideas to [adam@adammcarthur.net](mailto:adam@adammcarthur.net).

data/todo.txt

@@ -1,16 +1,3 @@
-Current List To Transition From Beta Into Stable:
+To do list moved to "enhancment" issues section on GitHub:
 
-1. Setup a dynamic method handler to make the JTask.get()
-method cleaner when selecting hash elements.
-
-Eg - JTask.get("email_subscribers", 5).email
-
-For more information, see ActiveRecord's implementation of method_missing().
-
-2. Add an encryption feature?
-
-3. Allow users to set the default directory.
-
-4. Clean up repeated code!!!
-
-5. Make file writes more efficient (to prevent scaling issues). Currently, files are completely re-written with the new version on save(), update(), chop() and destroy().
+https://github.com/adammcarthur/jtask/issues?labels=enhancement

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jtask
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Adam McArthur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-23 00:00:00.000000000 Z
+date: 2014-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -52,7 +52,7 @@ post_install_message: |2-
 
   Thanks for installing JTask Beta. Check out the full documentation and contribute at https://github.com/adammcarthur/jtask
 
-  In this release (v0.1.0 Beta): Fixed a major flaw in the JTask.get() output. Read more about this error here: https://github.com/adammcarthur/jtask/issues/1
+  In this release (v0.2.0 Beta): JTask now outputs OpenStructs instead of Hashes. Read more about this update here: https://github.com/adammcarthur/jtask/issues/2
 
   - Adam (@adammcarth)
   -