jtask 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8a3724c45e878a1633fa464af954ddefbe729cb8
+  data.tar.gz: 23409551f3de8e7290b93864e90240ab0839b016
+SHA512:
+  metadata.gz: 0ae4495c34617b63da73c5528114669f677d25642a3ba9ffe31d63d2f02bc1a93f60b33c14ca3764ea40fa754aa770ec1ddccaa279d127e7e4a3efec90c85d11
+  data.tar.gz: 8da72a38f76b1f89ac7667949b1039e13429e66b458ac21a764a115f1fee1ae75e7bbbf0da1d4f3428cba203539f72df840063418c1c672af33803ce1ec9d14b

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+tmp
+doc

data/jtask.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name        = 'jtask'
+  s.version     = '0.0.1'
+  s.platform    = Gem::Platform::RUBY
+  s.date        = '2014-03-23'
+  s.summary     = "Provides CRUD actions for JSON files, plus a few extra goodies."
+  s.description = "CRUD actions for JSON files."
+  s.authors     = ["Adam McArthur"]
+  s.email       = 'adam@adammcarthur.net'
+  s.homepage    = 'https://github.com/adammcarthur/jtask'
+  s.license     = 'MIT'
+  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\n- Adam (@adammcarth)\n-"
+end

data/lib/jtask.rb

@@ -0,0 +1,27 @@
+###########################################################################
+# ` JTask v0.0.1 Beta                                                   ` #
+# ` Provides CRUD actions for JSON files, plus a few extra goodies.     ` #
+# ` Created by Adam McArthur (@adammcarth)                              ` #
+# ` Released under the MIT licence                                      ` #
+# ` Contribute & Documentation: https://github.com/adammcarthur/jtask   ` #
+###########################################################################
+
+class JTask
+  # Dependencies
+  require "rubygems"
+  require "json"
+
+  # Modules
+  modules = ["save", "get", "update", "destroy", "chop", "rename", "kill"]
+  modules.each do |m|
+    require "jtask/#{m}"
+  end
+  
+  extend Save
+  extend Get
+  extend Update
+  extend Destroy
+  extend Chop
+  extend Rename
+  extend Kill
+end

data/lib/jtask/chop.rb

@@ -0,0 +1,41 @@
+module Chop
+  def chop(filename, id, parameter, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    end
+    original_file = File.read(File.join(dir, filename))
+    objects = JSON.parse(original_file)
+
+    # Quality control - ensure paramter is a string
+    unless parameter.is_a?(String)
+      raise SyntaxError, "The chop() method can only remove one parameter at a time\n               - only a string can be used to specify the parameter.\n\n-"
+    end
+
+    if id.is_a?(Integer)
+      if objects["#{id}"]
+        # Find object with the id and delete the requested parameter
+        removed_version = objects["#{id}"].tap{ |x| x.delete(parameter) }
+        insert = objects
+        insert["#{id}"] = removed_version
+      else
+        raise NameError, "\n\nJTask Error => The id #{method} could not be found in the\n               file \"#{dir + filename}\". The file has not been changed.\n\n-"
+      end
+    elsif id == :all
+      # Parameter must be removed from all objects
+      objects.each do |k, v|
+        # Remove parameter from every hash
+        objects["#{k}"] = objects["#{k}"].tap{ |x| x.delete(parameter) }
+      end
+    insert = objects
+    else
+      raise NameError, "/n/nJTask Error => Incorrect id method used. A single id (integer) can be specified,\n               or the symbol \":all\" to remove the parameter from every object.\n\n-"
+    end
+
+     # Re-write the file with the new version.
+     File.write(File.join(dir, filename), insert.to_json)
+
+    return true
+  end
+end

data/lib/jtask/destroy.rb

@@ -0,0 +1,24 @@
+module Destroy
+  def destroy(filename, id, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    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}") }
+    else
+      # the id doesn't exist in the file
+      raise NameError, "\n\nJTask Error => An id of #{id} does not exsist in the file specified at\n               \"#{dir + filename}\". Nothing has been deleted.\n\n-"
+    end
+
+    # Re-write the file with the new version.
+    File.write(File.join(dir, filename), insert.to_json)
+
+    return true
+  end
+end

data/lib/jtask/get.rb

@@ -0,0 +1,42 @@
+module Get
+  def get(filename, method=nil, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    end
+    original_file = File.read(File.join(dir, filename))
+    objects = JSON.parse(original_file)
+    
+    if method
+      # Determine if an id integer or {first: - last:} hash method has been supplied.
+      if method.is_a?(Integer)
+        # Check if 'method' (in this case the single id to retrieve) exists.
+        if objects["#{method}"]
+          output = {"id" => "#{method}"}.merge(objects["#{method}"])
+          # Old objects.select { |k, v| k == "#{method}" }
+        else
+          # id supplied doesn't exist
+          raise NameError, "\n\nJTask Error => The id #{method} could not be found in\n               the file \"#{dir + filename}\".\n\n-"
+        end
+      elsif method.is_a?(Hash)
+        if method[:first]
+          # Load the FIRST n number of objects from the file
+          output = Hash[(objects.to_a).first(method[:first].to_i)]
+        elsif method[:last]
+          # Load the LAST n number of objects from the file
+          output = Hash[(objects.to_a).last(method[:last].to_i).reverse] # wow!
+        else
+          raise NameError, "\n\nJTask Error => Invalid get method specified. Try using\n               JTask.get(\"filename\", last: 10) instead.\n\n-" 
+        end
+      else
+        raise NameError, "\n\nJTask Error => Invalid get method specified. Try using\n               JTask.get(\"filename\", 1) instead.\n\n-"
+      end
+    else
+      # No retrieval method supplied, so output all the objects from the file :)
+      output = objects
+    end
+    
+    return output
+  end
+end

data/lib/jtask/kill.rb

@@ -0,0 +1,14 @@
+module Kill
+  def kill(filename, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    end
+
+    # Delete the file
+    File.delete(File.join(dir, filename))
+    
+    return true
+  end
+end

data/lib/jtask/rename.rb

@@ -0,0 +1,14 @@
+module Rename
+  def rename(filename, new, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    end
+    
+    # Rename the file
+    File.rename(File.join(dir, filename), File.join(dir, new))
+
+    return true
+  end
+end

data/lib/jtask/save.rb

@@ -0,0 +1,42 @@
+module Save
+  def save(filename, parameters, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    end
+    # Check if the file already exists
+    unless File.exists?(File.join(dir, filename))
+      # Create the file since it doesn’t exist, and setup up for JSON.
+      File.open(File.join(dir, filename), "w+") { |file| file.write("{}") }
+    end
+    # Validate haash supplied for parameters
+    unless parameters.is_a?(Hash)
+      raise SyntaxError, "\n\nJTask Error => Invalid value supplied to the parameters variable.\n               Ensure your parameters are in a symbol hash form\n               like - {name: \"Adam\", city: \"Melbourne\"}\n\n-"
+    end
+    
+    original_file = File.read(File.join(dir, filename))
+    objects = JSON.parse(original_file)
+    # Set the id of the new object
+    if (objects.to_a).first
+      # Add 1 to last object id
+      nextid = (objects.to_a).last[0].to_i + 1
+    else
+      # 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
+    # Extra } used to replace the one we took out originally
+    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

@@ -0,0 +1,22 @@
+module Update
+  def update(filename, id, parameters, dir=nil)
+    # Check if user has specified a custom directory.
+    unless dir
+      # If not, a default folder is assigned.
+      dir = "models/"
+    end
+    original_file = File.read(File.join(dir, filename))
+    objects = JSON.parse(original_file)
+
+    insert = objects
+    parameters.each do |k, v|
+      # 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)
+
+    return true
+  end
+end

data/license.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Adam McArthur (@adammcarth)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/readme.md

@@ -0,0 +1,117 @@
+# JTask
+
+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:
+
+    JTask.save("preferences", {background_color: "black", font_size: "medium"})
+    #=> true
+
+    JTask.get("preferences", 1)["font_size"]
+    #=> "medium"
+
+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.
+
+**Example of JTask storage file:**
+
+    {
+      "1": {
+        "background_colour": "black",
+        "font_size": "medium"
+      }
+    }
+
+Sequential ID's are automatically assigned to JSON objects on save.
+
+### JTask.save(filename, parameters, dir=nil)
+*Saves a hash of parameters to the requested file.*
+
+    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/")
+    
+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("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"
+    
+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"=>{..}}
+
+### JTask.update(filename, id, parameters, dir=nil)
+*Updates the record with `id` with a new set of parameters.*
+
+    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" } }
+
+To completely remove parameters (the entire key-value pair) from objects, refer to the JTask.chop() method below.
+
+### JTask.destroy(filename, id, dir=nil)
+*Removes an entire object from the file.*
+
+    JTask.destroy("twitter_names", 15)
+    
+### JTask.chop(filename, id, paramter, dir=nil)
+*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")
+    
+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).
+
+### JTask.rename(filename, new, dir=nil)
+*Simply renames the file to something different.*
+
+    JTask.rename("orders", "online_orders")
+    
+### JTask.kill(filename, dir=nil)
+*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")
+    
+## 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).
+
+To contribute to the project, fork it, send a pull request and I'll review your changes. Check out the `todo.txt` list to see what still needs to be done.
+
+\- Adam

data/todo.txt

@@ -0,0 +1,3 @@
+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().

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: jtask
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Adam McArthur
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: CRUD actions for JSON files.
+email: adam@adammcarthur.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- ".gitignore"
+- jtask.gemspec
+- lib/.DS_Store
+- lib/jtask.rb
+- lib/jtask/.DS_Store
+- lib/jtask/chop.rb
+- lib/jtask/destroy.rb
+- lib/jtask/get.rb
+- lib/jtask/kill.rb
+- lib/jtask/rename.rb
+- lib/jtask/save.rb
+- lib/jtask/update.rb
+- license.txt
+- readme.md
+- todo.txt
+homepage: https://github.com/adammcarthur/jtask
+licenses:
+- MIT
+metadata: {}
+post_install_message: |2-
+
+  Thanks for installing JTask Beta. Check out the full documentation and contribute at https://github.com/adammcarthur/jtask
+
+  - Adam (@adammcarth)
+  -
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Provides CRUD actions for JSON files, plus a few extra goodies.
+test_files: []