rocksky 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506387a27a8e92d1310a65f855110efff853b6079d9dbb65d6a3e1e56932cc18
-  data.tar.gz: 9d190b167472ba41881d547b527e501e446a75d844cefd4ff5b3200cd461cc94
+  metadata.gz: 411359937d7cc586384c4b58c7e32f4824cc4cfb1ee0e3ec3f38c0071b0b3b30
+  data.tar.gz: 97525f3e9c77f00c136a9f349f18747965dba4aa02f4e55bb1fb6587d926fc6f
 SHA512:
-  metadata.gz: 1a82ef8bb90f40689b29067ba2debfe55eb8e099ed0897c3a69b795a3f03e76c49b10ba42d2035377027ea6701b53ac7be2195b2aead08f0a609ebd4e3058e9c
-  data.tar.gz: 78ca04c14127de3ae2b6993a942129ad1d9118679f1c8458807d315744e703932ae3c861fb32349fb615dff4d4086207bc38e19a2361d27a8fa047291576addf
+  metadata.gz: 49ce584a23a45ecab4725b82308b6968468e2e3104267d4e5ca6696241d149ce224872d8eb303b8dd7680c2e4bc97e738feac641760dfb05c7d5330ef527d5e8
+  data.tar.gz: 4cc152d4c19bfaa289a7422426abe6878d2fae69fda3f0063846b3ece0080c979f9d2b4077415f650bd34d4e7b466d13d3bac045c4e5c94a5e5495034253eee8

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.11.0
+
+- Added `Rocksky::Filter`, a fluent RSQL builder (`eq`, `ne`, `gt`, `ge`,
+  `lt`, `le`, `is_in`, `is_out`, `is_null`, `is_not_null`, combined with
+  `#and` / `#or`). Fields are Symbols (`:artist`, `:"track.artist"`); values
+  are quoted/escaped automatically, `*` wildcards stay bare.
+- Added filterable reads: `Rocksky.catalog_songs`, `catalog_artists`,
+  `catalog_albums` (`limit:`, `offset:`, `genre:`, `filter:`) and
+  `Rocksky.scrobble_feed` (`did:`, `following:`, `limit:`, `offset:`,
+  `filter:`). `filter:` takes a `Rocksky::Filter` or a raw RSQL String.
+
 ## 0.10.0
 
 - Remote-player protocol: now-playing records accept optional audio info —

data/README.md

@@ -14,7 +14,7 @@ gem install rocksky
 Or in a Gemfile:
 
 ```ruby
-gem "rocksky", "~> 0.7"
+gem "rocksky", "~> 0.11"
 ```
 
 The gem is pure-Ruby; the native library is fetched from the GitHub release on
@@ -83,6 +83,31 @@ Rocksky.top_artists_interval(limit: 5, interval: :all)
 **Match** — `Rocksky.match_song(title, artist, mb_id: nil, isrc: nil)` resolves a
 bare title + artist into full canonical metadata.
 
+### Filtering
+
+`Rocksky::Filter` builds RSQL expressions for the `filter:` kwarg of
+`catalog_songs`, `catalog_artists`, `catalog_albums` and `scrobble_feed`
+(each also takes `limit:`, `offset:` and — catalogs only — `genre:`). Fields
+are Symbols; dotted selectors on the scrobble feed reach the joined
+track/user/artist (`:"track.artist"`, `:"user.handle"`, …).
+
+```ruby
+filter = Rocksky::Filter.eq(:artist, "Daft Punk")
+                        .and(Rocksky::Filter.gt(:duration, 200_000))
+                        .or(Rocksky::Filter.is_in(:genre, %w[house electro]))
+filter.to_s # => artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+
+Rocksky.catalog_songs(limit: 20, filter: filter)
+Rocksky.scrobble_feed(filter: Rocksky::Filter.eq(:"track.artist", "Daft Punk"))
+```
+
+Constructors: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `is_in`, `is_out` (aliases
+`in`/`out`), `is_null`, `is_not_null`. Combine with `#and` (`;`) and `#or`
+(`,`); an OR operand inside an AND is parenthesized automatically. String
+values are quoted/escaped when they contain reserved characters, and `*`
+wildcards pass through unquoted (`Filter.eq(:artist, "Daft*")`). A raw RSQL
+String is accepted anywhere a `Filter` is.
+
 ### Writes — `Rocksky::Agent`
 
 `Agent.login(session_path, identifier, password, appview:, dedup_path:)` → an

data/lib/rocksky/filter.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Standalone — no native core involved. Loads on its own via
+# `require "rocksky/filter"`.
+module Rocksky
+  # Fluent builder for RSQL filter expressions, accepted by the +filter:+
+  # parameter of the catalog and scrobble-feed queries
+  # (app.rocksky.song.getSongs, app.rocksky.artist.getArtists,
+  # app.rocksky.album.getAlbums, app.rocksky.scrobble.getScrobbles).
+  #
+  #     require "rocksky"
+  #
+  #     filter = Rocksky::Filter.eq(:artist, "Daft Punk")
+  #                             .and(Rocksky::Filter.gt(:duration, 200_000))
+  #                             .or(Rocksky::Filter.is_in(:genre, %w[house electro]))
+  #
+  #     Rocksky.catalog_songs(filter: filter)
+  #     # artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+  #
+  # Fields are Symbols (Strings work too); dotted selectors on the scrobble
+  # feed are written as +:"track.artist"+. String values are quoted and
+  # escaped automatically when they contain characters RSQL reserves; +*+
+  # wildcards pass through unquoted so <tt>Filter.eq(:artist, "Daft*")</tt>
+  # performs a case-insensitive match.
+  class Filter
+    # Characters that never need quoting in an RSQL value (+*+ kept bare so
+    # wildcards work).
+    SAFE_VALUE = /\A[A-Za-z0-9_.:@*+-]+\z/
+    private_constant :SAFE_VALUE
+
+    class << self
+      # +field==value+ — equals; +*+ in string values is a wildcard.
+      def eq(field, value)
+        comparison(field, "==", value)
+      end
+
+      # +field!=value+ — not equals.
+      def ne(field, value)
+        comparison(field, "!=", value)
+      end
+
+      # +field=gt=value+ — greater than.
+      def gt(field, value)
+        comparison(field, "=gt=", value)
+      end
+
+      # +field=ge=value+ — greater than or equal.
+      def ge(field, value)
+        comparison(field, "=ge=", value)
+      end
+
+      # +field=lt=value+ — less than.
+      def lt(field, value)
+        comparison(field, "=lt=", value)
+      end
+
+      # +field=le=value+ — less than or equal.
+      def le(field, value)
+        comparison(field, "=le=", value)
+      end
+
+      # +field=in=(a,b)+ — matches any of the values.
+      def is_in(field, values)
+        list(field, "=in=", values)
+      end
+
+      # +field=out=(a,b)+ — matches none of the values.
+      def is_out(field, values)
+        list(field, "=out=", values)
+      end
+
+      alias in is_in
+      alias out is_out
+
+      # +field==null+ — the field is NULL.
+      def is_null(field)
+        new("#{field}==null", :comparison)
+      end
+
+      # +field!=null+ — the field is not NULL.
+      def is_not_null(field)
+        new("#{field}!=null", :comparison)
+      end
+
+      private
+
+      def comparison(field, op, value)
+        new("#{field}#{op}#{render_value(value)}", :comparison)
+      end
+
+      def list(field, op, values)
+        name = op == "=in=" ? "is_in" : "is_out"
+        raise ArgumentError, "Filter.#{name}(#{field.inspect}, ...) needs at least one value" if values.empty?
+
+        new("#{field}#{op}(#{values.map { |v| render_value(v) }.join(",")})", :comparison)
+      end
+
+      def render_value(value)
+        return value.to_s if value.is_a?(Integer) || value.is_a?(Float) ||
+                             value == true || value == false
+
+        str = value.to_s
+        return str if !str.empty? && SAFE_VALUE.match?(str)
+
+        %("#{str.gsub(/(["\\])/) { "\\#{Regexp.last_match(1)}" }}")
+      end
+    end
+
+    def initialize(expr, kind)
+      @expr = expr
+      @kind = kind
+    end
+
+    # Both sides must match (+;+). An +or+ operand is parenthesized to keep
+    # RSQL precedence.
+    def and(other)
+      Filter.new("#{operand_in_and};#{other.operand_in_and}", :and)
+    end
+
+    # Either side may match (+,+). Never parenthesizes.
+    def or(other)
+      Filter.new("#{@expr},#{other.build}", :or)
+    end
+
+    # The RSQL expression string to send as the +filter+ query param.
+    def build
+      @expr
+    end
+
+    alias to_s build
+
+    protected
+
+    def operand_in_and
+      @kind == :or ? "(#{@expr})" : @expr
+    end
+  end
+end

data/lib/rocksky/manifest.json

@@ -1,12 +1,12 @@
 {
   "repo": "tsirysndr/rocksky",
-  "tag": "bindings-v0.7.0",
+  "tag": "bindings-v0.8.0",
   "checksums": {
-    "aarch64-apple-darwin": "e9a772586564269dccf8448d46162b85fe5290307b818b3a4fc26ff634c2ab57",
-    "aarch64-linux-gnu": "fbfc5d12a8c532f437577f1c2e36c794760e78bb66749af33eef17d14a60cafc",
-    "x86_64-apple-darwin": "81e5628ea2f269ac8efefce85fa5eae093b1d49848aba580da9f267a36f85115",
-    "x86_64-linux-gnu": "3d3de1e3b691416676dd1c09879b14944a5c85d1d8911650113e6ee7783326e2",
-    "x86_64-unknown-freebsd": "b0ad8071e2a6baf1096d4f82221c440e56bf9426e435244ade8687f08edabf69",
-    "x86_64-unknown-netbsd": "08e9ff48d6273e63d6ebdc5eb3882777bc9bd227bc9126478a98c5041e2f1f05"
+    "aarch64-apple-darwin": "31b58deb0f3d627d37b101f06b5b4a952401040f076b4cea7436aa338080a701",
+    "aarch64-linux-gnu": "dca60c186ee83401e9afcdf1e7b31c308594f6dcda4cab25acf77254739d2a49",
+    "x86_64-apple-darwin": "bdf2c98ddc866280712c928d78d4173c1760deac6d8c567417b90ea20fba1bb4",
+    "x86_64-linux-gnu": "74dede20bb5892eff8ad321721a3f4584227bf2c97d78c2febeec095d2df46b6",
+    "x86_64-unknown-freebsd": "e6af79359f73a9d42d6232eade70f5e3938e75b66bc240e1077d76334daa08fe",
+    "x86_64-unknown-netbsd": "d1765e3c66d99a1160ddb3361ff9cfcf9c1335a056e68d089ea1c97ef6ff3f16"
   }
 }

data/lib/rocksky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rocksky
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/rocksky.rb

@@ -127,6 +127,51 @@ module Rocksky
     unwrap(C.rocksky_global_stats(base.to_s))
   end
 
+  # ---- catalog + feed reads with RSQL filtering ----
+  #
+  # +filter:+ accepts a Rocksky::Filter (see rocksky/filter.rb) or a raw RSQL
+  # String. Fields are Symbols, e.g. Rocksky::Filter.eq(:artist, "Daft Punk").
+
+  # The song catalog (app.rocksky.song.getSongs), optionally narrowed by
+  # +genre:+ and/or an RSQL +filter:+. Returns { "tracks" => [...] }.
+  def self.catalog_songs(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.song.getSongs", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # The artist catalog (app.rocksky.artist.getArtists). Returns
+  # { "artists" => [...] }.
+  def self.catalog_artists(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.artist.getArtists", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # The album catalog (app.rocksky.album.getAlbums). Returns
+  # { "albums" => [...] }.
+  def self.catalog_albums(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.album.getAlbums", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # A social/global scrobbles feed (app.rocksky.scrobble.getScrobbles). Pass
+  # +did:+ to scope to an actor and +following: true+ for their follow graph.
+  # +filter:+ reaches the joined track/user/artist via dotted fields, e.g.
+  # Rocksky::Filter.eq(:"track.artist", "Daft Punk"). Returns
+  # { "scrobbles" => [...] }.
+  def self.scrobble_feed(did: nil, following: false, limit: 50, offset: 0, filter: nil, base: nil)
+    params = { limit: limit, offset: offset }
+    params[:did] = did unless did.nil?
+    params[:following] = following if following
+    params[:filter] = filter.to_s unless filter.nil?
+    get("app.rocksky.scrobble.getScrobbles", params, base: base)
+  end
+
+  # Shared param assembly for the three catalog reads (omit-nil idiom).
+  def self.catalog_params(limit, offset, genre, filter)
+    params = { limit: limit, offset: offset }
+    params[:genre] = genre unless genre.nil?
+    params[:filter] = filter.to_s unless filter.nil?
+    params
+  end
+  private_class_method :catalog_params
+
   # Universal read escape hatch — call any app.rocksky.* query by nsid. +params+
   # is a hash of string params; the whole read-query catalog is reachable here.
   #
@@ -301,5 +346,6 @@ module Rocksky
   end
 end
 
+require_relative "rocksky/filter"
 require_relative "rocksky/library"
 require_relative "rocksky/remote"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rocksky
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Rocksky
@@ -80,6 +80,7 @@ files:
 - README.md
 - exe/rocksky-console
 - lib/rocksky.rb
+- lib/rocksky/filter.rb
 - lib/rocksky/library.rb
 - lib/rocksky/manifest.json
 - lib/rocksky/native.rb