JTask ( ).save

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.json", {background_color: "black", font_size: "medium"})
#=> true

JTask.get("preferences.json", last: 1).font_size
#=> "medium"

The above example stores the settings in a file called preferences.json. We then get the last object saved to the file and output the value of the "font_size" key. JTask syntax is designed to be simple and elegant to use, making it easy to remember and enjoyable to work with. It even has it's own built in error handler:

JTask.get("clients.json", :all)
#=> NameError: [JTask] Couldn't find the file specified at 'models/clients.json'. Try running JTask.save("clients.json") to setup a blank file.

The above error makes mention of an id number. As central to many CRUD frameworks, JTask operates around id numbers to manipulate the objects. JTask automatically calculates and assigns these sequential id numbers for you.

Example of JTask storage file:

{
  "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 wiki guide for more information.

Getting Started

gem install jtask

require "jtask"

# Tell JTask where your files are [optional]
JTask.configure do |config|
  config.file_dir = "path/to/jtask_files/"
end

Basic Documentation

Below you will find a very broad overview of how to use the most common JTask methods. Make sure you check out the wiki for the full documentation and implementation examples.

---

JTask.save(filename, parameters, dir)

Saves a hash of parameters to the requested file.

JTask.save("foods.json", {entree: "cheese", main: "hamburger", desert: "cake"})

Custom directories can be set each time (refer to below). 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, dir)

Retrieves stored JSON data from the file and returns an OpenStruct.

JTask.get("email_subscribers.json")
#=> [ #<JTask::Get "id"=1 "email"="[email protected]">, #<JTask::Get "id"=2 "email"="blah"> ... ]

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.json", 50)
#=> #<JTask::Get "id"="50" "email"="[email protected]">

@subscriber.email
#=> "[email protected]"

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.json", first: 25)
#=> [ #<JTask::Get "id"=1>, #<JTask::Get "id"=2>, ..., #<JTask::Get "id"=25> ]

JTask.get("email_subscribers.json", last: 1)
#=> #<JTask::Get "id"=365 "email"="[email protected]">

---

JTask.update(filename, id, parameters, dir)

Updates an existing JSON object with a new set of values.

JTask.update("ui_settings.json", 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
#<JTask::Get "id"=42 "show_ads"="yes">

# Updated Version
#<JTask::Get "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)

Removes an entire object from the file.

---

JTask.chop(filename, id, paramter, dir)

Removes an entire key-value pair from one or all of the file's objects.

---

JTask.rename(filename, new, dir)

Simply renames the file to something different.

---

JTask.kill(filename, dir)

Completely removes the entire file specified from the system.

---

Share your ideas and contribute

I'd love to here what you plan to use JTask for. Let me know via twitter, or email your thoughts and ideas to [email protected].

My favourite feedback so far:

"JTask is probably useful."

To contribute to the project, fork it (also create a new feature branch if your changes are substantial), send a pull request and I'll review your changes. Check out the enhancement suggestions page to see what still needs to be done.

- Adam