drum 0.1.12

data/lib/drum/service/stdio.rb

@@ -0,0 +1,51 @@
+require 'drum/model/playlist'
+require 'drum/model/ref'
+require 'drum/service/service'
+require 'drum/utils/log'
+require 'yaml'
+
+module Drum
+  # A service that reads from stdin and writes to stdout.
+  class StdioService < Service
+    include Log
+
+    def name
+      'stdio'
+    end
+
+    def parse_ref(raw_ref)
+      if raw_ref.is_token
+        location = case raw_ref.text
+        when 'stdout' then :stdout
+        when 'stdin' then :stdin
+        else return nil
+        end
+        Ref.new(self.name, :any, [location])
+      elsif raw_ref.text == '-'
+        Ref.new(self.name, :any, [:stdin, :stdout])
+      else
+        nil
+      end
+    end
+
+    def download(playlist_ref)
+      if playlist_ref.resource_location.include?(:stdin)
+        # TODO: Support multiple, --- delimited playlists?
+        [Playlist.deserialize(YAML.load(STDIN.read))]
+      else
+        []
+      end
+    end
+
+    def upload(playlist_ref, playlists)
+      if playlist_ref.resource_location.include?(:stdout)
+        playlists.each do |playlist|
+          log.all playlist.serialize.to_yaml
+        end
+        nil
+      else
+        raise 'Cannot upload to somewhere other than stdout!'
+      end
+    end
+  end
+end

data/lib/drum/utils/ext.rb

@@ -0,0 +1,88 @@
+module Drum
+  module Try
+    # A lightweight variant of Rails' try that only supports
+    # blocks (the other variants are already handled more
+    # elegantly using &.).
+    #
+    # @yield [value] The block to run if not nil
+    # @yieldparam [Object] value The non-nil value
+    # @return [Object, nil] Either the mapped self or nil
+    def try
+      if self.nil?
+        nil
+      else
+        yield self
+      end
+    end
+  end
+
+  module Casings
+    # Converts a string to kebab-case.
+    #
+    # @return [String] The kebabcased version of the string
+    def kebabcase
+      self.gsub(/([A-Z]+)([A-Z][a-z])/,'\1-\2')
+          .gsub(/([a-z\d])([A-Z])/,'\1-\2')
+          .gsub(/[\s_\/\-_:\.]+/, '-')
+          .downcase
+    end
+
+    # Converts a string to ['array', 'case']
+    #
+    # @return [Array<String>] The arraycased version of the string
+    def arraycase
+      self.kebabcase
+          .split('-')
+    end
+
+    # Converts a string to Start Case.
+    #
+    # @return [String] The startcased version of the string
+    def startcase
+      self.arraycase
+          .map { |s| s.capitalize }
+          .join(' ')
+    end
+
+    # Converts a string to camelCase.
+    #
+    # @return [String] The camelcased version of the string
+    def camelcase
+      self.arraycase
+          .each_with_index
+          .map { |s, i| if i == 0 then s else s.capitalize end }
+          .join
+    end
+
+    # Converts a string to PascalCase.
+    #
+    # @return [String] The pascalcased version of the string
+    def pascalcase
+      self.arraycase
+          .map { |s| s.capitalize }
+          .join
+    end
+  end
+
+  module ToHashById
+    # Initializes a hash from the array grouping by ids as keys
+    # (which are assumed to be unique).
+    #
+    # @return [Hash<Object, Object>] The resulting hash
+    def to_h_by_id
+      self.map { |v| [v.id, v] }.to_h
+    end
+  end
+end
+
+class Object
+  include Drum::Try
+end
+
+class String
+  include Drum::Casings
+end
+
+class Array
+  include Drum::ToHashById
+end

data/lib/drum/utils/log.rb

@@ -0,0 +1,93 @@
+require 'logger'
+
+module Drum
+  # A simple logging facility.
+  #
+  # @!attribute level
+  #   @return [Logger::Level] The minimum level of messages to be logged
+  # @!attribute output
+  #   @return [Proc] A function taking a string for outputting a message
+  class Logger
+    module Level
+      ALL = 100
+      ERROR = 2
+      WARN = 1
+      INFO = 0
+      DEBUG = -1
+      TRACE = -2
+    end
+
+    attr_accessor :level
+    attr_accessor :output
+
+    # Creates a new logger with the given level.
+    #
+    # @param [Logger::Level] level The minimum level of messages to be logged.
+    # @param [Proc] output A function taking a string for outputting a message.
+    def initialize(level: Level::INFO, output: method(:puts))
+      self.level = level
+      self.output = output
+    end
+
+    # Logs a message at the given level.
+    #
+    # @param [Logger::Level] level The level to log the message at.
+    # @param [String] msg The message to log.
+    def log(level, msg)
+      if level >= self.level
+        self.output.(msg)
+      end
+    end
+
+    # Logs a message at the ALL level.
+    #
+    # @param [String] msg The message to log.
+    def all(msg)
+      self.log(Level::ALL, msg)
+    end
+
+    # Logs a message at the ERROR level.
+    #
+    # @param [String] msg The message to log.
+    def error(msg)
+      self.log(Level::ERROR, msg)
+    end
+
+    # Logs a message at the WARN level.
+    #
+    # @param [String] msg The message to log.
+    def warn(msg)
+      self.log(Level::WARN, msg)
+    end
+
+    # Logs a message at the INFO level.
+    #
+    # @param [String] msg The message to log.
+    def info(msg)
+      self.log(Level::INFO, msg)
+    end
+
+    # Logs a message at the DEBUG level.
+    #
+    # @param [String] msg The message to log.
+    def debug(msg)
+      self.log(Level::DEBUG, msg)
+    end
+
+    # Logs a message at the TRACE level.
+    #
+    # @param [String] msg The message to log.
+    def trace(msg)
+      self.log(Level::TRACE, msg)
+    end
+  end
+
+  module Log
+    # Fetches the global, lazily initialized logger.
+    #
+    # @return [Logger] The logger
+    def log
+      @@log ||= Logger.new
+    end
+  end
+end

data/lib/drum/utils/persist.rb

@@ -0,0 +1,50 @@
+require 'yaml'
+
+# A wrapper around a hash that stores values persistently in a YAML.
+#
+# @!attribute value
+#  @return [Hash] The wrapped hash
+class Drum::PersistentHash
+  attr_reader :value
+
+  # Creates a new persistent hash.
+  #
+  # @param [String] file_path The path to the stored YAML file (may be non-existent).
+  # @param [Hash] value The initial default value, if the file doesn't exist yet or is malformed
+  def initialize(file_path, value={})
+    @file_path = file_path
+    begin
+      self.load
+    rescue StandardError => e
+      @value = value
+      self.store
+    end
+  end
+
+  # Loads the hash from the file.
+  def load
+    @value = YAML.load(File.read(@file_path))
+  end
+
+  # Saves the hash to the file.
+  def store
+    File.write(@file_path, @value.to_yaml)
+  end
+
+  # Writes a mapping to the hash and stores it on disk.
+  #
+  # @param [Object] key The key to use.
+  # @param [Object] value The value to map the key to.
+  def []=(key, value)
+    @value[key] = value
+    store
+  end
+
+  # Reads a mapping from the hash.
+  #
+  # @param [Object] key The key to use.
+  # @return [Object] The value the key is mapped to.
+  def [](key)
+    @value[key]
+  end
+end

data/lib/drum/version.rb

@@ -0,0 +1,3 @@
+module Drum
+  VERSION = '0.1.12'
+end

data/lib/drum.rb

@@ -0,0 +1,250 @@
+require 'drum/model/raw_ref'
+require 'drum/service/applemusic'
+require 'drum/service/file'
+require 'drum/service/mock'
+require 'drum/service/service'
+require 'drum/service/spotify'
+require 'drum/service/stdio'
+require 'drum/utils/log'
+require 'drum/version'
+require 'highline'
+require 'progress_bar'
+require 'thor'
+require 'yaml'
+
+module Drum
+  class Error < StandardError; end
+  
+  # The command line interface for drum.
+  class CLI < Thor
+    include Log
+
+    # Sets up the CLI by registering the services.
+    def initialize(*args)
+      super
+
+      @hl = HighLine.new
+
+      # Set up .drum directory
+      @dot_dir = Pathname.new(Dir.home) / '.drum'
+      @dot_dir.mkdir unless @dot_dir.directory?
+
+      @cache_dir = @dot_dir / 'cache'
+      @cache_dir.mkdir unless @cache_dir.directory?
+
+      # Declare services in descending order of parse priority
+      @services = [
+        MockService.new,
+        StdioService.new,
+        AppleMusicService.new(@cache_dir),
+        SpotifyService.new(@cache_dir),
+        # The file service should be last since it may
+        # successfully parse refs that overlap with other
+        # services.
+        FileService.new
+      ].map { |s| [s.name, s] }.to_h
+    end
+
+    def self.exit_on_failure?
+      true
+    end
+
+    no_commands do
+      # Performs a block with the given service, if registered.
+      #
+      # @yield [name, service] The block to run
+      # @yieldparam [String] name The name of the service
+      # @yieldparam [Service] service The service
+      # @param [String] raw_name The name of the service
+      def with_service(raw_name)
+        name = raw_name.downcase
+        service = @services[name]
+        if service.nil?
+          raise "Sorry, #{name} is not a valid service! Try one of these: #{@services.keys}"
+        end
+        yield(name, service)
+      end
+
+      # Parses a ref using the registered services.
+      #
+      # @param [String] raw The raw ref to parse
+      # @return [optional, Ref] The ref, if parsed successfully with any of the services
+      def parse_ref(raw)
+        raw_ref = RawRef.parse(raw)
+        @services.each_value do |service|
+          ref = service.parse_ref(raw_ref)
+          unless ref.nil?
+            return ref
+          end
+        end
+        return nil
+      end
+
+      # Prompts the user for confirmation.
+      #
+      # @param [String] prompt The message to be displayed
+      def confirm(prompt)
+        answer = @hl.ask "#{prompt} [y/n]"
+        unless answer == 'y'
+          log.info 'Okay, exiting.'
+          exit
+        end
+      end
+    end
+
+    desc 'show [REF]', 'Preview a playlist in a simplified format'
+
+    # Previews a playlist in a simplified format.
+    #
+    # @param [String] raw_ref The (raw) playlist ref.
+    def show(raw_ref)
+      ref = self.parse_ref(raw_ref)
+
+      if ref.nil?
+        raise "Could not parse ref: #{raw_ref}"
+      end
+
+      self.with_service(ref.service_name) do |name, service|
+        playlists = service.download(ref)
+        
+        playlists.each do |playlist|
+          log.all({
+            'name' => playlist.name,
+            'description' => playlist&.description,
+            'tracks' => playlist.tracks.each_with_index.map do |track, i|
+              artists = (track.artist_ids&.filter_map { |id| playlist.artists[id]&.name } || []).join(', ')
+              "#{i + 1}. #{artists} - #{track.name}"
+            end
+          }.compact.to_yaml)
+        end
+      end
+    end
+    
+    desc 'cp [SOURCE] [DEST]', 'Copy a playlist from the source to the given destination'
+
+    method_option :group_by_author,
+      type: :boolean,
+      default: false,
+      desc: "Prepend the author name to each playlist's path"
+
+    method_option :recase_paths,
+      type: :string,
+      enum: ['kebabcase', 'startcase', 'camelcase', 'pascalcase'],
+      default: false,
+      desc: "Convert each playlist's path segments to a specific case"
+
+    method_option :note_date,
+      type: :boolean,
+      default: false,
+      desc: 'Add a small note with the upload date to each description.'
+
+    # Copies a playlist from the source to the given destination.
+    #
+    # @param [String] raw_src_ref The source playlist ref.
+    # @param [String] raw_dest_ref The destination playlist ref.
+    # @return [void]
+    def cp(raw_src_ref, raw_dest_ref)
+      src_ref = self.parse_ref(raw_src_ref)
+      dest_ref = self.parse_ref(raw_dest_ref)
+
+      if src_ref.nil?
+        raise "Could not parse src ref: #{raw_src_ref}"
+      end
+      if dest_ref.nil?
+        raise "Could not parse dest ref: #{raw_dest_ref}"
+      end
+
+      self.with_service(src_ref.service_name) do |src_name, src_service|
+        self.with_service(dest_ref.service_name) do |dest_name, dest_service|
+          log.info "Copying from #{src_name} to #{dest_name}..."
+
+          # TODO: Should we handle merging at all or just copy (as currently done)?
+
+          playlists = src_service.download(src_ref).lazy
+
+          unless playlists.size.nil?
+            bar = ProgressBar.new(playlists.size)
+
+            # Redirect log output so the bar stays at the bottom
+            log.output = bar.method(:puts)
+          end
+
+          # Apply transformations to the downloaded playlists.
+          # Note that we use 'map' despite mutating the playlists
+          # in-place to preserve laziness in the iteration.
+
+          playlists = playlists.map do |playlist|
+            bar&.increment!
+
+            if options[:group_by_author]
+              author_name = playlist.author_id.try { |id| playlist.users[id] }&.display_name || 'Other'
+              playlist.path.unshift(author_name)
+            end
+
+            if options[:recase_paths]
+              casing = options[:recase_paths]
+              playlist.path.map! do |n|
+                case casing
+                when 'kebabcase' then n.kebabcase
+                when 'startcase' then n.startcase
+                when 'camelcase' then n.camelcase
+                when 'pascalcase' then n.pascalcase
+                else raise "Casing '#{casing}' is not implemented (yet)!"
+                end
+              end
+            end
+
+            if options[:note_date]
+              unless playlist.description.end_with?("\n") || playlist.description.empty?
+                playlist.description += "\n"
+              end
+              playlist.description += Time.now.strftime("Pushed with Drum on %Y-%m-%d")
+            end
+
+            playlist
+          end
+
+          dest_service.upload(dest_ref, playlists)
+        end
+      end
+    end
+
+    desc 'rm [REF]', 'Remove a playlist from the corresponding service'
+
+    # Removes a playlist from the corresponding service.
+    #
+    # @param [String] raw_ref The playlist ref.
+    # @return [void]
+    def rm(raw_ref)
+      ref = self.parse_ref(raw_ref)
+
+      if ref.nil?
+        raise "Could not parse ref: #{raw_ref}"
+      end
+
+      self.with_service(ref.service_name) do |name, service|
+        log.info "Removing from #{name}..."
+        service.remove(ref)
+      end
+    end
+
+    desc 'services', 'List available services'
+
+    # Lists available services.
+    #
+    # @return [void]
+    def services
+      log.info @services.each_key.to_a.join("\n")
+    end
+
+    map %w[--version -v] => :__print_version
+    desc '--version, -v', 'Print the version', hide: true
+
+    # Prints the version.
+    #
+    # @return [void]
+    def __print_version
+      log.all VERSION
+    end
+  end
+end

data/userdoc/playlist-format.md

@@ -0,0 +1,96 @@
+# Drum Playlist Format
+
+Drum uses a YAML-based format to represent playlists. This makes it easy to back them up, check them into version control and use them in other tools, among others. There are two basic flavors of playlists, though both share the same rough structure:
+
+* **Regular playlists**, which are a simple list of songs
+* **Smart playlists**, which additionally include a list of filtering rules
+
+A playlist is 'smart' if and only if it contains `filter`s.
+
+> Note that by default, Drum will only allow copying smart playlists to destinations that support smart playlists (currently just local files). With the `-x`/`--execute` flag, however, the smart playlist will be converted into a regular playlist during the copying, thereby allowing all destinations that support regular playlists.
+
+<!-- TODO: Actually implement smart playlists -->
+
+## Specification
+
+### Playlist
+
+The top-level object in a playlist file.
+
+```yaml
+id: string
+name: string
+description: string?
+author_id: string? (references User.id)
+path: string[]?
+users: User[]?
+artists: Artist[]?
+albums: Album[]?
+tracks: Track[]?
+spotify:
+  id: string
+  public: boolean?
+  collaborative: boolean?
+  image_url: string?
+applemusic:
+  library_id: string?
+  global_id: string?
+  public: boolean?
+  editable: boolean?
+  image_url: string?
+```
+
+### User
+
+```yaml
+id: string
+display_name: string?
+spotify:
+  id: string
+  image_url: string?
+```
+
+### Artist
+
+```yaml
+id: string
+name: string
+spotify:
+  id: string
+  image_url: string?
+```
+
+### Album
+
+```yaml
+id: string
+name: string
+artist_ids: string[] (references Artist.id)
+spotify:
+  id: string
+  image_url: string?
+applemusic:
+  image_url: string?
+```
+
+### Track
+
+```yaml
+name: string
+artist_ids: string[] (references Artist.id)
+composer_ids: string[]? (references Artist.id)
+genres: string[]?
+album_id: string? (references Album.id)
+duration_ms: number?
+explicit: boolean?
+released_at: string? (ISO8601 date)
+added_at: string? (ISO8601 date)
+added_by: string? (references User.id)
+isrc: string?
+spotify:
+  id: string
+applemusic:
+  library_id: string?
+  catalog_id: string?
+  preview_url: string?
+```