sync_songs 0.0.1

data/.gitignore

@@ -0,0 +1,8 @@
+# Ignore editor backups
+*~
+.bundle
+*.gem
+.bundle
+test_lastfm_set.rb
+test_grooveshark_set.rb
+test_csv_set*.csv

data/CONTRIBUTING.org

@@ -0,0 +1,14 @@
+# -*- mode:org; indent-tabs-mode:nil; tab-width:2 -*-
+
+* Contributing
+
+** Issues
+
+If you have a question, found a bug or want to make a suggestion please go ahead and [[https://github.com/Sleft/sync_songs/issues/new][post it as an issue]] but make sure it is not already reported. Please be as clear as possible and provide details. If the issue has to do with the program failing please include output from the program with the =--debug= and the =-v= options activated.
+
+** Development
+
+If you want to contribute please:
+
+- Follow the guidelines in development.org.
+- Fork the project and commit changes to an aptly named topic branch which you then make a pull request for.

data/Gemfile

@@ -0,0 +1,7 @@
+# -*- coding: utf-8; mode: ruby -*-
+
+source 'https://rubygems.org'
+
+gemspec
+
+ruby '1.9.3'

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    sync_songs (0.0.0)
+      grooveshark (>= 0.2.7)
+      highline (>= 1.6.16)
+      lastfm (>= 1.17.0)
+      launchy (>= 2.2.0)
+      thor (>= 0.18.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (3.2.13)
+      i18n (= 0.6.1)
+      multi_json (~> 1.0)
+    addressable (2.3.3)
+    grooveshark (0.2.7)
+      json (>= 1.4.6)
+      rest-client (>= 1.5.1)
+      uuid (~> 2.0)
+    highline (1.6.16)
+    httparty (0.10.2)
+      multi_json (~> 1.0)
+      multi_xml (>= 0.5.2)
+    i18n (0.6.1)
+    json (1.7.7)
+    lastfm (1.17.0)
+      activesupport (>= 3.0.3)
+      httparty
+      xml-simple
+    launchy (2.2.0)
+      addressable (~> 2.3)
+    macaddr (1.6.1)
+      systemu (~> 2.5.0)
+    mime-types (1.21)
+    multi_json (1.7.2)
+    multi_xml (0.5.3)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    systemu (2.5.2)
+    thor (0.18.1)
+    uuid (2.3.7)
+      macaddr (~> 1.0)
+    xml-simple (1.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  sync_songs!

data/LICENSE.org

@@ -0,0 +1,2 @@
+sync_songs is copyrighted free software and licensed under the same
+terms as Ruby, see http://www.ruby-lang.org/en/about/license.txt

data/README.org

@@ -0,0 +1,117 @@
+# -*- mode:org; indent-tabs-mode:nil; tab-width:2 -*-
+
+* sync_songs
+
+With sync_songs you can sync sets of songs between services. If you have one set of song at one service and another song set at another service you can use sync_songs to merge the song sets. sync_songs can also be used to backup song sets by the ability to spread them across several services. Additionaly sync_songs can be used to diff song sets.
+
+Currently sync_songs supports the following services:
+- csv (on the form =name, artist, album, duration, id= where only the first two fields are required)
+- Grooveshark
+- Last.fm
+
+sync_songs can be used as standalone but also as a library.
+
+** Installation
+
+To use sync_songs one has to have [[http://www.ruby-lang.org][Ruby]] installed. The easiest way to install Ruby is to use a package management system. If you are on a Debian-based distribution you can issue the following terminal command to install Ruby:
+#+BEGIN_EXAMPLE
+sudo apt-get install ruby1.9.1
+#+END_EXAMPLE
+
+The following describes three ways of obtaining and installing. The first way is recommended for users and the second way is recommended for developers.
+
+*** Gem
+
+This is the best method to install for most purposes. It requires RubyGems which on Debian-based distributions can be installed via the following command:
+#+BEGIN_EXAMPLE
+sudo apt-get install rubygems1.9.1
+#+END_EXAMPLE
+
+Then you can install sync_songs and its dependencies via the following command:
+#+BEGIN_EXAMPLE
+sudo gem install sync_songs
+#+END_EXAMPLE
+
+*** Git
+
+This method is good if you want to help develop sync_songs. It requires Git which on Debian-based distributions can be installed via the following command:
+#+BEGIN_EXAMPLE
+sudo apt-get install git
+#+END_EXAMPLE
+
+To get the dependencies for sync_songs one can use bundler which can be installed via RubyGems (see above for installation instructions) in the following way:
+#+BEGIN_EXAMPLE
+sudo gem install bundler
+#+END_EXAMPLE
+
+To install sync_songs =cd= to an empty directory and do
+#+BEGIN_EXAMPLE
+git clone https://github.com/Sleft/sync_songs.git .
+#+END_EXAMPLE
+to clone the git repository into that directory. You can use the same command when you want to update it. To install the dependencies issue the following the same directory:
+#+BEGIN_EXAMPLE
+bundle
+#+END_EXAMPLE
+
+*** Archive
+
+This method is not recommended but good if you for some reason cannot use RubyGems or Git. [[https://github.com/Sleft/sync_songs/archive/master.zip][Download]] an archive and extract to the directory you want to install in. Install the dependencies listed in the [[https://github.com/Sleft/sync_songs/blob/master/sync_songs.gemspec][gemspec]].
+
+** Usage
+
+If you want to use sync_songs simply to sync songs between different services you probably want to use it as standalone.
+
+*** Standalone
+
+Issue the following command to learn about how to use sync_songs:
+#+BEGIN_EXAMPLE
+sync_songs help
+#+END_EXAMPLE
+
+The most common way of using sync_songs is probably to sync between two services by issuing a command of the following form:
+#+BEGIN_EXAMPLE
+sync_songs sync --color -vs user1:service1:favorites user2:service2:favorites
+#+END_EXAMPLE
+The =--color= option is recommended as it contributes to legibility. The =-v= option is recommended as it explains what is being done. Note that fetching song data from services may take some time due to limitations of bandwidth and due to limitations of particular services.
+
+The above example does not work as it uses placeholder services. For a list of supported services one can issue
+#+BEGIN_EXAMPLE
+sync_songs supp
+#+END_EXAMPLE
+If one has a user named mary at Grooveshark and a user named smith at Last.fm one can use the following to sync between them:
+#+BEGIN_EXAMPLE
+sync_songs sync --color -vs mary:grooveshark:favorites smith:lastfm:loved
+#+END_EXAMPLE
+
+To sync between more than two services just add additional services as arguments to the =-s= option. For example, to also sync to a csv file one can add it as an argument:
+#+BEGIN_EXAMPLE
+sync_songs sync --color -vs user1:service1:favorites user2:service2:favorites file_path:csv:library
+#+END_EXAMPLE
+Note that syncing to a csv is a way of backing up songs from services.
+
+To diff songs one can proceed as above but by replacing the =sync= command with =diff=, e.g.
+#+BEGIN_EXAMPLE
+sync_songs diff --color -vs user1:service1:favorites user2:service2:favorites
+#+END_EXAMPLE
+
+*** Library
+
+If you want to integrate sync_songs in a project add the following line to the project's gemspec:
+#+BEGIN_EXAMPLE
+gem.add_runtime_dependency 'sync_songs'
+#+END_EXAMPLE
+Alternatively add the following line to your Gemfile:
+#+BEGIN_EXAMPLE
+gem 'sync_songs'
+#+END_EXAMPLE
+Now you should be able to =require sync_songs=.
+
+Note that you can use bundler to get dependencies for sync_songs, see installation via Git above.
+
+* License
+
+See LICENSE.org.
+
+* Contributing and development
+
+See CONTRIBUTING.org.

data/Rakefile

@@ -0,0 +1,19 @@
+# -*- coding: utf-8; mode: ruby -*-
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/unit/test*.rb',
+                          'test/unit/services/test*.rb']
+end
+
+desc 'Run tests'
+task default: :test
+
+# task test: :rubocop
+
+task :style do
+  sh 'rubocop'
+end

data/bin/sync_songs

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8; mode: ruby -*-
+
+require 'thor'
+require_relative '../lib/sync_songs.rb'
+
+# Public: Classes for syncing sets of songs.
+module SyncSongs
+  class Cli < Thor
+    class_option :verbose, type: :boolean, aliases: '-v',
+    desc: 'Explain what is being done'
+    class_option :debug, type: :boolean, desc: 'Debug mode'
+    class_option :color, type: :boolean, desc: 'Color mode'
+    services_option = [:services, {type: :array, required: true,
+                         banner: Controller::INPUT_FORM,
+                         desc: 'At least two users or file paths '\
+                         'each paired with a service and a type, '\
+                         'e.g. -s user1:grooveshark:favorites '\
+                         'songs.csv:csv:library',
+                         aliases: '-s'}]
+
+    desc 'sync', 'Sync sets of songs'
+    long_desc 'Syncs sets of songs between the given services.'
+    method_option(*services_option)
+    def sync
+      setupController
+      @controller.sync
+    end
+
+    desc 'diff', 'Diff sets of songs'
+    long_desc 'Diffs sets of songs between the given services.'
+    method_option(*services_option)
+    def diff
+      setupController
+      @controller.diff
+    end
+
+    desc 'supp', 'List supported services'
+    long_desc <<-LONGDESC
+    Prints a list of the supported services.
+     LONGDESC
+    def supp
+      @controller = Controller.new(CLI.new(options[:verbose],
+                                           options[:debug],
+                                           options[:color]),
+                                   nil)
+      @controller.showSupportedServices
+    end
+
+    desc 'version', 'Shows the version number'
+    long_desc 'Shows the version number. Please include the version'\
+    'in bug reports. If there is an error please produce it with the'\
+    'debug option and include the output from it in the bug report.'
+    def version
+      puts "#{$PROGRAM_NAME} #{VERSION}"
+    end
+
+    private
+
+    def setupController
+      @controller = Controller.new(CLI.new(options[:verbose],
+                                           options[:debug],
+                                           options[:color]),
+                                   options[:services])
+    end
+  end
+
+  Cli.start(ARGV)
+end

data/development.org

@@ -0,0 +1,53 @@
+# -*- mode:org; indent-tabs-mode:nil; tab-width:2 -*-
+
+* Development
+
+sync_songs is designed to be used as standalone and also to provide a useful library for syncing sets of songs between services. One goal is for sync_songs to handle any number of services. Another goal is for it to be easy to add support for new services.
+
+** General guidelines
+
+- Document code with [[http://tomdoc.org/][TomDoc]].
+- If possible, include tests for every feature.
+- Follow [[https://github.com/bbatsov/ruby-style-guide][The Ruby Style Guide]] as much as possible. This means that [[https://github.com/bbatsov/rubocop][rubocop]] can be used to check style (get it via =sudo gem install rubocop=).
+
+** Project structure
+
+*** File structure
+
+The directory structure is as follows:
+- ./ :: Main project files, e.g. Rakefile, gem files and readme.
+  - bin :: Scripts meant to be executed by the user are placed here.
+  - lib :: Contains a file that loads the library.
+    - sync_songs :: The main code.
+      - services :: The code relating to particular services.
+  - test ::
+    - unit :: Tests of the =Test::Unit= framework. This directory should have a structure that corresponds to lib/sync_songs. Thus, this directory contains tests for the main code and also test suites.
+      - sample_data :: Sample data for tests of the parent directory.
+      - services :: Tests relating to particular services.
+        - sample_data :: Sample data for tests of the parent directory.
+
+*** Code structure
+
+The code is structured along MVC pattern. In lib/sync_songs there is a controller, controller.rb, which handles the main logic. The controller interacts with the user via a user interface, for example cli.rb -- a command line interface. Entity classes of the program are based on the classes =Song= and =SongSet=.
+
+In .lib/sync_songs/services the classes relating to particular services are found. Each service has a controller which the main controller communicates with. If a particular service needs to interact with the user it should have its own user interface which is called by its controller. Each service has an entity class for getting and setting songs.
+
+** How to add a service
+
+For a service to be meaningful it needs to be possible to get songs from it or set songs to it. Obviously it is best if both getting and setting is possible as it makes possible for sync in both directions. This mean that it needs to be possible to get and/or set songs to the service in question via Ruby.
+
+As described under the heading "Code structure" above each service should have a controller, a user interface (if it needs to interact with the user) and an entity class. When adding a service it is probably best to start by designing the entity class.
+
+The entity class for a particular service, which I will call a service set, should be a subclass of =SongSet= and named ServicenameSet. This provides it with the ability to store objects of the class =Song= via the methods =<<= and =add=. Every service set needs to have at least two methods. It needs to have a constructor that calls the constructor of its super class and does any setup that is necessary for the particular service. It also needs a method for getting or setting songs. The method for getting songs should be named after which kind of songs it gets, e.g. if it gets favorite songs it should be called =favorites= (if there is no given name for the type of song please call the method =library=), and it should get those songs from the service and add them to the =SongSet=. The method for setting songs should be named =addTo= followed by the type of songs it adds, e.g. =addToFavorites= if it adds favorites, and it should take a =SongSet= as a parameter and add those to the given type of songs of the service. When there is a method for setting songs there also needs to be a method for searching songs named =search= which takes a =SongSet= and an optional boolean value defaulting to true for whether to do strict search as arguments. The search method should search for the songs given as argument and return any matches. A service set is not responsible for handling exceptions but any exceptions thrown by any of its methods should be documented in TomDoc style. For an example of a simple service set see lib/sync_songs/services/csv_set.rb.
+
+The controller for a particular service should be a subclass of =ServiceController= and it should be named ServicenameController. The controller is responsible for all communication with the main controller and it should setup the service set via its constructor. It should also have wrappers for the getters, setters and search methods of the service set and if any of them throws an exception it should be handled. For an example of a controller for a service see lib/sync_songs/services/csv_controller.rb.
+
+A user interface for a particular service is only necessary if it needs to interact with the user. The service user interface should be named ServicenameInterfacetype and if possible it should use methods of the main user interface of the same type. Note that the service user interface should be called by the service controller only. For an example of a service user interface see lib/sync_songs/services/csv_cli.rb.
+
+** Adding a user interface
+
+As mentioned sync_songs is designed to have a replaceable user interface. If one wants to make a new user interface one needs to construct a main user interface and a user interface for every service that needs one. If the main controller needs to be changed to support other user interface that is a flaw in the main controller and fixes for such flaws are encouraged.
+
+** Plan
+
+The plan is for sync_songs to work as expected, have as few bugs as possible and support more services. Specific plans are documented in plan.org. Also see [[https://github.com/Sleft/sync_songs/issues][issues]].

data/lib/sync_songs/cli.rb

@@ -0,0 +1,280 @@
+# -*- coding: utf-8 -*-
+
+require 'highline/import'
+
+# Public: Classes for syncing sets of songs.
+module SyncSongs
+  # Public: Command-line interface.
+  class CLI
+    # Public: A character for answering yes to a question.
+    YES_ANSWER = 'y'
+    # Public: A character that the user can input to quit what is
+    # currently happening. Sometimes it means to quit to program
+    # altogether, sometimes it means to merely to quit the current
+    # dialog.
+    QUIT_ANSWER = 'q'
+    # Public: Message asking for yes, no or quit.
+    YN_OPTIONS_MSG = 'Enter y for yes, n for no or q to quit'
+    # Public: Validator for yes, no or quit questions.
+    YN_VALIDATOR = /\A[yn#{QUIT_ANSWER}]/i
+
+    attr_reader :color
+
+    # Public: Creates a command-line interface.
+    #
+    # verbose             - True if interface is verbose (default:
+    #                       nil).
+    # debug               - True if interface is in debug mode
+    #                       (default: nil), this means e.g. that
+    #                       stack traces for exceptions are printed.
+    # color               - True if color formatted output should be
+    #                       used (default: nil).
+    # possible_directions - A hash of possible sync directions
+    #                       between two given services mapped to
+    #                       descriptions of those directions (default:
+    #                       nil).
+    def initialize(verbose = nil, debug = nil, color = nil,
+                   possible_directions = nil)
+      @verbose             = verbose
+      @debug               = debug
+      @possible_directions = possible_directions
+      HighLine::use_color  = color
+
+      directionsMessage if @possible_directions
+
+      HighLine.color_scheme = HighLine::ColorScheme.new do |cs|
+        cs[:em]                = [:bold]
+        cs[:verbose]           = [:blue]
+        cs[:verbose_direction] = [:cyan, :bold]
+        cs[:error]             = [:red, :bold]
+        cs[:even_row]          = [:green]
+        cs[:odd_row]           = [:magenta]
+      end
+
+      @row = true         # To track even and odd rows for colorizing.
+    end
+
+    # Public: Asks for directions to write in and return them.
+    #
+    # directions - A two dimensional array where each element is of
+    #              the form ['service1', '?', 'service2'].
+    #
+    # Returns an two dimensional array where each element is of the
+    #   form ['service1', '</=/>', 'service2'].
+    def askDirections(directions)
+      directions.each do |d|
+        d[1] = askDirection("#{d.join(' ')} ")
+
+        exitOption(d[1])
+
+        if @verbose
+          say("<%= color(%q(#{d.first.join(' ')}), :verbose) %> "\
+              "<%= color(%q(#{d[1]}), :verbose_direction) %> "\
+              "<%= color(%q(#{d.last.join(' ')}), :verbose) %>")
+        end
+      end
+
+      directions
+    end
+
+    # Public: Asks if strict search should be used for the given
+    # service and returns the answer.
+    #
+    # s - A String describing a service
+    #
+    # Returns true if the user answer that strict search should be
+    #   used for the given service.
+    def strict_search(s)
+      input = ask("<%= color(%q(Strict search), :em) %> for #{s}? ") do |q|
+        q.responses[:not_valid] = 'A strict search is recommended '\
+        'as a wide search may generate too many hits. '\
+        "#{YN_OPTIONS_MSG}"
+        q.default = YES_ANSWER
+        q.validate = YN_VALIDATOR
+      end
+
+      exitOption(input)
+
+      input.casecmp(YES_ANSWER) == 0
+    end
+
+    # Public: Asks if interactive mode should be used for the given
+    # service and returns the answer.
+    #
+    # s - A String describing a service
+    #
+    # Returns true if the user answer that interactive mode should be
+    #   used for the given service.
+    def interactive(s)
+      input = ask("<%= color(%q(Interactive mode), :em) %> for #{s}? ") do |q|
+        q.responses[:not_valid] = 'In interactive mode you will for '\
+        'every found song be asked whether to add it. Interactive '\
+        'mode is recommended for everything but services you have '\
+        "direct access to, such as text files. #{YN_OPTIONS_MSG}"
+        q.default = YES_ANSWER
+        q.validate = YN_VALIDATOR
+      end
+
+      exitOption(input)
+
+      input.casecmp(YES_ANSWER) == 0
+    end
+
+    # Public: For every of the given songs, ask whether to add it and
+    # return an array of songs to add.
+    #
+    # service - A String naming a service.
+    # songs   - An Array of songs to ask about.
+    #
+    # Return an Array of songs to add.
+    def askAddSongs(service, songs)
+      songs_to_add = []
+
+      songs.each do |s|
+        add = askAddSong(s, service)
+
+        # Stop asking if the user press quit
+        break if add.casecmp(QUIT_ANSWER) == 0
+
+        songs_to_add << s if add.casecmp(YES_ANSWER) == 0
+      end
+
+      songs_to_add
+    end
+
+    # Public: Shows the given message and exits with the given exit
+    # code.
+    #
+    # msg       - A String naming a failure message.
+    # exit_code - Exit code to use, see
+    #             http://tldp.org/LDP/abs/html/exitcodes.html for
+    #             details (default: 1).
+    # exception - The Exception causing the failure (default: nil).
+    def fail(msg, exit_code = 1, exception = nil)
+      failMessage(msg)
+
+      if @debug && exception
+        p exception
+        puts exception.backtrace
+      end
+
+      exit(exit_code)
+    end
+
+    # Public: Shows the given message.
+    #
+    # msg - A String or an Enumerable naming a message.
+    def message(msg)
+      puts msg
+    end
+
+    # Public: Shows the given message.
+    #
+    # msg - A String or an Enumerable naming a message.
+    def emMessage(msg)
+      styleMessage(msg, :em)
+    end
+
+    # Public: Prints the given message if in verbose mode.
+    #
+    # msg - A String or an an Enumerable of Strings naming a verbose
+    # message.
+    def verboseMessage(msg)
+      styleMessage(msg, :verbose) if @verbose
+    end
+
+    # Public: Shows the given fail message.
+    #
+    # msg - A String or an Enumerable naming a message.
+    def failMessage(msg)
+      styleMessage(msg, :error)
+    end
+
+    # Public: Shows the supported services.
+    def supportedServices
+      msg = []
+
+      Controller.supportedServices.each do |service, type_action|
+        type_msg = []
+        type_action.each do |type, action|
+          type_msg << "#{type} <%= color(%q(#{action}), :even_row) %>"
+        end
+        msg << "<%= color(%q(#{service}), :em) %>: #{type_msg.join(', ')}"
+      end
+
+      say(msg.join("\n"))
+    end
+
+    # Public: Sets the possible directions.
+    #
+    # val - A hash of possible sync directions between two given
+    #       services mapped to descriptions of those directions.
+    def possible_directions=(val)
+      @possible_directions = val
+      directionsMessage
+    end
+
+    private
+
+    # Internal: Prints the given message with the given style.
+    #
+    # msg   - A String or an an Enumerable of Strings naming a
+    #         message.
+    # color - A Symbol representing an ERB style.
+    def styleMessage(msg, style)
+      if @verbose
+        if msg.respond_to? :each
+          msg.each { |m| styleMessage(m, style) }
+        else
+          say("<%= color(%q(#{msg}), '#{style}') %>")
+        end
+      end
+    end
+
+    # Internal: Asks whether to add the given song to the given
+    # service.
+    #
+    # song    - A String naming a song.
+    # service - A String naming a service.
+    def askAddSong(song, service)
+      question = "Add <%= color(%q(#{song} to #{service}), "
+      question << (@row ? ':even_row' : ':odd_row')
+      @row = !@row
+
+      ask("#{question}) %>? ") do |q|
+        q.responses[:not_valid] = YN_OPTIONS_MSG
+        q.default = YES_ANSWER
+        q.validate = YN_VALIDATOR
+      end
+    end
+
+    # Internal: Ask which direction to sync for the given services.
+    #
+    # question - A String naming a question asking for which direction
+    #            to sync in between to services.
+    #
+    # Returns a String naming the direction to sync in.
+    def askDirection(question)
+      ask(question) do |q|
+        q.responses[:not_valid] = @DIRECTIONS_MSG
+        q.default = '='
+        q.validate = lambda { |a| @possible_directions.key?(a.to_sym) || a == QUIT_ANSWER }
+      end
+    end
+
+    # Internal: Exits if input is a character for quitting.
+    #
+    # input - Input String from user.
+    def exitOption(input)
+      exit if input.casecmp(QUIT_ANSWER) == 0
+    end
+
+    # Internal: Create a message describing what sync directions the
+    # user can choose for any two services.
+    def directionsMessage
+      @DIRECTIONS_MSG = @possible_directions.map { |k, v| "<%= color(%q(#{k}), :verbose_direction) %> for #{v}" }
+      @DIRECTIONS_MSG = "Enter #{@DIRECTIONS_MSG.join(", ")}"
+      @DIRECTIONS_MSG << " or <%= color(%q(#{QUIT_ANSWER}), :verbose_direction) %> to quit"
+    end
+  end
+end