paradeiser 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bee8d6c4f066abbede76f32b8bd4bb6eaffadce7
-  data.tar.gz: 220abdcc0e1bcdf6ef2d2819c5c903508f42da8a
+  metadata.gz: dd9b4f1eb7fe225041e03d1824dcfce44b17e680
+  data.tar.gz: 010a924c64c9ffc32d18a68324afd6a8a79b46fe
 SHA512:
-  metadata.gz: 82e436e805e7159115ef9b814140f7e62ba1363d9e4af9fc6b18b9cf0bdbbb1efb355fe74f3febe19a61780989ff70df917b8dfbbf7f1229d7f1c79684bc9854
-  data.tar.gz: 40435ad4870ec1e3479bd9f82ef6168cd515cd89f6b0f437646092e1ab8d6d5e34301f93b5a8460f8286847365f7554c43bfeb3a1ba654b119568a8d50a03016
+  metadata.gz: e0ab299f7782dd479bc50981b203a02a8e69725a3b89559ac6683dcdbcadd8197c6bacccf34b9084193d08d46cbb6b704a2013bea2234a23717d350a3378406b
+  data.tar.gz: 46eb79b934a8210f6ceff2f25855905f06dbcae751a445039e33d49e5ee44b4f57663bff1c9ca29c1001bc6c5dd19ee5b78201e0c71e575207920c9ea4027cfa

data/.travis.yml

@@ -6,3 +6,4 @@ rvm:
 before_install:
  - sudo apt-get update
  - sudo apt-get install at
+ - export PATH=${TRAVIS_BUILD_DIR}/test/bin:${PATH}

data/Guardfile

@@ -14,4 +14,5 @@ guard 'minitest' do
   # Integration tests
   watch(%r{^bin/([^/]+)$}){|m| "test/integration/test_#{m[1]}.rb"}
   watch(%r|^test/integration/test_(.*)\.rb|){|m| "test/integration/test_#{m[1]}.rb"}
+  watch(%r|^test/lib/*\.rb|){'test'}
 end

data/README.md

@@ -32,20 +32,42 @@ This is scoped to a single user account (not just the `$PAR_DIR` directory, but
 
       $ par pomodoro start
 
+      # Abbreviated version:
+      $ par start
+
 If a break is still active, it will be stopped before the new pomodoro is started. Because of Rule #1, calling start while a pomodoro is active will print an error message.
 
 ### Finish the pomodoro
 
       $ par pomodoro finish
 
+      # With annotation:
+      $ par pomodoro finish This one went very well.
+
+      # Abbreviated version:
+      $ par finish
+
+      # Abbreviated version with annotation:
+      $ par finish This one went very well.
+
 If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not. Remaining arguments, if present, will be added to the pomodoro as annotation.
 
 If there is no active pomodoro, an error message will be printed.
 
 ### Record an interruption of the current pomodoro
 
+      $ par pomodoro interrupt
+      $ par pomodoro interrupt --external
+
+      # Abbreviated version:
       $ par interrupt
-      $ par interrupt --external
+
+      # With annotation:
+      $ par pomodoro interrupt Could not help checking my mail
+      $ par pomodoro interrupt --external VP of engineering walked into my office
+
+      # Abbreviated version with annotation:
+      $ par interrupt Could not help checking my mail
 
 Remaining arguments, if present, will be added to the interrupt as annotation. If no pomodoro is active, the command will throw an error.
 
@@ -55,15 +77,48 @@ Remaining arguments, if present, will be added to the interrupt as annotation. I
 
 If there is an active pomodoro, an error message will be printed. The `start` command is optional and may be omitted (it's only there for symmetry with `par break finish`, see the section about `at`).
 
-By default the break will be five minutes long.
+There is a command to stop a break (see also the section about `at`):
+
+      $ par break finish
+
+From a user's perspective it isn't really necessary to call `par break finish`, because either a new pomodoro is started, which will implicitely stop the active break, or the break ends naturally because it is over.
 
-While there is a command to stop a break (see the section about `at`), it isn't really necessary to call it from a user's perspective. Either a new pomodoro is started, which will implicitely stop the break, or the break ends naturally because it is over. We do not track break time.
+We do not track break time.
+
+### Annotate a pomodoro
+
+      $ par pomodoro annotate This was intense, but I am happy about the work I finished.
+
+      # Abbreviated version:
+      $ par annotate This was intense, but I am happy about the work I finished.
+
+The annotation will be added to the active or, if none is active, to the most recently finished or cancelled pomodoro. If no text is given, the annotation text is read from STDIN.
+
+Breaks cannot have annotations.
 
 ### Cancel the pomodoro
 
+      $ par pomodoro cancel
       $ par pomodoro cancel Just couldn't concentrate anymore.
 
-It will be marked as unsuccessful (remember, a pomodoro is indivisible). If no pomodoro is active, the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
+      # Abbreviated version:
+      $ par cancel
+
+      # Abbreviated version with annotation:
+      $ par cancel Just couldn't concentrate anymore.
+
+The pomodoro will be marked as canceled and the timer will be cleared. If no pomodoro is active, the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
+
+### Log a pomodoro or break
+
+Add a successfully finished pomodoro that was never recorded as being started (maybe the user forgot to call `par pomodoro start`):
+
+      $ par pomodoro log
+
+      # Abbreviated version:
+      $ par log
+
+It will appear in the reports and will count towards efficiency calculations. The current time will be used for the finish timestamp, and the start time will be calculated backwards from the finish time based on the default length of a pomodoro / break.
 
 ### Initialize Paradeiser
 
@@ -106,7 +161,7 @@ Paradeiser uses a dedicated at queue named 'p' to organize its jobs and to preve
 
 ## Status
 
-Paradeiser can print the current status to STDOUT with the `par status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
+Paradeiser can print the current status to STDOUT with the `par status` command. The current state is also provided as process exit status (which is useful when the output is suppressed).
 
 * Given an active pomodoro:
 
@@ -146,7 +201,30 @@ Paradeiser can print the current status to STDOUT with the `par status` command.
 
 ## Reports
 
+Without arguments, a report is shown for all pomodori and breaks.
+
       $ par report
+      # Pomodoro Report
+      - 6 pomodori finished
+      - 1 pomodoro canceled
+      - 2 internal interrupts
+      - 2 external interrupts
+      - 4 breaks (14 minutes in total)
+
+      ## Annotations
+      * You may pass an annotation to finish.
+      * Interrupts take annotations, too.
+      * Internal interrupts take annotations, too.
+      * And the last annotation is added via cancel.
+
+Note that the annotations section is not shown if there are no annotations.
+
+### Report Formatting
+By default The output of reports is formatted as [markdown](http://TODO), so that it can easily be read at the command line, but also piped into a markdown processor, e.g. for HTML generation with [redcloth](http://TODO):
+
+      $ par report | redcloth | bcat
+
+Here, the HTML produced by redcloth is piped into `bcat`, which opens a browser with the produced HTML.
 
 ## Output Policy
 Paradeiser follows the [Rule of Silence](http://www.faqs.org/docs/artu/ch01s06.html#id2878450). If all goes well, a command will not print any output to `STDOUT` unless `--verbose` is given. `status`, `report` and `timesheet` are exempted from this rule, as their primary purpose is to print to STDOUT.
@@ -169,8 +247,10 @@ Instead of handling tasks itself, Paradeiser integrates with external tools via
 * `after-start-break` is called after the processing of the break start action ended.
 * `before-finish-break` is called after the timer of the current break fired (the break is over), but before the processing of the break finish action begins.
 * `after-finish-break` is called after the processing of the break finish action ended.
+
 * `before-interrupt-pomodoro` is called when the `interrupt` command was received, but before the action processing begins.
 * `after-interrupt-pomodoro` is called after the processing of the `interrupt` action ended.
+
 * `before-cancel-pomodoro` is called when the `cancel` command was received, but before the processing of the cancel action begins.
 * `after-cancel-pomodoro` is called after the processing of the `cancel` action ended.
 
@@ -192,6 +272,13 @@ Variable | Used in | Description
 `$PAR_BREAK_ID` | Hooks | Identifier of the break
 `$PAR_BREAK_STARTED_AT` | Hooks | Timestamp of when the break was started
 
+## Export
+
+Paradeiser can export the pomodori and breaks it has stored to JSON:
+
+      $ par export
+      [{"type":"Pomodoro","length":1500,"status":"finished","interrupts":[],"annotati ...
+
 ## Similar Projects
 
 These and many more exist, why another tool?
@@ -204,9 +291,14 @@ They have a lot of what I wanted, but pomo focuses very much on the tasks themse
 ## Implementation Notes
 
 ### State Machine
-Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model a pomodoro. Internal event handlers do the actual work; among them is the task of calling the external hooks.
+Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model the state of pomodori and breaks. Internal event handlers do the actual work. Calling the external hooks is one of these tasks.
+
+Pomodoro:
 
 ![State Transition Diagram for Pomodoro](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+
+Break:
+
 ![State Transition Diagram for Break](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Break_status.svg)
 
 The graph was created using the rake task that comes with `state_machine`:

data/TODO.md

@@ -1,16 +1,32 @@
 # Paradeiser Backlog
 
-* Add `par report` with a single (global) view that implements the report format described in the vision document (but isn't scoped yet)
+* By default, hooks copied by `par init` should not be executable, otherwise the hooks will fail if the optional dependencies (e.g. `notify-send` on Linux) are not present
 
-* Implement `par pomodoro annotate` and annotations for most commands. Alias it it `par annotate`.
+* Add validations to models. `finished_at` must occur at after created at, etc.
+
+* There must be no overlap in pomodori, even if we log one.
+  - Logging one while another one is active must fail unless finished at is before the active one's started at.
+
+* `par log` needs options for when the logged pomodoro was started and / or stopped
+
+* Improve tests with more doubles
+  - Sandy Metz rules about testing messages:
+    - Incoming: Assert state
+    - Outgoing
+      * Queries: Ignore
+      * Commands: Expect behavior
+
+* Implement scoped reports
+
+* `par timesheet`
+  - Implement basic timesheet (global; not grouped by anything)
+  - Show all annotations next to each pomodoro, interrupt and break
 
 * Improve status messages with relative times and dates (`distance_of_time_in_words_to_now`)
   => action_view/helpers/date_helper
 
 * Simplify the status view. Separate views by class (break vs. pomodoro).
 
-* Refactor the hooks tests: extract the common code
-
 * Whenever par runs, it should garbage-collect pomodori or breaks (finish them and adjust their finish time) that weren't finished after they were over (e.g. because at isn't there or the hooks did not fire)
 
 * Extend commander to allow abbreviated commands with Ruby's `Abbrev` module
@@ -42,7 +58,7 @@
   - test with `if $stdin.tty?`
   - If that approach works well, suggest it for TaskWarrior too (for bulk actions, e.g. in scripts)
 
-* Implement documentation Approach
+* Implement documentation approach
   - `par help` is what the user will use to get information.
   - Not sure how to allow the user to look at features that are not related to a command. Either extend `par help` to accept arbitrary keywords, or look into 'gem man`.
 
@@ -55,7 +71,7 @@
   - As part of finishing a feature, the feature file is moved from the backlog file to in individual doc file, and the README is updated to mention that feature.
 
 * Promote Paradeiser
-  - Publish an [ASCII cast](http://ascii.io/)
+  - Publish an [ASCII cast](http://ascii.io/) or with [Showterm](http://showterm.io/)
   - Tell the TaskWarrior community about Paradeiser
   - Tell the Pomodoro community about Paradeiser
   - Tell the Ruby community about Paradeiser (e.g. @neverbendeasy does kanban)

data/VISION.md

@@ -32,21 +32,42 @@ This is scoped to a single user account (not just the `$PAR_DIR` directory, but
 
       $ par pomodoro start
 
+      # Abbreviated version:
+      $ par start
+
 If a break is still active, it will be stopped before the new pomodoro is started. Because of Rule #1, calling start while a pomodoro is active will print an error message.
 
 ### Finish the pomodoro
 
       $ par pomodoro finish
+
+      # With annotation:
       $ par pomodoro finish This one went very well.
 
+      # Abbreviated version:
+      $ par finish
+
+      # Abbreviated version with annotation:
+      $ par finish This one went very well.
+
 If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not. Remaining arguments, if present, will be added to the pomodoro as annotation.
 
 If there is no active pomodoro, an error message will be printed.
 
 ### Record an interruption of the current pomodoro
 
+      $ par pomodoro interrupt
+      $ par pomodoro interrupt --external
+
+      # Abbreviated version:
       $ par interrupt
-      $ par interrupt --external
+
+      # With annotation:
+      $ par pomodoro interrupt Could not help checking my mail
+      $ par pomodoro interrupt --external VP of engineering walked into my office
+
+      # Abbreviated version with annotation:
+      $ par interrupt Could not help checking my mail
 
 Remaining arguments, if present, will be added to the interrupt as annotation. If no pomodoro is active, the command will throw an error.
 
@@ -58,29 +79,63 @@ If there is an active pomodoro, an error message will be printed. The `start` co
 
 By default the break will be five minutes long. After four pomodori within a day, the break will be 30 minutes long. This can be overridden with `--short` or `--long`, with an optional argument value that determines the lenght of the break in minutes (e.g. `par break --short=10`).
 
-While there is a command to stop a break (see the section about `at`), it isn't really necessary to call it from a user's perspective. Either a new pomodoro is started, which will implicitely stop the break, or the break ends naturally because it is over. We do not track break time.
+There is a command to stop a break (see also the section about `at`):
+
+      $ par break finish
+
+From a user's perspective it isn't really necessary to call `par break finish`, because either a new pomodoro is started, which will implicitely stop the active break, or the break ends naturally because it is over.
+
+We do not track break time.
 
 ### Annotate a pomodoro
 
       $ par pomodoro annotate This was intense, but I am happy about the work I finished.
 
+      # Abbreviated version:
+      $ par annotate This was intense, but I am happy about the work I finished.
+
 The annotation will be added to the active or, if none is active, to the most recently finished or cancelled pomodoro. If no text is given, the annotation text is read from STDIN.
 
 Breaks cannot have annotations.
 
 ### Cancel the pomodoro
 
+      $ par pomodoro cancel
       $ par pomodoro cancel Just couldn't concentrate anymore.
 
-It will be marked as unsuccessful (remember, a pomodoro is indivisible). If no pomodoro is active, the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
+      # Abbreviated version:
+      $ par cancel
+
+      # Abbreviated version with annotation:
+      $ par cancel Just couldn't concentrate anymore.
 
-### Log a pomodoro
+The pomodoro will be marked as canceled and the timer will be cleared. If no pomodoro is active, the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
+
+### Log a pomodoro or break
+
+Add a successfully finished pomodoro that was never recorded as being started (maybe the user forgot to call `par pomodoro start`):
 
       $ par pomodoro log
 
-Add a successfully finished pomodoro that was never recorded as being started (maybe the user forgot to call `par pomodoro start`). It will appear in the reports and will count towards efficiency calculations.
+      # Abbreviated version:
+      $ par log
+
+      # Logging a break is also possible:
+      $ par break log
 
-The current time will be used for the finish timestamp, and the start time will be calculated from the finish time backwards.
+It will appear in the reports and will count towards efficiency calculations. The current time will be used for the finish timestamp, and the start time will be calculated backwards from the finish time based on the default length of a pomodoro / break.
+
+### Delete a pomodoro or break
+
+      $ par delete
+
+Without arguments, the active pomodoro or break will be canceled and then deleted. If none is active, the most recently finished or cancelled pomodoro or break is deleted. Note that there is no long form of this command as it pertains to pomodori _and_ breaks.
+
+A specific pomodoro or break to be deleted can be specified as argument:
+
+      $ par delete 42
+
+This will delete the pomodoro or break identified as #42.
 
 ### Initialize Paradeiser
 
@@ -183,7 +238,7 @@ Paradeiser uses a dedicated at queue named 'p' to organize its jobs and to preve
 
 ## Status
 
-Paradeiser can print the current status to STDOUT with the `par status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
+Paradeiser can print the current status to STDOUT with the `par status` command. The current state is also provided as process exit status (which is useful when the output is suppressed).
 
 * Given an active pomodoro:
 
@@ -246,37 +301,96 @@ Paradeiser can print the current status to STDOUT with the `par status` command.
 
 ## Reports
 
+Without arguments, a report is shown for the most recent pomodoro or break.
+
+* Given the most recent item was a pomodoro, finished today:
+
       $ par report
-      Daily Pomodoro Report for 2013-07-16
+      # Report for pomodoro #12
+
+      Started 17:07, finished 17:32
+
+      ## Interrupts
+      0 internal
+      0 external
+
+      ## Annotations
+      * This one went very well.
+
+A report can produced for a specific pomodoro or break (here, it was started earlier today and then cancelled after a few interruptions):
+
+      $ par report 11
+      # Report for pomodoro #11
+
+      Started 11:34, canceled 11:40
 
-      3 pomodori finished
-      1 pomodoro cancelled
-      1 internal interruptions
-      2 external interruptions
-      4 breaks (3 short, 1 long; 45 minutes in total)
+      ## Interrupts
+      2 internal:
 
-      Most efficient location: Home Office
-      Least efficient location: Coffeshop
+      * Could not help checking my mail
+      * Surfin' the web
 
-By default, the command groups by `--day`. Alternative options are `--week`, `--month` or `--year`. Without a value, the argument assumes the current day / week / month / year. The first day of the period can be specified as argument, e.g. `par report --day=2013-07-18`. The period is parsed with [Chronic](http://chronic.rubyforge.org/), which also enables symbolic values like `par report --month="last month"`.
+      1 external:
+      * VP of engineering walked into my office
+
+      # Annotations
+      * Right before lunch doesn't seem like a good time for a pomodoro.
+
+Reports can also be grouped by `--day`, `--week`, `--month`, `--year`, or `--all`:
+
+      $ par report --day
+      # Daily Report for 2013-07-16
+
+      ## Pomodori
+      - 3 finished
+      - 1 cancelled
+
+      ## Interrupts
+      - 1 internal
+      - 2 external
+
+      ## Breaks
+      - 3 short
+      - 1 long
+
+      Total: 4 breaks, 45 minutes
+
+      ## Locations
+      Most efficient: Home Office
+      Least efficient: Coffeshop
+
+Without a value, the argument assumes the current day / week / month / year. The first day of the period can be specified as argument, e.g. `par report --day=2013-07-18`. The period is parsed with [Chronic](http://chronic.rubyforge.org/), which also enables symbolic values like `par report --month="last month"`.
+
+Note that the annotations section is not shown if there are no annotations.
 
 The report can also be grouped by location:
 
-      $ par report location
-      Pomodoro Location Report
+      $ par report --location
+      # Location Report
+
+      ## Home Office
+      38 finished
+      12 cancelled
+      21 interrupts
 
-      Home Office: 38 finished, 12 cancelled, 21 interrupts
-      Starbucks:   12 finished, 2 cancelled, 45 interrupts
-      On the road: 14 finished, 0 cancelled, 12 interrupts
+      ## Starbucks
+      12 finished
+      2 cancelled
+      45 interrupts
+
+      ## On the road
+      14 finished
+      0 cancelled
+      12 interrupts
 
       The following locations do not have a label. Assign it with
 
-        $ par location macbook@01:23:45:67:89:0A "Your Label"
+        $ par --location macbook@01:23:45:67:89:0A "Your Label"
 
 Detailed report for a single location:
 
-      $ par report location "Home Office"
-      Pomodoro Location Report for Home Office
+      $ par report --location="Home Office"
+      # Location Report for Home Office
 
       58 pomodori finished
       12 pomodoro cancelled
@@ -288,7 +402,7 @@ Detailed report for a single location:
 
 Further grouping is also possible, e.g. by year:
 
-      $ par report location --year=2012
+      $ par report --location --year=2012
       Pomodoro Location Report for 2012
 
       233 pomodori finished
@@ -323,6 +437,13 @@ Efficiency can be reported by day, week, month, year, or location:
 
 The same options as for regular reports apply. The timesheet report also details the efficiency of each location.
 
+### Report Formatting
+By default The output of reports is formatted as [markdown](http://TODO), so that it can easily be read at the command line, but also piped into a markdown processor, e.g. for HTML generation with [redcloth](http://TODO):
+
+      $ par report | redcloth | bcat
+
+Here, the HTML produced by redcloth is piped into `bcat`, which opens a browser with the produced HTML.
+
 ### Exporting a Report
 
       $ par report --weekly --format JSON # weekly report in JSON format
@@ -407,6 +528,25 @@ The configuration is stored in a config file. It is user-editable file, but edit
   `PAR_DIR` | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`. Overridden by `$PAR_DIR`.
   `AT_QUEUE` | Name of the `at` queue to use. Defaults to `p`.
 
+## Export
+
+Paradeiser can export the pomodori and breaks it has stored to JSON:
+
+      $ par export
+      [{"type":"Pomodoro","length":1500,"status":"finished","interrupts":[],"annotati ...
+
+## Import
+
+Paradeiser can import pomodori and breaks from a JSON file:
+
+      $ par import pomodori.json
+
+If the second argument is missing, `par import` will expect the JSON that is to be imported to appear on STDIN:
+
+      $ cat pomodori.json | par import
+
+If the import succeeds, no further message will printed and the exit status will be zero. If there is an existing pomodoro or break that overlaps with one imported from JSON, the entire import will fail and paradeiser will exit with a non-zero exit status.
+
 ## Taskwarrior Integration
 
 This is deployed to `~/.paradeiser/hooks/after-finish` by default.
@@ -433,9 +573,14 @@ They have a lot of what I wanted, but pomo focuses very much on the tasks themse
 ## Implementation Notes
 
 ### State Machine
-Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model a pomodoro. Internal event handlers do the actual work; among them is the task of calling the external hooks.
+Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model the state of pomodori and breaks. Internal event handlers do the actual work. Calling the external hooks is one of these tasks.
+
+Pomodoro:
 
 ![State Transition Diagram for Pomodoro](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+
+Break:
+
 ![State Transition Diagram for Break](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Break_status.svg)
 
 The graph was created using the rake task that comes with `state_machine`: