fmrest 0.13.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa084310edbe4889c9ff8576ec6b208d676e12b7f390ffa96edd294651d86c7c
-  data.tar.gz: d1f18c369fd228f00dafd1a8d7b4dd34d045d429b554a0813b4c1388b6c145e1
+  metadata.gz: ec213ebe845fe6b4e10e5cf54550d2a73fec05ac33fbeb5a9758b8f04327a8df
+  data.tar.gz: 9313ec2d6b743a6355535736f5d1fe77656c3f1d5c2648c4dcc2de36d49347d5
 SHA512:
-  metadata.gz: 0abaf03db7360a3a8617a53ab2aaa99298017b16e4fb066a3fb5f449f936e48185cbb2e43dcac38de702996b3eec4a696f6ca0829d2f8ce2e8453232e136bc83
-  data.tar.gz: e6fcb69cda93b3bc246eb5a2feadfd6f3a6ea3fe13db2a437a429f7a0b9d998bd48f2b4c01cd68b22ad7342fc6668cf603f99f3f355c25384b54462577ebe4c7
+  metadata.gz: 406e098733ea1c945b18d6df1063be38d1e9826c68d58bf1b9ce7d47784b0b8949d4d581e9918182c883ba674f2fff1ce0d4bb5b2854587ff0a1dc3d77a76f2d
+  data.tar.gz: c6e29a0b3f63adc1bb2c5c03a6c5f0a2eadb6ed4ae864159b9d504f77b1848ed51a94e6d1ca8aeb4abed8f36a08d58a99d4c66bfff04f56e227e4b117bb4e97e

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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest
 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,28 +16,28 @@ 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: fmrest-spyke
   requirement: !ruby/object:Gem::Requirement
     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: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -222,6 +222,17 @@ licenses:
 - MIT
 metadata: {}
 post_install_message: |+
+  =======================================
+   Notes on upgrading from fmrest < 0.15
+  =======================================
+
+  There's a breaking change in the way the `.query` method behaves when chained.
+
+  Previously it would add new conditions as a logical OR in relation to
+  already set ones, whereas now by default it adds new conditions as a logical
+  AND relative to existing ones. To keep the old behavior you can use `.or.query`
+  in chained query calls instead. See documentation on querying for details.
+
   =======================================
    Notes on upgrading from fmrest < 0.13
   =======================================