klipbook 1.0.2 → 2.0.0

data/CHANGELOG.txt

@@ -1,3 +1,16 @@
+== 2.0.0 / 2013-02-12
+
+* Feature changes
+
+	* Renamed the collate command to pretty print which describes what it does better.
+
+	* Introduces a _new_ collate command that collates all clippings into a single JSON
+file.
+
+* Other unexposed changes
+
+	* Internally refactored much of the codebase into a more sensible structure.
+
 == 1.0.2 / 2012-12-12
 
 * Bug fixes

data/Gemfile

@@ -10,7 +10,7 @@ group :development do
   gem 'bundler'
   gem 'jeweler', '~> 1.6.4'
   gem 'rcov', '>= 0'
-  gem 'pry'
+  gem 'pry-debugger'
   gem 'cucumber'
   gem 'aruba'
   gem 'guard'

data/Gemfile.lock

@@ -9,12 +9,20 @@ GEM
     builder (3.0.0)
     childprocess (0.3.5)
       ffi (~> 1.0, >= 1.0.6)
-    coderay (1.0.7)
+    coderay (1.0.8)
+    columnize (0.3.6)
     cucumber (1.2.1)
       builder (>= 2.1.2)
       diff-lcs (>= 1.1.3)
       gherkin (~> 2.11.0)
       json (>= 1.4.6)
+    debugger (1.2.4)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.1.1)
+      debugger-ruby_core_source (~> 1.1.7)
+    debugger-linecache (1.1.2)
+      debugger-ruby_core_source (>= 1.1.1)
+    debugger-ruby_core_source (1.1.8)
     diff-lcs (1.1.3)
     domain_name (0.5.6)
       unf (~> 0.0.3)
@@ -48,16 +56,19 @@ GEM
       nokogiri (~> 1.4)
       ntlm-http (~> 0.1, >= 0.1.1)
       webrobots (~> 0.0, >= 0.0.9)
-    method_source (0.8)
+    method_source (0.8.1)
     mime-types (1.19)
     net-http-digest_auth (1.2.1)
     net-http-persistent (2.8)
     nokogiri (1.5.5)
     ntlm-http (0.1.1)
-    pry (0.9.10)
+    pry (0.9.11.4)
       coderay (~> 1.0.5)
       method_source (~> 0.8)
-      slop (~> 3.3.1)
+      slop (~> 3.4)
+    pry-debugger (0.2.1)
+      debugger (~> 1.2.0)
+      pry (~> 0.9.10)
     rainbow (1.1.4)
     rake (0.9.2.2)
     rb-fchange (0.0.5)
@@ -75,7 +86,7 @@ GEM
     rspec-expectations (2.7.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.7.0)
-    slop (3.3.3)
+    slop (3.4.3)
     terminal-notifier-guard (1.5.3)
     thor (0.16.0)
     unf (0.0.5)
@@ -96,7 +107,7 @@ DEPENDENCIES
   guard-rspec
   jeweler (~> 1.6.4)
   mechanize
-  pry
+  pry-debugger
   rainbow
   rcov
   rr

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Ray Grasso
+Copyright (c) 2013 Ray Grasso
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,20 +1,23 @@
 # Klipbook
 
-Klipbook collates highlights and notes that you've created on your Kindle into a nice html file.
+Klipbook takes the highlights and notes that you've created on your Kindle and
+outputs them into nice html or JSON.
 
-## An example of a clippings file generated by Klipbook
+## An example of a html clippings file generated by Klipbook
 
-<img src="https://github.com/grassdog/klipbook/raw/master/example.png" alt="Example of a clippings file" />
+<img src="https://github.com/grassdog/klipbook/raw/master/example.png" alt="Example
+of a clippings file" />
 
 ## What sources does it support?
 
 Klipbook can take your highlights from a clippings file off a physical Kindle device
-or from the [Kindle highlights site](https://kindle.amazon.com/your_highlights) itself.
+or from the [Kindle highlights site](https://kindle.amazon.com/your_highlights)
+itself.
 
 ## When should I use the file and when should I use the site?
 
 If your books are purchased from Amazon directly then use the site. The site is the
-canonical source and will contain all of your notes and highlights from across all of 
+canonical source and will contain all of your notes and highlights from across all of
 your Kindle devices and applications. Currently the Amazon highlights site only shows
 clippings for books you've purchased on Amazon.
 
@@ -24,36 +27,43 @@ device only keeps clippings that you made directly on it.
 
 ## How does it work?
 
-Klipbook supports two main commands: `collate` and `list`.
+Klipbook supports three commands: `list`, `pprint`, and `collate`.
 
-### Collate
+### Pretty print
 
-`collate` pulls together the clippings from your latest annotated book and combines them
-into a simple html file.
+`pprint` retrieves the clippings from your latest annotated books and writes them
+out into a pretty html file for each book.
 
 #### From a file
 
-Copy your clippings file (called "My Clippings.txt" on a 3rd generation Kindle) from your Kindle device to your local drive via USB.
+Copy your clippings file (called "My Clippings.txt" on a 3rd generation Kindle) from
+your Kindle device to your local drive via USB.
 
 Then write out a list of your clippings via:
 
-    $ klipbook collate "file:My Clippings.txt"
+```sh
+$ klipbook pprint "file:My Clippings.txt"
+```
 
-This command will write the collected clippings for the latest annotated book to a file in the current
-directory. You can override the output directory with the `--output-dir` switch.
+This command will write the collected clippings for the latest annotated book to a
+file in the current directory. You can override the output directory with the
+`--output-dir` switch.
 
-You can also specify a maximum count of books you'd like collated with the `--num-books` switch.
+You can also specify a maximum count of books you'd like collated with the
+`--num-books` switch.
 
-Klipbook will not overwrite an exiting file by default. You can change this with
-the `--force` flag.
+Klipbook will not overwrite an exiting file by default. You can change this with the
+`--force` flag.
 
 #### From the site
 
 Specify your Amazon username and password to klipbook and it will scrape the site and
 output a clippings file.
 
-    $ klipbook collate site:my-username@blah.com:my-password
-    
+```sh
+$ klipbook pprint site:my-username@blah.com:my-password
+```
+
 The same flags above apply.
 
 Note that the scraping requires a network connection (obviously) and can take a while
@@ -61,40 +71,61 @@ so please be patient.
 
 ### Set up defaults
 
-If you don't feel like having your Amazon credentials in your shell history you can set your
-default source in the klipbook rc file: `~/.klipbookrc`.
+If you don't feel like having your Amazon credentials in your shell history you can
+set your default source in the klipbook rc file: `~/.klipbookrc`.
 
 This is simply a YAML file and you can specify default values for the source and the
 output directory, e.g.
 
-    $ cat ~/.klipbookrc
-    source: site:my-username@blah.com:my-password
-    output: my/default/output/directory
+```sh
+$ cat ~/.klipbookrc
+
+:source: site:my-username@blah.com:my-password
+:output: /path/to/my/default/output/directory
+```
 
 Command line options override the defaults stored in the rc file.
 
 ### List
 
-The list command lists the books avaiable in the specified source.
+The `list` command lists the books available in the specified source.
 
-    $ klipbook list file:"My Clippings.txt"
+```sh
+$ klipbook list file:"My Clippings.txt"
 
-    Book list:
-    [1] The Big Sleep by Raymond Chandler
-    [2] How to jump out of a plane without a parachute and survive by Rip Rockjaw
+Book list:
+[1] The Big Sleep by Raymond Chandler
+[2] How to jump out of a plane without a parachute and survive by Rip Rockjaw
+```
 
 By default it will only list the latest book. This can be overrided with the
 `--num-books` switch.
 
+### Collate
+
+`collate` pulls together the clippings from your latest annotated books and combines
+them into a single JSON file.
+
+```sh
+$ klipbook collate -c books.json "file:My Clippings.txt"
+```
+
+You can rerun collate on an existing JSON file to add new books. By default existing
+books in the JSON file will not be overwritten. This can be changed with the `force`
+flag.
+
 ## Installation
 
 Klipbook is a Ruby gem. To install simply run:
 
-    gem install klipbook
+```sh
+$ gem install klipbook
+```
 
 ## Supported Devices
 
-Klipbook has been tested on clippings files from 3rd generation Kindles and the Kindle Touch.
+Klipbook has been tested on clippings files from 3rd generation Kindles and the
+Kindle Touch.
 
 ## Tested platforms
 
@@ -102,9 +133,10 @@ Klipbook has been tested on Mac OSX Mountain Lion using MRI 1.9.3.
 
 ## Contributing to Klipbook
 
-Fork the project on [Github](https://github.com/grassdog/klipbook), add tests for your changes, and submit a well described pull request. 
+Fork the project on [Github](https://github.com/grassdog/klipbook), add tests for
+your changes, and submit a well described pull request. 
 
 ## Copyright
 
-Copyright (c) 2012 Ray Grasso. See LICENSE.txt for further details.
+Copyright (c) 2013 Ray Grasso. See LICENSE.txt for further details.
 

data/bin/klipbook

@@ -25,32 +25,52 @@ arg_name 'count'
 default_value 1
 flag [:n, :'num-books']
 
-desc 'Collate your clippings into a html file for each book'
+desc 'Collate your clippings into a single json file'
 arg_name 'source'
-long_desc "Clippings are fetched from the specified source before being collated into html " +
-          "files and written into the current directory.\n\n" + SOURCE_HELP
+long_desc "Clippings are fetched from the specified source, collated, and written into a single json file.\n\n" +
+          SOURCE_HELP
 command :collate do |c|
 
-  c.desc 'Override the directory path where collated files are written'
+  c.desc 'Specify the name of the json file to be written to.'
+  c.arg_name 'File-name'
+  c.flag [:c, :'output-file']
+
+  c.desc 'Force overwrite of any existing book entries within the output file'
+  c.switch [:f, :force]
+
+  c.action do |globals,options,args|
+    book_file_path = output_file(options)
+    books = fetch_books(args, globals)
+    Klipbook::Commands::Collate.new(books, book_file(book_file_path)).call(book_file_path, options[:f])
+  end
+end
+
+desc 'Pretty print your clippings into a html file for each book'
+arg_name 'source'
+long_desc "Clippings are fetched from the specified source before being written to html " +
+          "files in the output directory.\n\n" + SOURCE_HELP
+command :pprint do |c|
+
+  c.desc 'Override the directory path where html files are written'
   c.arg_name 'Directory'
   c.flag [:o, :'output-dir']
 
-  c.desc 'Force overwrite of any existing collated files'
+  c.desc 'Force overwrite of any existing files'
   c.switch [:f, :force]
 
   c.action do |globals,options,args|
     books = fetch_books(args, globals)
-    Klipbook::Collator.new(books).collate_books(output_dir(options), options[:f])
+    Klipbook::Commands::PrettyPrint.new(books).call(output_dir(options), options[:f])
   end
 end
 
 desc 'List available books'
 arg_name 'source'
-long_desc "Clippings are fetched from the specified source before being listed to screen.\n\n" + SOURCE_HELP
+long_desc "List the books from the specified source to screen.\n\n" + SOURCE_HELP
 command :list do |c|
   c.action do |globals,options,args|
     books = fetch_books(args, globals)
-    Klipbook::Printer.new(books).print
+    Klipbook::Commands::ListBooks.new(books).call
   end
 end
 
@@ -75,17 +95,33 @@ on_error do |exception|
   true
 end
 
+def book_file(file_path)
+  raw_json = if File.exist?(file_path)
+               File.open(file_path, 'r') do |f|
+                 f.read
+               end
+             else
+               ''
+             end
+
+  Klipbook::Collate::BookFile.from_json(raw_json)
+end
+
 def source_spec(args)
   @source_spec ||= (args[0] || Klipbook::Config.new.read[:source])
 end
 
 def fetch_books(args, globals)
-  Klipbook::Fetcher.new(source_spec(args), globals[:n].to_i).fetch_books
+  Klipbook::Sources::BookSource.new(source_spec(args), globals[:n].to_i).books
 end
 
 def output_dir(options)
   @output_dir ||= (options[:o] || Klipbook::Config.new.read[:output] || Dir.pwd)
 end
 
+def output_file(options)
+  @output_file ||= (options[:c] || Klipbook::Config.new.read[:output_file] || File.join(Dir.pwd, 'books.json'))
+end
+
 exit run(ARGV)
 

data/features/collate.feature

@@ -1,51 +1,11 @@
-Feature: klipbook collates the clippings from a clippings file
+Feature: klipbook collates clippings from a clippings file
   As an avid reader and note taker
-  I want to see a pretty html collation for books that I've read
-  So that I can refer to a nice summary of passages I enjoyed in the book
+  I want to see a single JSON file collating the clippings of the books that I've read
+  So that I can export them to other tools for my enjoyment
 
   Scenario: File with clippings for a book
-    Given a directory named "output"
-    And a file that contains clippings for 3 books called "input.txt"
-    When I collate clippings for "3" books from the file "input.txt" to the output directory "output"
-    Then I should find a file in the folder "output" named "Lean Software Development: An Agile Toolkit by Mary Poppendieck and Tom Poppendieck.html" that contains "13" clippings
-    Then I should find a file in the folder "output" named "Instapaper: Long Reads by Instapaper: Long Reads.html" that contains "4" clippings
-    Then I should find a file in the folder "output" named "Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html" that contains "3" clippings
-    And the exit status should be 0
-
-  Scenario: Attempting to write to an existing file
-    Given a directory named "output"
-    And a file in "output" named "Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
-    And a file that contains clippings for 3 books called "input.txt"
-    When I collate clippings for "3" books from the file "input.txt" to the output directory "output"
-    Then the output should contain "Skipping Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
-    And the exit status should be 0
-
-  Scenario: Force overwrite of an existing file
-    Given a directory named "output"
-    And a file in "output" named "Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
-    And a file that contains clippings for 3 books called "input.txt"
-    When I collate clippings for "3" books from the file "input.txt" to the output directory "output" forcefully
-    Then the output should contain "Writing Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
-    And the exit status should be 0
-
-  Scenario: Attempt to write with a bad number of books
-    Given a directory named "output"
-    And a file that contains clippings for 3 books called "input.txt"
-    When I collate clippings for "notanumber" books from the file "input.txt" to the output directory "output"
-    Then the output should contain "error: Specify a number of books greater than 0"
-    And the exit status should be 1
-
-  Scenario: Attempt to write to a non-existent directory
-    Given there is not a directory named "output"
-    And a file that contains clippings for 3 books called "input.txt"
-    When I collate clippings for "3" books from the file "input.txt" to the output directory "output"
-    Then the output should contain "error: Output directory doesn't exist: output"
-    And the exit status should be 1
-
-  @slow
-  Scenario: Site with clippings for a book
-    Given a directory named "output"
-    When I collate clippings for "1" books from the kindle site to the output directory "output"
-    Then I should find "1" collated files containing clippings in the directory "output"
+    Given a file that contains clippings for 3 books called "input.txt"
+    When I collate clippings for "3" books from the file "input.txt" to the output file "books.json"
+    Then I should find a file called "books.json" that contains "Lean Software Development: An Agile Toolkit"
     And the exit status should be 0
 

data/features/pretty_print.feature

@@ -0,0 +1,51 @@
+Feature: klipbook pretty prints the clippings from a clippings file
+  As an avid reader and note taker
+  I want to see a pretty html summary for each of the books that I've read
+  So that I can refer to a nice summary of passages I enjoyed in the book
+
+  Scenario: File with clippings for a book
+    Given a directory named "output"
+    And a file that contains clippings for 3 books called "input.txt"
+    When I pretty print clippings for "3" books from the file "input.txt" to the output directory "output"
+    Then I should find a file in the folder "output" named "Lean Software Development: An Agile Toolkit by Mary Poppendieck and Tom Poppendieck.html" that contains "13" clippings
+    Then I should find a file in the folder "output" named "Instapaper: Long Reads by Instapaper: Long Reads.html" that contains "4" clippings
+    Then I should find a file in the folder "output" named "Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html" that contains "3" clippings
+    And the exit status should be 0
+
+  Scenario: Attempting to write to an existing file
+    Given a directory named "output"
+    And a file in "output" named "Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
+    And a file that contains clippings for 3 books called "input.txt"
+    When I pretty print clippings for "3" books from the file "input.txt" to the output directory "output"
+    Then the output should contain "Skipping Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
+    And the exit status should be 0
+
+  Scenario: Force overwrite of an existing file
+    Given a directory named "output"
+    And a file in "output" named "Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
+    And a file that contains clippings for 3 books called "input.txt"
+    When I pretty print clippings for "3" books from the file "input.txt" to the output directory "output" forcefully
+    Then the output should contain "Writing Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.html"
+    And the exit status should be 0
+
+  Scenario: Attempt to write with a bad number of books
+    Given a directory named "output"
+    And a file that contains clippings for 3 books called "input.txt"
+    When I pretty print clippings for "notanumber" books from the file "input.txt" to the output directory "output"
+    Then the output should contain "error: Specify a number of books greater than 0"
+    And the exit status should be 1
+
+  Scenario: Attempt to write to a non-existent directory
+    Given there is not a directory named "output"
+    And a file that contains clippings for 3 books called "input.txt"
+    When I pretty print clippings for "3" books from the file "input.txt" to the output directory "output"
+    Then the output should contain "error: Output directory doesn't exist: output"
+    And the exit status should be 1
+
+  @slow
+  Scenario: Site with clippings for a book
+    Given a directory named "output"
+    When I pretty print clippings for "1" books from the kindle site to the output directory "output"
+    Then I should find "1" pretty formated files containing clippings in the directory "output"
+    And the exit status should be 0
+

data/features/step_definitions/collate_steps.rb

@@ -1,61 +1,17 @@
-CLIPPING_FILE = File.join(File.dirname(__FILE__), '../fixtures/clippings-for-three-books.txt')
 
-Given /^a file in "([^"]*)" named "([^"]*)"$/ do |output_dir, file_name|
-  in_current_dir { FileUtils.touch(File.join(output_dir, file_name)) }
+When /^I collate clippings for "([^"]*)" books from the file "([^"]*)" to the output file "([^"]*)"$/ do |book_count, input_file, output_file|
+  run_collate(book_count, output_file, input_file)
 end
 
-Given /^there is not a directory named "([^"]*)"$/ do |directory_name|
+Then /^I should find a file called "([^"]*)" that contains "([^"]*)"$/ do |output_file, expected_text|
   in_current_dir do
-    FileUtils.rm_f(directory_name)
-  end
-end
-
-Given /^a file that contains clippings for 3 books called "([^"]*)"$/ do |file_name|
-  in_current_dir { FileUtils.cp(CLIPPING_FILE, file_name) }
-end
-
-When /^I collate clippings for "([^"]*)" books from the file "([^"]*)" to the output directory "([^"]*)"$/ do |book_count, input_file, output_dir|
-  run_collate_file(book_count, output_dir, input_file, false)
-end
-
-When /^I collate clippings for "([^"]*)" books from the file "([^"]*)" to the output directory "([^"]*)" forcefully$/ do |book_count, input_file, output_dir|
-  run_collate_file(book_count, output_dir, input_file, true)
-end
-
-Then /^I should find a file in the folder "([^"]*)" named "([^"]*)" that contains "([^"]*)" clippings$/ do |output_folder, file_name, clipping_count|
-  in_current_dir do
-    file_path = File.join(output_folder, file_name)
-    File.exists?(file_path).should be_true
-    File.open(file_path, 'r') do |f|
-      f.read.should match(/<footer>\s+#{clipping_count} clippings &bull;/m)
+    File.exists?(output_file).should be_true
+    File.open(output_file, 'r') do |f|
+      f.read.should match(/#{expected_text}/m)
     end
   end
 end
 
-# FIXME This step currently assumes you have site: set up in your klipbookrc
-When /^I collate clippings for "([^"]*)" books from the kindle site to the output directory "([^"]*)"$/ do |book_count, output_dir|
-  run_simple(unescape("klipbook -n #{book_count} collate -o #{output_dir}"), false)
+def run_collate(book_count, output_file, input_file)
+  run_simple(unescape("klipbook -n #{book_count} collate -c #{output_file} file:#{input_file}"), false)
 end
-
-Then /^I should find "([^"]*)" collated files containing clippings in the directory "([^"]*)"$/ do |file_count, output_dir|
-  in_current_dir do
-    files = Dir['output/*.html']
-    files.should have(file_count.to_i).items
-    files.each do |fname|
-      File.open(fname, 'r') do |f|
-        f.read.should match(/<footer>\s+\d+ clippings &bull;/m)
-      end
-    end
-  end
-end
-
-def run_collate_file(book_count, output, input, force=false)
-  force_str = if force
-    '-f'
-  else
-    ''
-  end
-
-  run_simple(unescape("klipbook -n #{book_count} collate #{force_str} -o #{output} file:#{input}"), false)
-end
-

data/features/step_definitions/pretty_print_steps.rb

@@ -0,0 +1,61 @@
+CLIPPING_FILE = File.join(File.dirname(__FILE__), '../fixtures/clippings-for-three-books.txt')
+
+Given /^a file in "([^"]*)" named "([^"]*)"$/ do |output_dir, file_name|
+  in_current_dir { FileUtils.touch(File.join(output_dir, file_name)) }
+end
+
+Given /^there is not a directory named "([^"]*)"$/ do |directory_name|
+  in_current_dir do
+    FileUtils.rm_f(directory_name)
+  end
+end
+
+Given /^a file that contains clippings for 3 books called "([^"]*)"$/ do |file_name|
+  in_current_dir { FileUtils.cp(CLIPPING_FILE, file_name) }
+end
+
+When /^I pretty print clippings for "([^"]*)" books from the file "([^"]*)" to the output directory "([^"]*)"$/ do |book_count, input_file, output_dir|
+  run_pretty_print_file(book_count, output_dir, input_file, false)
+end
+
+When /^I pretty print clippings for "([^"]*)" books from the file "([^"]*)" to the output directory "([^"]*)" forcefully$/ do |book_count, input_file, output_dir|
+  run_pretty_print_file(book_count, output_dir, input_file, true)
+end
+
+Then /^I should find a file in the folder "([^"]*)" named "([^"]*)" that contains "([^"]*)" clippings$/ do |output_folder, file_name, clipping_count|
+  in_current_dir do
+    file_path = File.join(output_folder, file_name)
+    File.exists?(file_path).should be_true
+    File.open(file_path, 'r') do |f|
+      f.read.should match(/<footer>\s+#{clipping_count} clippings &bull;/m)
+    end
+  end
+end
+
+# FIXME This step currently assumes you have site: set up in your klipbookrc
+When /^I pretty print clippings for "([^"]*)" books from the kindle site to the output directory "([^"]*)"$/ do |book_count, output_dir|
+  run_simple(unescape("klipbook -n #{book_count} pprint -o #{output_dir}"), false)
+end
+
+Then /^I should find "([^"]*)" pretty printed files containing clippings in the directory "([^"]*)"$/ do |file_count, output_dir|
+  in_current_dir do
+    files = Dir['output/*.html']
+    files.should have(file_count.to_i).items
+    files.each do |fname|
+      File.open(fname, 'r') do |f|
+        f.read.should match(/<footer>\s+\d+ clippings &bull;/m)
+      end
+    end
+  end
+end
+
+def run_pretty_print_file(book_count, output, input, force=false)
+  force_str = if force
+    '-f'
+  else
+    ''
+  end
+
+  run_simple(unescape("klipbook -n #{book_count} pprint #{force_str} -o #{output} file:#{input}"), false)
+end
+