fmrest-spyke 0.13.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be7fffcbab34bb4d18fbca7c7279562d5ae9fea61ee7a3bea30885062ef50c73
-  data.tar.gz: e1148f44c5d730ca4406eb5aae58494b33f3562102371a3a0ce7073f5f0558e2
+  metadata.gz: 1a91619fdca8717119b8b299648d3388948551e653bececb0a90a422850be0a2
+  data.tar.gz: 9e666b8f8162522b1269a3b4d18cda8724ad7439d0398672c02d228149cb636d
 SHA512:
-  metadata.gz: 5c73415699cfef77051e1365d89c178fe05436ffef4134b88972ed93b921f2b32131007f9c3b4647ba1fcce4d6ab6f24ba924e1ae043c84cfd09c368b84b4f32
-  data.tar.gz: fac0d4d6e9f3d8397187f1c9dba29cfe62370069086aadc0760778e2d4b0fb32d29b318d534d9548896c0fbe364a52c9e27585da60b327aa465ab19cdf328a07
+  metadata.gz: 6fee0ccdc7bb75ae47f620c0cbf3da137806394225a565f5227d9a63e4ea4612b78200997dfc84594ba4eb2db84a156a28d3b05109d9dfb95f6851434bd94f6b
+  data.tar.gz: bab901d8024b1331358325f149ebc297c206e549aba81b73187748b2f168c7eecac2409170722e7a062901317084348c4ac3811bddffa07613bf944aa0f61f00

data/.yardopts

@@ -1,4 +1,5 @@
 --markup markdown
 --plugin activesupport-concern
+lib/**/*.rb
 -
 docs/*

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## Changelog
 
+### 0.16.0
+
+* Add `FmRest.logger=`
+* Handle serialization of `nil`, `true` and `false` values
+
+### 0.15.2
+
+* Fix autoloading of `FmRest::Layout`
+
+### 0.15.0
+
+* Much improved querying API (see documentation on querying), adding new
+  `.query` capabilities, as well as two new methods: `.match` and `.or`
+
+### 0.14.0
+
+* Aliased `FmRest::Spyke::Base` as `FmRest::Layout` (now preferred), and
+  provided a shortcut version for setting the layout name (e.g.  `class Foo <
+  FmRest::Layout("LayoutName")`)
+* Made `layout` class setting subclass-inheritable
+
 ### 0.13.1
 
 * Fix downloading of container field data from FMS19+

data/README.md

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/fmrest.svg?style=flat)](https://rubygems.org/gems/fmrest)
 ![CI](https://github.com/beezwax/fmrest-ruby/workflows/CI/badge.svg)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/beezwax/fmrest-ruby)
 
 A Ruby client for
 [FileMaker 18 and 19's Data API](https://help.claris.com/en/data-api-guide)
@@ -9,7 +10,7 @@ using
 [Faraday](https://github.com/lostisland/faraday) and with optional
 ActiveRecord-ish ORM features through [Spyke](https://github.com/balvig/spyke).
 
-fmrest-ruby only partially implements FileMaker 18's Data API.
+fmrest-ruby only partially implements FileMaker 19's Data API.
 See the [implementation completeness table](#api-implementation-completeness-table)
 to see if a feature you need is natively supported by the gem.
 
@@ -17,10 +18,10 @@ to see if a feature you need is natively supported by the gem.
 
 The `fmrest` gem is a wrapper for two other gems:
 
-* `fmrest-core`, which provides the core Faraday connection builder, session
+* `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
+  of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
+* `fmrest-core`, providing the core Faraday connection builder, session
   management, and other core utilities.
-* `fmrest-spyke`, which provides an ActiveRecord-like ORM library built on top
-  of `fmrest-core` and Spyke.
 
 ## Installation
 
@@ -30,7 +31,7 @@ Add this to your Gemfile:
 gem 'fmrest'
 ```
 
-Or if you just want to use the Faraday connection without the ORM features, do:
+Or if you just want to use the Faraday connection without the ORM features:
 
 ```ruby
 gem 'fmrest-core'
@@ -40,10 +41,11 @@ gem 'fmrest-core'
 
 ### ORM example
 
-Most people would want to use the ORM features provided by `fmrest-spyke`:
+Most people would want to use the ORM features:
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+# A Layout model connecting to the "Honeybees Web" FileMaker layout
+class Honeybee < FmRest::Layout("Honeybees Web")
   # Connection settings
   self.fmrest_config = {
     host:     "…",
@@ -53,13 +55,28 @@ class Honeybee < FmRest::Spyke::Base
   }
 
   # Mapped attributes
-  attributes name: "Bee Name", age: "Bee Age"
+  attributes name: "Bee Name", age: "Bee Age", created_on: "Created On"
 
-  # Portals
-  has_portal :flowers
+  # Portal associations
+  has_portal :tasks
 
-  # File container
+  # File containers
   container :photo, field_name: "Bee Photo"
+
+  # Scopes
+  scope :can_legally_fly, -> { query(age: ">18") }
+
+  # Client-side validations
+  validates :name, presence: true
+
+  # Callbacks
+  before_save :set_created_on
+
+  private
+
+  def set_created_on
+    self.created_on = Date.today
+  end
 end
 
 # Find a record by id
@@ -68,7 +85,7 @@ bee = Honeybee.find(9)
 bee.name = "Hutch"
 
 # Add a new record to portal
-bee.flowers.build(name: "Daisy")
+bee.tasks.build(urgency: "Today")
 
 bee.save
 ```
@@ -88,11 +105,11 @@ connection = FmRest::V1.build_connection(
 )
 
 # Get all records (as parsed JSON)
-connection.get("layouts/MyFancyLayout/records")
+connection.get("layouts/FancyLayout/records")
 
 # Create new record
 connection.post do |req|
-  req.url "layouts/MyFancyLayout/records"
+  req.url "layouts/FancyLayout/records"
 
   # You can just pass a hash for the JSON body
   req.body = { … }
@@ -128,13 +145,14 @@ You can also pass a `:log` option for basic request logging, see the section on
 Option              | Description                                | Format                      | Default
 --------------------|--------------------------------------------|-----------------------------|--------
 `:host`             | Hostname with optional port, e.g. `"example.com:9000"` | String          | None
-`:database`         |                                            | String                      | None
-`:username`         |                                            | String                      | None
-`:password`         |                                            | String                      | None
+`:database`         | The name of the database to connect to     | String                      | None
+`:username`         | A Data API-ready account                   | String                      | None
+`:password`         | Your password                              | String                      | None
 `:account_name`     | Alias of `:username`                       | String                      | None
 `:ssl`              | SSL options to be forwarded to Faraday     | Faraday SSL options         | None
 `:proxy`            | Proxy options to be forwarded to Faraday   | Faraday proxy options       | None
 `:log`              | Log JSON responses to STDOUT               | Boolean                     | `false`
+`:log_level`        | Which log level to log into                | Values accepted by `Logger#level=` | `:debug`
 `:coerce_dates`     | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
 `:date_format`      | Date parsing format                        | String (FM date format)     | `"MM/dd/yyyy"`
 `:timestamp_format` | Timestmap parsing format                   | String (FM date format)     | `"MM/dd/yyyy HH:mm:ss"`
@@ -157,8 +175,8 @@ FmRest.default_connection_settings = {
 }
 ```
 
-These settings will be used by default by `FmRest::Spyke::Base` models whenever
-you don't set `fmrest_config=` explicitly, as well as by
+These settings will be used by default by `FmRest::Layout` models whenever you
+don't set `fmrest_config=` explicitly, as well as by
 `FmRest::V1.build_connection` in case you're setting up your Faraday connection
 manually.
 
@@ -188,11 +206,11 @@ building REST ORM models. fmrest-ruby builds its ORM features atop Spyke,
 bundled in the `fmrest-spyke` gem (already included if you're using the
 `fmrest` gem).
 
-To create a model you can inherit directly from `FmRest::Spyke::Base`, which is
-itself a subclass of `Spyke::Base`.
+To create a model you can inherit directly from `FmRest::Layout` (itself a
+subclass of `Spyke::Base`).
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+class Honeybee < FmRest::Layout
 end
 ```
 
@@ -216,17 +234,23 @@ bee = Honeybee.find(9) # GET request
 
 It's recommended that you read Spyke's documentation for more information on
 these basic features. If you've used ActiveRecord or similar ORM libraries
-however you'll find it quite familiar.
+you'll find it quite familiar.
+
+Notice that `FmRest::Layout` is aliased as `FmRest::Spyke::Base`. Previous
+versions of fmrest-ruby only provided the latter version, so if you're already
+using `FmRest::Spyke::Base` there's no need to rename your classes to
+`FmRest::Layout`, both will continue to work interchangeably.
 
-In addition, `FmRest::Spyke::Base` extends `Spyke::Base` with the following
+In addition, `FmRest::Layout` extends `Spyke::Base` with the following
 features:
 
-### Model.fmrest_config=
+### FmRest::Layout.fmrest_config=
 
-This allows you to set your Data API connection settings on your model:
+This allows you to set Data API connection settings specific to your model
+class:
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+class Honeybee < FmRest::Layout
   self.fmrest_config = {
     host:     "…",
     database: "…",
@@ -244,9 +268,8 @@ does the initial connection setup and then inherit from it in models using that
 same connection. E.g.:
 
 ```ruby
-class BeeBase < FmRest::Spyke::Base
-  self.fmrest_config = { host: "…", … }
-  }
+class BeeBase < FmRest::Layout
+  self.fmrest_config = { host: "…", database: "…", … }
 end
 
 class Honeybee < BeeBase
@@ -254,34 +277,46 @@ class Honeybee < BeeBase
 end
 ```
 
+Also, if not set, your model will try to use
+`FmRest.default_connection_settings` instead.
+
 #### Connection settings overlays
 
 There may be cases where you want to use a different set of connection settings
 depending on context. For example, if you want to use username and password
-provided by the user in a web application. Since `Model.fmrest_config` is set
-at the class level, changing the username/password for the model in one context
-would also change it in all other contexts, leading to security issues.
+provided by the user in a web application. Since `.fmrest_config`
+is set at the class level, changing the username/password for the model in one
+context would also change it in all other contexts, leading to security issues.
 
 To solve this scenario, fmrest-ruby provides a way of defining thread-local and
-reversible connection settings overlays through `Model.fmrest_config_overlay=`.
+reversible connection settings overlays through
+`.fmrest_config_overlay=`.
 
 See the [main document on connection setting overlays](docs/ConfigOverlays.md)
 for details on how it works.
 
-### Model.layout
+### FmRest::Layout.layout
 
-Use `Model.layout` to define the layout for your model.
+Use `layout` to set the layout name for your model.
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+class Honeybee < FmRest::Layout
   layout "Honeybees Web"
 end
 ```
 
-Note that you only need to set this if the name of the model and the name of
-the layout differ, otherwise the default will just work.
+Alternatively, if you're inheriting from `FmRest::Layout` directly you can set
+the layout name in the class definition line:
 
-### Model.request_auth_token
+```ruby
+class Honeybee < FmRest::Layout("Honeybees Web")
+```
+
+Note that you only need to manually set the layout name if the name of the
+class and the name of the layout differ, otherwise fmrest-ruby will just use
+the name of the class.
+
+### FmRest::Layout.request_auth_token
 
 Requests a Data API session token using the connection settings in
 `fmrest_config` and returns it if successful, otherwise returns `false`.
@@ -290,16 +325,16 @@ You normally don't need to use this method as fmrest-ruby will automatically
 request and store session tokens for you (provided that `:autologin` is
 `true`).
 
-### Model.logout
+### FmRest::Layout.logout
 
-Use `Model.logout` to log out from the database session (you may call it on any
+Use `.logout` to log out from the database session (you may call it on any
 model that uses the database session you want to log out from).
 
 ```ruby
 Honeybee.logout
 ```
 
-### Mapped Model.attributes
+### Mapped FmRest::Layout.attributes
 
 Spyke allows you to define your model's attributes using `attributes`, however
 sometimes FileMaker's field names aren't very Ruby-ORM-friendly, especially
@@ -308,7 +343,7 @@ fmrest-ruby extends `attributes`' functionality to allow you to map
 Ruby-friendly attribute names to FileMaker field names. E.g.:
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+class Honeybee < FmRest::Layout
   attributes first_name: "First Name", last_name: "Last Name"
 end
 ```
@@ -327,16 +362,16 @@ bee.first_name = "Queen"
 bee.attributes # => { "First Name": "Queen", "Last Name": "Buzz" }
 ```
 
-### Model.has_portal
+### FmRest::Layout.has_portal
 
 You can define portal associations on your model wth `has_portal`, as such:
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+class Honeybee < FmRest::Layout
   has_portal :flowers
 end
 
-class Flower < FmRest::Spyke::Base
+class Flower < FmRest::Layout
   attributes :color, :species
 end
 ```
@@ -371,8 +406,8 @@ Guides](https://guides.rubyonrails.org/active_model_basics.html#dirty).
 Since Spyke is API-agnostic it only provides a wide-purpose `.where` method for
 passing arbitrary parameters to the REST backend. fmrest-ruby however is well
 aware of its backend API, so it extends Spkye models with a bunch of useful
-querying methods: `.query`, `.limit`, `.offset`, `.sort`, `.portal`, `.script`,
-etc.
+querying methods: `.query`, `.match`, `.omit`, `.limit`, `.offset`, `.sort`,
+`.portal`, `.script`, etc.
 
 See the [main document on querying](docs/Querying.md) for detailed information
 on the query API methods.
@@ -393,7 +428,7 @@ detailed information on how those work.
 You can define container fields on your model class with `container`:
 
 ```ruby
-class Honeybee < FmRest::Spyke::Base
+class Honeybee < FmRest::Layout
   container :photo, field_name: "Beehive Photo ID"
 end
 ```
@@ -411,7 +446,7 @@ details.
 
 ### Setting global field values
 
-You can call `.set_globals` on any `FmRest::Spyke::Base` model to set global
+You can call `.set_globals` on any `FmRest::Layout` model to set global
 field values on the database that model is configured for.
 
 See the [main document on setting global field values](docs/GlobalFields.md)
@@ -423,7 +458,7 @@ If using `fmrest-spyke` with Rails then pretty log output will be set up for
 you automatically by Spyke (see [their
 README](https://github.com/balvig/spyke#log-output)).
 
-You can also enable simple Faraday STDOUT logging of raw requests (useful for
+You can also enable simple Faraday logging of raw requests (useful for
 debugging) by passing `log: true` in the options hash for either
 `FmRest.default_connection_settings=` or your models' `fmrest_config=`, e.g.:
 
@@ -435,7 +470,7 @@ FmRest.default_connection_settings = {
 }
 
 # Or in your model
-class LoggyBee < FmRest::Spyke::Base
+class LoggyBee < FmRest::Layout
   self.fmrest_config = {
     host: "…",
     …
@@ -444,12 +479,22 @@ class LoggyBee < FmRest::Spyke::Base
 end
 ```
 
-If you need to set up more complex logging for your models can use the
+You can also pass `log_level` to connection settings to change the severity of
+log output (defaults to `:debug`).
+
+By default fmrest-ruby logs to STDOUT or to Rails' logger object if available.
+You can change this by providing your own logger object to `FmRest.logger=`:
+
+```ruby
+FmRest.logger = Logger.new("fmrest.log")
+```
+
+If you need to set up more complex logging for your models you can use the
 `faraday` block inside your class to inject your own logger middleware into the
 Faraday connection, e.g.:
 
 ```ruby
-class LoggyBee < FmRest::Spyke::Base
+class LoggyBee < FmRest::Layout
   faraday do |conn|
     conn.response :logger, MyApp.logger, bodies: true
   end
@@ -460,31 +505,31 @@ end
 
 FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
 
-| FM 18 Data API feature              | Supported by basic connection | Supported by FmRest::Spyke::Base |
-|-------------------------------------|-------------------------------|----------------------------------|
-| Log in using HTTP Basic Auth        | Yes                           | Yes                              |
-| Log in using OAuth                  | No                            | No                               |
-| Log in to an external data source   | No                            | No                               |
-| Log in using a FileMaker ID account | No                            | No                               |
-| Log out                             | Yes                           | Yes                              |
-| Get product information             | Manual*                       | No                               |
-| Get database names                  | Manual*                       | No                               |
-| Get script names                    | Manual*                       | No                               |
-| Get layout names                    | Manual*                       | No                               |
-| Get layout metadata                 | Manual*                       | No                               |
-| Create a record                     | Manual*                       | Yes                              |
-| Edit a record                       | Manual*                       | Yes                              |
-| Duplicate a record                  | Manual*                       | No                               |
-| Delete a record                     | Manual*                       | Yes                              |
-| Edit portal records                 | Manual*                       | Yes                              |
-| Get a single record                 | Manual*                       | Yes                              |
-| Get a range of records              | Manual*                       | Yes                              |
-| Get container data                  | Manual*                       | Yes                              |
-| Upload container data               | Manual*                       | Yes                              |
-| Perform a find request              | Manual*                       | Yes                              |
-| Set global field values             | Manual*                       | Yes                              |
-| Run a script                        | Manual*                       | Yes                              |
-| Run a script with another request   | Manual*                       | Yes                              |
+| FM 18 Data API feature              | Supported by basic connection | Supported by FmRest::Layout |
+|-------------------------------------|-------------------------------|-----------------------------|
+| Log in using HTTP Basic Auth        | Yes                           | Yes                         |
+| Log in using OAuth                  | No                            | No                          |
+| Log in to an external data source   | No                            | No                          |
+| Log in using a FileMaker ID account | No                            | No                          |
+| Log out                             | Yes                           | Yes                         |
+| Get product information             | Manual*                       | No                          |
+| Get database names                  | Manual*                       | No                          |
+| Get script names                    | Manual*                       | No                          |
+| Get layout names                    | Manual*                       | No                          |
+| Get layout metadata                 | Manual*                       | No                          |
+| Create a record                     | Manual*                       | Yes                         |
+| Edit a record                       | Manual*                       | Yes                         |
+| Duplicate a record                  | Manual*                       | No                          |
+| Delete a record                     | Manual*                       | Yes                         |
+| Edit portal records                 | Manual*                       | Yes                         |
+| Get a single record                 | Manual*                       | Yes                         |
+| Get a range of records              | Manual*                       | Yes                         |
+| Get container data                  | Manual*                       | Yes                         |
+| Upload container data               | Manual*                       | Yes                         |
+| Perform a find request              | Manual*                       | Yes                         |
+| Set global field values             | Manual*                       | Yes                         |
+| Run a script                        | Manual*                       | Yes                         |
+| Run a script with another request   | Manual*                       | Yes                         |
 
 \* You can manually supply the URL and JSON to a `FmRest` connection.
 
@@ -519,6 +564,6 @@ See [LICENSE.txt](LICENSE.txt).
 
 ## Disclaimer
 
-This project is not sponsored by or otherwise affiliated with FileMaker, Inc,
-an Apple subsidiary. FileMaker is a trademark of FileMaker, Inc., registered in
-the U.S. and other countries.
+This project is not sponsored by or otherwise affiliated with Claris
+International Inc., an Apple Inc. subsidiary. FileMaker is a trademark of
+Claris International Inc., registered in the U.S. and other countries.

data/lib/fmrest/spyke.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
-begin
-  require "spyke"
-rescue LoadError => e
-  e.message << " (Did you include Spyke in your Gemfile?)" unless e.message.frozen?
-  raise e
-end
-
+require "spyke"
 require "fmrest"
 require "fmrest/spyke/spyke_formatter"
 require "fmrest/spyke/model"

data/lib/fmrest/spyke/base.rb

@@ -6,4 +6,19 @@ module FmRest
       include FmRest::Spyke::Model
     end
   end
+
+  Layout = Spyke::Base
+
+  # Shortcut for creating a Layout class and setting its FM layout name.
+  #
+  # @param layout [String] The FM layout to connect this class to
+  #
+  # @return [Class] A new subclass of `FmRest::Layout` with the FM layout
+  #   setting already set.
+  #
+  def self.Layout(layout)
+    Class.new(Layout) do
+      self.layout layout
+    end
+  end
 end

data/lib/fmrest/spyke/model/orm.rb

@@ -26,10 +26,10 @@ module FmRest
 
         class_methods do
           # Methods delegated to `FmRest::Spyke::Relation`
-          delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
-                   :portals, :includes, :with_all_portals, :without_portals,
-                   :script, :find_one, :first, :any, :find_some,
-                   :find_in_batches, :find_each, to: :all
+          delegate :limit, :offset, :sort, :order, :query, :match, :omit,
+            :portal, :portals, :includes, :with_all_portals, :without_portals,
+            :script, :find_one, :first, :any, :find_some, :find_in_batches,
+            :find_each, to: :all
 
           # Spyke override -- Use FmRest's Relation instead of Spyke's vanilla
           # one

data/lib/fmrest/spyke/model/serialization.rb

@@ -4,9 +4,6 @@ module FmRest
   module Spyke
     module Model
       module Serialization
-        FM_DATE_FORMAT = "%m/%d/%Y"
-        FM_DATETIME_FORMAT = "#{FM_DATE_FORMAT} %H:%M:%S"
-
         # Spyke override -- Return FM Data API's expected JSON format,
         # including only modified fields.
         #
@@ -76,13 +73,21 @@ module FmRest
         # Modifies the given hash in-place encoding non-string values (e.g.
         # dates) to their string representation when appropriate.
         #
+        # nil gets converted to empty string as the Data API doesn't accept
+        # nulls in JSON. Likewise, true and false get converted to 1 and 0
+        # respectively.
+        #
         def serialize_values!(params)
           params.transform_values! do |value|
             case value
-            when *datetime_classes
-              convert_datetime_timezone(value.to_datetime).strftime(FM_DATETIME_FORMAT)
-            when *date_classes
-              value.strftime(FM_DATE_FORMAT)
+            when *FmRest::V1.datetime_classes
+              FmRest::V1.convert_datetime_timezone(value.to_datetime, fmrest_config.timezone).strftime(FmRest::V1::Dates::FM_DATETIME_FORMAT)
+            when *FmRest::V1.date_classes
+              value.strftime(FmRest::V1::Dates::FM_DATE_FORMAT)
+            when nil
+              ""
+            when true, false
+              value ? 1 : 0
             else
               value
             end
@@ -90,25 +95,6 @@ module FmRest
 
           params
         end
-
-        def convert_datetime_timezone(dt)
-          case fmrest_config.timezone
-          when :utc, "utc"
-            dt.new_offset(0)
-          when :local, "local"
-            dt.new_offset(FmRest::V1.local_offset_for_datetime(dt))
-          when nil
-            dt
-          end
-        end
-
-        def datetime_classes
-          [DateTime, Time, defined?(FmRest::StringDateTime) && FmRest::StringDateTime].compact
-        end
-
-        def date_classes
-          [Date, defined?(FmRest::StringDate) && FmRest::StringDate].compact
-        end
       end
     end
   end

data/lib/fmrest/spyke/model/uri.rb

@@ -6,12 +6,26 @@ module FmRest
       module URI
         extend ::ActiveSupport::Concern
 
+        included do
+          # Make the layout setting inheritable
+          class_attribute :_layout, instance_predicate: false
+
+          class << self
+            protected :_layout
+          end
+        end
+
         class_methods do
-          # Accessor for FM layout (helps with building the URI)
+          # Accessor for FM layout (user for building request URIs).
+          #
+          # @param layout [String] The FM layout to connect this class to
+          #
+          # @return [String] The current layout if manually set, or the name of
+          #   the class otherwise
           #
           def layout(layout = nil)
-            @layout = layout if layout
-            @layout ||= model_name.name
+            self._layout = layout.dup.to_s.freeze if layout
+            self._layout || model_name.name
           end
 
           # Spyke override -- Extends `uri` to default to FM Data's URI schema

data/lib/fmrest/spyke/relation.rb

@@ -5,6 +5,8 @@ module FmRest
     class Relation < ::Spyke::Relation
       SORT_PARAM_MATCHER = /(.*?)(!|__desc(?:end)?)?\Z/.freeze
 
+      class UnknownQueryKey < ArgumentError; end
+
       # NOTE: We need to keep limit, offset, sort, query and portal accessors
       # separate from regular params because FM Data API uses either "limit" or
       # "_limit" (or "_offset", etc.) as param keys depending on the type of
@@ -12,7 +14,7 @@ module FmRest
 
 
       attr_accessor :limit_value, :offset_value, :sort_params, :query_params,
-                    :included_portals, :portal_params, :script_params
+                    :or_flag, :included_portals, :portal_params, :script_params
 
       def initialize(*_args)
         super
@@ -161,16 +163,111 @@ module FmRest
         portal(false)
       end
 
+      # Sets conditions for a find request. Conditions must be given in
+      # `{ field: condition }` format, where `condition` is normally a string
+      # sent raw to the Data API server, so you can use FileMaker find
+      # operators. You can also pass Ruby range or date/datetime objects for
+      # condition values, and they'll be converted to the appropriate Data API
+      # representation.
+      #
+      # Passing `omit: true` in a conditions set will negate all conditions in
+      # that set.
+      #
+      # You can modify the way conditions are added (i.e. through logical AND
+      # or OR) by pre-chaining `.or`. By default it adds conditions through
+      # logical AND.
+      #
+      # Note that because of the way the Data API works, logical AND conditions
+      # on a single field are not possible. Because of that, if you try to set
+      # two AND conditions for the same field, the previously existing one will
+      # be overwritten with the new condition.
+      #
+      # It is recommended that you learn how the Data API represents conditions
+      # in its find requests (i.e. an array of JSON objects with conditions on
+      # fields). This method internally uses that same representation, which
+      # you can view by inspecting the resulting relations. Understanding that
+      # representation will also make the limitations of this Ruby API clear.
+      #
+      # @example
+      #   Person.query(name: "=Alice") # Simple query
+      #   Person.query(age: (20..29)) # Query using a Ruby range
+      #   Person.query(created_on: Date.today..Date.today-1)
+      #   Person.query(name: "=Alice", age: ">20") # Query multiple fields (logical AND)
+      #   Person.query(name: "=Alice").query(age: ">20") # Same effect as above example
+      #   Person.query(name: "=Bob", omit: true) # Negate a query (i.e. find people not named Bob)
+      #   Person.query(pets: { name: "=Snuggles" }) # Query portal fields
+      #   Person.query({ name: "=Alice" }, { name: "=Bob" }) # Separate conditions through logical OR
+      #   Person.query(name: "=Alice").or.query(name: "=Bob") # Same effect as above example
+      # @return [FmRest::Spyke::Relation] a new relation with the given find
+      #   conditions applied
       def query(*params)
         with_clone do |r|
-          r.query_params += params.flatten.map { |p| normalize_query_params(p) }
+          params = params.flatten.map { |p| normalize_query_params(p) }
+
+          if r.or_flag || r.query_params.empty?
+            r.query_params += params
+            r.or_flag = nil
+          elsif params.length > r.query_params.length
+            params[0, r.query_params.length].each_with_index do |p, i|
+              r.query_params[i].merge!(p)
+            end
+
+            remainder = params.length - r.query_params.length
+            r.query_params += params[-remainder, remainder]
+          else
+            params.each_with_index { |p, i| r.query_params[i].merge!(p) }
+          end
         end
       end
 
+      # Similar to `.query`, but sets exact string match queries (i.e.
+      # prefixes queries with ==) and escapes find operators in the given
+      # queries using `FmRest.e`.
+      #
+      # @example
+      #   Person.query(email: "bob@example.com") # Find exact email
+      # @return [FmRest::Spyke::Relation] a new relation with the exact match
+      #   conditions applied
+      def match(*params)
+        query(transform_query_values(params) { |v| "==#{FmRest::V1.escape_find_operators(v)}" })
+      end
+
+      # Negated version of `.query`, sets conditions to omit in a find request.
+      #
+      # This is the same as passing `omit: true` to `.query`.
+      #
+      # @return [FmRest::Spyke::Relation] a new relation with the given find
+      #   conditions applied negated
       def omit(params)
         query(params.merge(omit: true))
       end
 
+      # Signals that the next query conditions to be set (through `.query`,
+      # `.match`, etc.) should be added as a logical OR relative to previously
+      # set conditions (rather than the default AND).
+      #
+      # In practice this means the JSON query request will have a new
+      # conditions object appended, e.g.:
+      #
+      # ```
+      # {"query": [{"field": "condition"}, {"field": "OR-added condition"}]}
+      # ```
+      #
+      # You can call this method with or without parameters. If parameters are
+      # given they will be passed down to `.query` (and those conditions
+      # immediately set), otherwise it just prepares the next
+      # conditions-setting method to use OR.
+      #
+      # @example
+      #   # Add conditions directly in .or call:
+      #   Person.query(name: "=Alice").or(name: "=Bob")
+      #   # Add exact match conditions through method chaining
+      #   Person.match(email: "alice@example.com").or.match(email: "bob@example.com")
+      def or(*params)
+        clone = with_clone { |r| r.or_flag = true }
+        params.empty? ? clone : clone.query(*params)
+      end
+
       # @return [Boolean] whether a query was set on this relation
       def has_query?
         query_params.present?
@@ -328,11 +425,91 @@ module FmRest
             next
           end
 
-          # TODO: Raise ArgumentError if an attribute given as symbol isn't defiend
-          if k.kind_of?(Symbol) && klass.mapped_attributes.has_key?(k)
-            normalized[klass.mapped_attributes[k].to_s] = v
+          # Portal fields query (nested hash), e.g. { contact: { name: "Hutch" } }
+          if v.kind_of?(Hash)
+            if k.kind_of?(Symbol)
+              portal_key, = klass.portal_options.find { |_, opts| opts[:name].to_s == k.to_s }
+
+              if portal_key
+                portal_model = klass.associations[k].klass
+
+                portal_normalized = v.each_with_object({}) do |(pk, pv), h|
+                  normalize_single_query_param_for_model(portal_model, pk, pv, h)
+                end
+
+                normalized.merge!(portal_normalized.transform_keys { |pf| "#{portal_key}::#{pf}" })
+              else
+                raise UnknownQueryKey, "No portal matches the query key `:#{k}` on #{klass.name}. If you are trying to use the literal string '#{k}' pass it as a string instead of a symbol."
+              end
+            else
+              normalized.merge!(v.transform_keys { |pf| "#{k}::#{pf}" })
+            end
+
+            next
+          end
+
+          # Attribute query (scalar values), e.g. { name: "Hutch" }
+          normalize_single_query_param_for_model(klass, k, v, normalized)
+        end
+      end
+
+      def normalize_single_query_param_for_model(model, k, v, hash)
+        if k.kind_of?(Symbol)
+          if model.mapped_attributes.has_key?(k)
+            hash[model.mapped_attributes[k].to_s] = format_query_condition(v)
+          else
+            raise UnknownQueryKey, "No attribute matches the query key `:#{k}` on #{model.name}. If you are trying to use the literal string '#{k}' pass it as a string instead of a symbol."
+          end
+        else
+          hash[k.to_s] = format_query_condition(v)
+        end
+      end
+
+      # Transforms various Ruby data types to FileMaker search condition
+      # strings
+      #
+      def format_query_condition(condition)
+        case condition
+        when nil
+          "=" # Search for empty field
+        when Range
+          format_range_condition(condition)
+        when *FmRest::V1.datetime_classes
+          FmRest::V1.convert_datetime_timezone(condition.to_datetime, klass.fmrest_config.timezone)
+            .strftime(FmRest::V1::Dates::FM_DATETIME_FORMAT)
+        when *FmRest::V1.date_classes
+          condition.strftime(FmRest::V1::Dates::FM_DATE_FORMAT)
+        else
+          condition
+        end
+      end
+
+      def format_range_condition(range)
+        if range.first.kind_of?(Numeric)
+          if range.first == Float::INFINITY || range.end == -Float::INFINITY
+            raise ArgumentError, "Can't search for a range that begins at +Infinity or ends at -Infinity"
+          elsif range.first == -Float::INFINITY
+            if range.end == Float::INFINITY || range.end.nil?
+              "*" # Search for non-empty field
+            else
+              range.exclude_end? ? "<#{range.end}" : "<=#{range.end}"
+            end
+          elsif range.end == Float::INFINITY || range.end.nil?
+            ">=#{range.first}"
+          elsif range.exclude_end? && range.last.respond_to?(:pred)
+            "#{range.first}..#{range.last.pred}"
           else
-            normalized[k.to_s] = v
+            "#{range.first}..#{range.last}"
+          end
+        else
+          "#{format_query_condition(range.first)}..#{format_query_condition(range.last)}"
+        end
+      end
+
+      def transform_query_values(*params, &block)
+        params.flatten.map do |p|
+          p.transform_values do |v|
+            v.kind_of?(Hash) ? v.transform_values(&block) : yield(v)
           end
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest-spyke
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-16 00:00:00.000000000 Z
+date: 2021-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fmrest-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.1
+        version: 0.16.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.1
+        version: 0.16.0
 - !ruby/object:Gem::Dependency
   name: spyke
   requirement: !ruby/object:Gem::Requirement