fmrest 0.13.0 → 0.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04e163122c2e385a1957c0c3c111a7b4f9a75cbb04aaf362544383c78b972150
-  data.tar.gz: 2b69f8782b89ddbe4464fc7623f2abde16ccd1cdc113a56425e87a47b8b6876e
+  metadata.gz: a521c338828739448e5bd15308c97d5b099fe0c2684728479f93f10125d93892
+  data.tar.gz: 613f16988c9b1d3516088a4b699171819e6fc6531ae9bb383bdaba6074a68020
 SHA512:
-  metadata.gz: e13a616364f5e6e5f61c4e97d27ecbef7450cf427f10fceb67d67d3dfb0394fc1e07ce27d80b1d0bf4310305b46c7fd0bd32175a1ba55aba30183334e153f72a
-  data.tar.gz: 23e8705ed23af5cb644b7b8616abdb72a04c3bf82e01a99b0118451f0b0f35267db04ad86781d2f754c0622a0e8c6a8dc6a92a0c107375bd11f2e79c17ccf49f
+  metadata.gz: 148467a2ef5570c06605eb94bd2d604e3303062428f218f3c6706483e68c6ec8098b7e6c9214f219b87b10126ec73c627ca4c5ca91974dd4e323446f2436f1ae
+  data.tar.gz: cb382ee99672a58d215d00398a98c44be9ef840b5b9853f94edfb3c5c58c770f02245baf95545f0732c61c44342126ac314b698293622e8f1ad52aa67fb554ca

data/.yardopts

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

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## Changelog
 
+### 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+
+
 ### 0.13.0
 
 * Split `fmrest` gem into `fmrest-core` and `fmrest-spyke`. `fmrest` becomes a

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,9 +145,9 @@ 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
@@ -157,8 +174,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 +205,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 +233,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.
 
-In addition, `FmRest::Spyke::Base` extends `Spyke::Base` with the following
+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::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 +267,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 +276,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:
+
+```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.
 
-### Model.request_auth_token
+### 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 +324,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 +342,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 +361,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 +405,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 +427,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 +445,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)
@@ -435,7 +469,7 @@ FmRest.default_connection_settings = {
 }
 
 # Or in your model
-class LoggyBee < FmRest::Spyke::Base
+class LoggyBee < FmRest::Layout
   self.fmrest_config = {
     host: "…",
     …
@@ -449,7 +483,7 @@ If you need to set up more complex logging for your models can use 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 +494,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.
 
@@ -496,6 +530,7 @@ the following Ruby implementations:
 * Ruby 2.5
 * Ruby 2.6
 * Ruby 2.7
+* Ruby 3.0
 
 ## Gem development
 
@@ -518,6 +553,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.0
+  version: 0.15.2
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-11 00:00:00.000000000 Z
+date: 2021-04-06 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.0
+        version: 0.15.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 0.15.2
 - !ruby/object:Gem::Dependency
   name: fmrest-spyke
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 0.15.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 0.15.2
 - !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
   =======================================
@@ -266,7 +277,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.0.6
 signing_key:
 specification_version: 4
 summary: FileMaker Data API client