README.md in fmrest-0.6.0 vs README.md in fmrest-0.7.0

- old
+ new

@@ -103,10 +103,26 @@ [Logging](#Logging) below. `:username` is also aliased as `:account_name` to provide cross-compatibility with the ginjo-rfm gem. +### Full list of available options + +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 +`: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` +`:coerce_dates` | See section on [date fields](#date-fields) | 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"` +`:time_format` | Time parsing format | String (FM date format) | `"HH:mm:ss"` + ### Default connection settings If you're only connecting to a single FM database you can configure it globally through `FmRest.default_connection_settings=`. E.g.: @@ -120,10 +136,11 @@ ``` This configuration will be used by default by `FmRest::V1.build_connection` as well as your models whenever you don't pass a configuration hash explicitly. + ## Session token store By default fmrest-ruby will use a memory-based store for the session tokens. This is generally good enough for development, but not good enough for production, as in-memory tokens aren't shared across threads/processes. @@ -216,10 +233,58 @@ ``` **NOTE:** the moneta gem is not included as a dependency of fmrest-ruby, so you'll have to add it to your Gemfile. + +## Date fields + +Since the Data API uses JSON (wich doesn't provide a native date/time object), +dates and timestamps are received in string format. By default fmrest-ruby +leaves those string fields untouched, but it provides an opt-in feature to try +to automatically "coerce" them into Ruby date objects. + +The connection option `:coerce_dates` controls this feature. Possible values +are: + +* `:full`: whenever a string matches the given date/timestamp/time format, + convert them to `Date` or `DateTime` objects as appropriate +* `:hybrid` or `true`: similar as above, but instead of converting to regular + `Date`/`DateTime` it converts strings to `FmRest::StringDate` and + `FmRest::StringDateTime`, "hybrid" classes provided by fmrest-ruby that + retain the functionality of `String` while also providing most the + functionality of `Date`/`DateTime` (more on this below) +* `false`: disable date coercion entirely (default), leave original string + values untouched + +Enabling date coercion works with both basic fmrest-ruby connections and Spyke +models (ORM). + +The connection options `:date_format`, `:timestamp_format` and `:time_format` +control how to match and parse dates. You only need to provide these if you use +a date/time localization different from American format (the default). + +Future versions of fmrest-ruby will provide better (and less heuristic) ways of +specifying and/or detecting date fields (e.g. by requesting layout metadata or +a DSL in model classes). + +### Hybrid string/date objects + +`FmRest::StringDate` and `FmRest::StringDateTime` are special classes that +inherit from `String`, but internally parse and store a `Date`/`DateTime` +(respectively), and delegate any methods not provided by `String` to those +objects. In other words, they quack like a duck *and* bark like a dog. + +You can use these when you want fmrest-ruby to provide you with date objects, +but you don't want to worry about date coercion of false positives (i.e. a +string field that gets converted to `Date` because it just so matched the given +date format). + +Be warned however that these classes come with a fair share of known gotchas +(see GitHub wiki for more info). + + ## Spyke support (ActiveRecord-like ORM) [Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for building REST models. fmrest-ruby has Spyke support out of the box, although Spyke itself is not a dependency of fmrest-ruby, so you'll need to add it to @@ -828,10 +893,11 @@ resulting collection will have a `.metadata` attribute method containing the same metadata hash with script execution results. Note that this does not apply to retrieving single records, in that case you'll have to use `.last_request_metadata`. + ## Logging If using fmrest-ruby + Spyke in a Rails app pretty log output will be set up for you automatically by Spyke (see [their README](https://github.com/balvig/spyke#log-output)). @@ -881,11 +947,11 @@ |-------------------------------------|-------------------------------|----------------------------------| | 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 +| 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 | @@ -902,24 +968,11 @@ | 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. -## TODO -- [ ] Support for FM18 features -- [ ] Better/simpler-to-use core Ruby API -- [ ] Better API documentation and README -- [ ] Oauth support -- [x] Support for portal limit and offset -- [x] More options for token storage -- [x] Support for container fields -- [x] Optional logging -- [x] FmRest::Spyke::Base class for single inheritance (as alternative for mixin) -- [x] Specs -- [x] Support for portal data - ## Gem development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment (it will auto-load all fixtures in @@ -929,29 +982,26 @@ release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). + ## Contributing Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. + ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). 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. - -## Code of Conduct - -Everyone interacting in the fmrest-ruby project’s codebases, issue trackers, -chat rooms and mailing lists is expected to follow the [code of -conduct](CODE_OF_CONDUCT.md).