rtasklib 0.1.0 → 0.1.1.pre.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c60a1881ed6632325dec8f7b90b7945bd04e1d9
-  data.tar.gz: 0f9414694814029b834ab9031828bc0b6b56f1b2
+  metadata.gz: cbef69d8085f3de726027c8c93d277d1b5e95e6b
+  data.tar.gz: efc01dfeb85579ba8539ea68df1ccf216684ea10
 SHA512:
-  metadata.gz: b78ea752b977227baced57676296360a5349c300ca84d7136d0b25dcfc8039fa1bea2ff8e10fbb6d56bc5afd82c95ba1820bb79fa090850e151a9ce6b71b69fe
-  data.tar.gz: 26217f53ae87e4cda5cead70454adec4a07f10900435acc8cb9188f4050d6670b08d33fe646558c8a81bda3958193c7f534a5930ebd34acc4681f26042ca3c86
+  metadata.gz: ca2de133e12b01df7a4403948b946b9e018447921ea384714fc3c1a6e824e33e2175179b324bb9210bef56817500ca05e0378dd3ba5d093c9986de310477b760
+  data.tar.gz: 5e487152aa6a0a98b6d615e5bca94d10123d3eee416da29f35e98eaa55e7f567d528a5c600ae958aa83d306c79195fe8fe36e6aaa8466c05fa44d4bf753e67be

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -3,7 +3,10 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
+/doc/
 /spec/reports/
 /tmp/
+*.py
+lib/rtasklib/marshallable.rb
+spec/marshallable_spec.rb

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.3

data/.travis.yml

@@ -1,3 +1,32 @@
 language: ruby
+
 rvm:
-  - 2.0.0
+    - 2.1.3
+
+env:
+    - TASKWARRIOR=v2.4.1
+
+before_install:
+    - gem install bundler
+    - sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
+    - sudo apt-get update -qq
+    - sudo apt-get install -qq build-essential cmake uuid-dev g++-4.8
+    - sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.8 50
+    - git clone https://git.tasktools.org/scm/tm/task.git
+    - cd task
+    - git checkout $TASK_VERSION
+    - git clean -dfx
+    - cmake .
+    - make
+    - sudo make install
+    - pwd
+    - cd ../
+    - ls /home/travis/build/dropofwill/rtasklib/spec/data/.task
+    - export TASKRC=/home/travis/build/dropofwill/rtasklib/spec/data/.taskrc
+    - export TASKDATA=/home/travis/build/dropofwill/rtasklib/spec/data/.task
+    - task _version
+
+script: 'bundle exec rake'
+
+notifications:
+    email: false

data/Guardfile

@@ -0,0 +1,11 @@
+guard 'rspec', cmd: "bundle exec rspec --color --format=doc --format=Nc" do
+  # watch /lib/ files
+  watch(%r{^lib/(.+).rb$}) do |m|
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  # watch /spec/ files
+  watch(%r{^spec/(.+).rb$}) do |m|
+    "spec/#{m[1]}.rb"
+  end
+end

data/PLAN.md

@@ -0,0 +1,204 @@
+# rtasklib
+
+## Public API
+
+
+rtasklib::
+
+For now require `task --version` > 2.4.0, we can work on backwards
+compatibility later.
+
+### TaskWarrior Direct
+
+* #filter(filter_string)
+  just send random shit to task and handle the probable errors properly
+  `task #{filter_string} export`
+
+* add(
+
+### ActiveRecord API
+
+#### Required
+
+* #where()
+  takes string or hash arguments
+  strings get past directly to `task <filter> export`
+  returns a chainable relationship, instead of the raw objects of #find
+
+* #find(uuid | id)
+  #find([uuid | id, ...])
+
+* #take(num=1)
+
+* #first(num=1)
+  #last(num=1)
+  Num is how many to return
+  Should this be by urgency or id or uuid?
+
+* #find_by(key: value)
+  e.g. #find_by(project: "LinuxDev") which is the same as
+  #where(project: "LinuxDev").take or .first
+
+  #find_by!(key: value) is the same, but throws an error
+
+* #all()
+
+* #order()
+  either sql style string or AR style hash:
+  "created at DESC" or created_at: :desc
+  Chainable on relations from #where
+
+* #select() alias #project()
+  same as #order()
+  Only returns the listed columns
+
+* #distinct()
+  same as #take() but for selection/projections
+
+* #limit(num)
+  maximum number of rows to return
+
+* #offset(num)
+  change the starting point of a query
+
+* #readonly()
+
+* #find_or_create_by(), #find_or_create_by!()
+
+* #count alias #size, #length
+
+* #pluck()
+
+* #exists?()
+
+* #explain() show underlying command structure
+
+
+#### Probs should, but nah
+
+* Optimistic or Pessimistic locking to prevent race conditions
+
+* Eager loading
+
+* Scopes
+
+
+#### Maybe
+
+* #average(), #minimum(), #maximum(), #sum()
+
+* #none(), returns an empty relation, useful in chains perhaps?
+
+* #find_each(), #find_in_batches()
+  load all tasks in in batches, unnecessary for the task interface?
+
+* #joins()? Maybe for dependencies?
+
+* #group()? Out of scope probably? Needs a motivating use case.
+
+* #having()? Require group to be working first
+
+* #unscope, #only, #reorder, #reverse_order, #rewhere
+  These exist for performance reasons in SQL, probably not necessary for us.
+
+
+
+## [TaskWarrior 3rd-Party Guidelines]()
+
+Taskwarrior can be extended by means of a third-party application. There are script examples of import and export add-ons that support many different formats (clone the repository, look in task.git/scripts/add-ons). Then there are more sophisticated applications such as Vit that provide a complete replacement UI.
+
+All of these provide interesting new features and improve ease of use for different kinds of users. We encourage you to create such add-ons, but in doing so, there are some rules that must be followed, which will not only protect the users data from mistreatment, but also your application from being sensitive to changes in Taskwarrior.
+
+### Rules
+
+* Produce, consume and handle UTF8 text properly. UTF8 is the only text encoding supported by Taskwarrior.
+
+* Don't attempt to parse the pending.data file. Here's why: the .data file format is currently on its fourth version. The very first version was never released, so if you want to read Taskwarrior data properly, you will need to parse the three supported formats. Those formats are not documented. Additionally, you will need to handle the GC operations, implement the task "unwait" feature, observe user defined attribute handling restrictions, and implement recurring task synthesis all of which require .taskrc and default value access. You would essentially be rewriting the data access and configuration portion of Taskwarrior, which is a major undertaking. To support filters you would also need to evaluate the supported clauses, provide DOM access and implement aliases. Then there is also the fifth data format, which is planned...
+
+* Use the export command to query data from Taskwarrior. The export command implements filters which you can use, or you can omit a filter, get all the data, and implement your own filtering. JSON parsing is very well supported in all relevant programming languages, which means you should be using Taskwarrior itself to query the data, with a commodity JSON parser in conjunction. While the JSON format will be tweaked over time, the general form will not.
+
+* Use the command line interface to put data into Taskwarrior. Composing a valid command line is a simple way to put data in to Taskwarrior, and the ONLY way to modify data in Taskwarrior.
+
+* Verify feature support by running task --version. This command returns the version number, which will help you determine whether or not a particular feature is supported. Note that this command does not scan for a configuration file, and is therefore safe to run if Taskwarrior is not yet set up.
+
+* UDAs (User Defined Attributes) must be preserved in the data. When reading the JSON for a task, there may be attributes that you have never encountered before. If this is the case, you must not modify them in any way. This not only makes your application future-proof, but allows it to tolerate UDAs from other data sources. It also prevents the Taskserver from stripping out your data.
+Guidelines
+
+* If you need to store additional data, consider putting your own data file in the ~/.task directory. Just don't use the file names pending.data, completed.data, backlog.data, undo.data or synch.key.
+
+* There are many helper commands designed to assist add-on scripts such as shell completion scripts. These commands all begin with an underscore, see them with this command: `task help | grep ' _'`.
+
+* Familiarize yourself with the means of forcing color on or off, disabling word wrapping, disabling bulk operation limitations, disabling confirmation, disabling gc, modifying verbosity and so on. There are ways around almost all the restrictions, and while these don't make sense for regular users, they can be critical for add-on authors.
+
+## Classes
+
+```
+TaskWarriorException =>     optional?, TaskException
+
+
+ReadOnlyDictView =>         external, possibly IceNine
+
+    Deepcopies data to enforce immutability
+
+
+SerializingObject =>        internal, Serializer
+
+    TaskResource, TaskFilter < SerialObject
+
+    This is the key user-input -> data step
+
+    Serializing method should hold the following contract:
+        - any empty value (meaning removal of the attribute) is deserialized into a empty string
+
+        - None denotes a empty value for any attribute
+
+    Deserializing method should hold the following contract:
+        - None denotes an empty value for any attribute (however, this is here as a safeguard, TaskWarrior currently does not export empty-valued attributes) if the attribute is not iterable (e.g. list or set), in which case a empty iterable should be used.
+
+    Normalizing methods should hold the following contract:
+        - They are used to validate and normalize the user input. Any attribute value that comes from the user (during Task initialization, assignign values to Task attributes, or filtering by user-provided values of attributes) is first validated and normalized using the normalize_{key} method.
+
+        - If validation or normalization fails, normalizer is expected
+        to raise ValueError.
+
+    Normalize/Serialize/Deserialize the following data inputs:
+        - timestamps, should be localized, so to UTC before string: '%Y%m%dT%H%M%SZ'
+
+        - datetimes/dates, should be localized, default time=midnight
+
+        - annotations, should be an array of hashes
+
+        - tags, 'blah, blah'.split(',')
+
+        - depends, uuid
+
+        - possibly an array of data structure shoehorned into string since UDA doesn't
+
+    - Possible cool use case for meta-programming here.
+
+TaskResource =>     internal, TaskResource
+
+    inherits from Serializer
+
+TaskFilter =>       internal, TaskFilter
+
+    inherits from Serializer
+
+TaskAnnotation =>   internal, TaskAnnotation
+
+    inherits from TaskResource
+
+Task =>             internal, Task
+
+    inherits from TaskResource
+
+TaskQuerySet =>     internal, TaskLazyLook | TaskLookup
+
+    Lazy lookup for a task object
+
+TaskWarrior =>      internal, TaskWarrior
+
+    The main shebang
+
+
+```

data/README.md

@@ -1,8 +1,12 @@
 # Rtasklib
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rtasklib`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Coverage Status](https://travis-ci.org/dropofwill/rtasklib.svg?branch=master)](https://travis-ci.org/dropofwill/rtasklib) [![Coverage Status](https://coveralls.io/repos/dropofwill/rtasklib/badge.svg?branch=master)](https://coveralls.io/r/dropofwill/rtasklib?branch=master) [![yard docs](http://b.repl.ca/v1/yard-docs-blue.png)](http://will-paul.com/rtasklib)
+
+
+## Description
+
+A Ruby wrapper around the TaskWarrior CLI, based on the Python tasklib. Requires a working TaskWarrior install.
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
@@ -20,16 +24,33 @@ Or install it yourself as:
 
     $ gem install rtasklib
 
+
+## Dependencies
+
+* Taskwarrior > 2.4 (require custom UDAs, recurrences, and duration data types)
+
+* Ruby > 2 (currently untested on older versions)
+
+* See `./rtasklib.gemspec` for the latest Ruby dependencies
+
+
 ## Usage
 
 TODO: Write usage instructions here
 
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+
+## License
+
+Release under the MIT License (MIT) Copyright (©) 2015 Will Paul
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/rtasklib/fork )

data/Rakefile

@@ -1,10 +1,9 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-
 # run tests with `rake spec`
 RSpec::Core::RakeTask.new :spec do |task|
-  task.rspec_opts = ["--color", "--format", "nested"]
+  task.rspec_opts = ["--color", "--format=doc", "--format=Nc"]
 end
 
 task default: :spec

data/bin/console

@@ -1,14 +1,14 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "rtasklib"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+require_relative "../lib/rtasklib"
+require "pry"
 
-require "irb"
-IRB.start
+tw = Rtasklib::TaskWarrior.new("./spec/data/.task")
+
+binding.pry

data/bin/env

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require_relative "../lib/rtasklib"
+require "pry"
+
+Pry.start

data/lib/rtasklib/controller.rb

@@ -0,0 +1,50 @@
+require "multi_json"
+require "oj"
+
+module Rtasklib
+
+  module Controller
+    extend self
+
+    def create
+    end
+
+    def update
+    end
+
+    def get
+    end
+
+    def all
+      all = []
+      Execute.task_popen3(*@override_a, "export") do |i, o, e, t|
+        all = MultiJson.load(o.read).map do |x|
+          Rtasklib::Models::TaskModel.new(x)
+        end
+      end
+      return all
+    end
+
+    def get_rc
+      res = []
+      Execute.task_popen3(*@override_a, "_show") do |i, o, e, t|
+        o.read.each_line { |l| res.push(l.chomp) }
+      end
+      Taskrc.new(res, :array)
+    end
+
+    def get_version
+      version = nil
+      Execute.task_popen3(*@override_a, "_version") do |i, o, e, t|
+        version = to_gem_version(o.read.chomp)
+      end
+      return version
+    end
+
+    # Convert "1.6.2 (adf342jsd)" to Gem::Version object
+    def to_gem_version raw
+      std_ver = raw.chomp.gsub(' ','.').delete('(').delete(')')
+      Gem::Version.new std_ver
+    end
+  end
+end

data/lib/rtasklib/execute.rb

@@ -0,0 +1,89 @@
+require "open3"
+require "pty"
+require "expect"
+require "ruby_expect"
+require "stringio"
+
+module Rtasklib
+
+  # How to execute shell commands and capture output
+  module Execute
+    # so that the methods are available within the modules lookup path
+    extend self
+
+    @@exp_regex = {
+      create_rc: %r{Would \s you \s like \s a \s sample \s *.+ \s created, \s
+                    so \s taskwarrior \s can \s proceed\? \s
+                    \(yes/no\)}x }
+
+    # popen versions
+    #
+    def popen3 program='task', *opts, &block
+      execute = opts.unshift(program)
+      execute = execute.join(" ")
+      p execute
+
+      Open3.popen3(execute) do |i, o, e, t|
+        handle_response(e, t)
+        yield(i, o, e, t) if block_given?
+      end
+    end
+
+    def task_popen3 *opts, &block
+      popen3('task', opts, &block)
+    end
+
+    def each_popen3 program='task', *opts, &block
+      popen3(program, *opts) do |i, o, e, t|
+        o.each_line do |l|
+          yield(l, i, o, e, t)
+        end
+      end
+    end
+
+    def task_each_popen3 *opts, &block
+      popen3(program, *opts) do |i, o, e, t|
+        yield(i, o, e, t)
+      end
+    end
+
+    def handle_response stderr, thread
+      unless thread.value.success?
+        puts stderr.read
+        exit(-1)
+      end
+    end
+
+    # Non-greedy json object detection
+    # if /\{.*\}/ =~ l
+      # p l.chomp
+      # res.push(l.chomp)
+    # end
+    # def task create_new, *opts, &block
+    #   exp_regex = @@exp_regex
+    #   retval = 0
+    #   res = nil
+    #   buff = ""
+    #
+    #   run("task", *opts) do |exp, procedure|
+    #     res = procedure.any do
+    #       puts exp
+    #       expect exp_regex[:create_rc] do
+    #         if create_new
+    #           send "yes"
+    #         else
+    #           send "no"
+    #         end
+    #       end
+    #       block.call if block_given?
+    #     end
+
+    # Filters should be a list of values
+    # Ranges interpreted as ids
+    #   1...5 : "1-5"
+    #   1..5  : "1-4"
+    #   1     : "1"
+    #   and joined with ","
+    #   [1...5, 8, 9] : "1-5,8,9"
+  end
+end

data/lib/rtasklib/models.rb

@@ -0,0 +1,86 @@
+require "virtus"
+require "active_model"
+
+module Rtasklib::Models
+  ValidationError = Class.new RuntimeError
+
+  class UUID < Virtus::Attribute
+    def coerce(value)
+      value.to_s
+    end
+  end
+
+  RcBooleans = Virtus.model do |mod|
+    mod.coerce = true
+    mod.coercer.config.string.boolean_map = {
+      'no'  => false,
+      'yes' => true,
+      'on'  => true,
+      'off' => false }
+  end
+
+  class TaskrcModel
+    # A base Virtus model whose attributes are created dynamically based on the
+    # given attributes are read from a .taskrc or Hash
+    #
+    # Dynamically add convert Boolean Strings to Ruby's Boolean values
+    include RcBooleans
+  end
+
+  class TaskModel
+    include Virtus.model
+    # perhaps use Veto
+    include ActiveModel::Validations
+
+    # Default attributes from TW
+    # Should match: http://taskwarrior.org/docs/design/task.html
+    #
+    # Required for every task
+    attribute :description,   String
+    # But on creation these should be set by `task`
+    attribute :status,        String
+    attribute :uuid,          String
+    attribute :entry,         Date
+
+    # Optional for every task
+    attribute :start,         Date
+    attribute :until,         Date
+    attribute :scheduled,     Date
+    attribute :annotation,    Array[String]
+    attribute :tags,          Array[String]
+    attribute :project,       String
+    attribute :depends,       String
+    attribute :urgency,       Float
+    # is calculated, so maybe private?
+    attribute :priority,      String
+
+    # Required only for tasks that are Deleted or Completed
+    attribute :end,           Date
+
+    # Required only for tasks that are Waiting
+    attribute :wait,          Date
+
+    # Required only for tasks that are Recurring or have Recurring Parent
+    attribute :recur,         Date
+
+    # Optional except for tasks with Recurring Parents
+    attribute :due,           Date
+
+    # Required only for tasks that have Recurring Child
+    attribute :parent,        UUID
+
+    # Internal attributes should be read-only
+    attribute :mask,          String
+    attribute :imask,         String
+    attribute :modified,      Date
+
+    # TODO: handle arbitrary UDA's
+
+    # Refactoring idea, need to understand Virtus internals a bit better
+    # [:mask, :imask, :modified, :status, :uuid, :entry].each do |ro_attr|
+    #   define_method("set_#{ro_attr.to_s}") do |value|
+    #     self.class.find_by(ro_attr).send(".=", value)
+    #   end
+    # end
+  end
+end

data/lib/rtasklib/serializer.rb

@@ -0,0 +1,10 @@
+require "active_model"
+require "active_model/serializer"
+
+module Rtasklib
+
+  module Models
+    class TaskSerializer < ActiveModel::Serializer
+    end
+  end
+end