sheets_v4 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6357385eeb33468356dd974f8fda49f92e09b30b9911a825c562509bf5f70dd
-  data.tar.gz: a289b95495fd49e8221a89e037168aaae903ca40af2f9167cff60c75c0f28acc
+  metadata.gz: 60f10846ff0c3b62cb29c487499eb717897a2b28916606de7d3199fe0424435f
+  data.tar.gz: a6bb345b4379f94dbaa82b266943c144321e3bcf3404db34c1788e766813a766
 SHA512:
-  metadata.gz: 59b81fbfa525ee8f5810d1aeeb3d6168dfffe0ffd1a8c19792d8f27548cdb1b2106748a30f499f8619bd83cd73d773c5647f0b7fd57640c990af2eb7e9d5fd7b
-  data.tar.gz: '09ffa389430c102e6e4df4370bc42f2e8769399f78cabbfe61441372ed6bf4a87378a124a3c17fe0c7f53a73255fae7f153cd08df67e93589c5bcbb49360166e'
+  metadata.gz: 6914986ccca02b55b260b2a39e6777ce5e2cbca03f6fd00053d8ed96a960456831ee008bd175448da343eeaf0bcfc8c67309e489035b9792ec4ce51aba29d917
+  data.tar.gz: f76c250d9b9bec531ca6185ef3b2b351df6e0a12eccb1d6f862cf6a63d4b81305798630d992d3ec22fb44a94cbd488f3736e85da6ff72302eb7b7cf87017e176

data/CHANGELOG.md

@@ -4,6 +4,22 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## v0.6.0 (2023-10-03)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.5.0..v0.6.0)
+
+Changes since v0.5.0:
+
+* 2eab61d Update documentation explaining how to construct and validate a request (#17)
+
+## v0.5.0 (2023-10-01)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.4.0..v0.5.0)
+
+Changes since v0.4.0:
+
+* b403430 Refactor SheetsV4.validate_api_object (#15)
+
 ## v0.4.0 (2023-09-29)
 
 [Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.3.0..v0.4.0)

data/README.md

@@ -9,29 +9,51 @@
 
 Unofficial helpers for the Google Sheets V4 API
 
-* [Important Links for Programming Google Sheets](#important-links-for-programming-google-sheets)
-  * [General API Documentation](#general-api-documentation)
-  * [Ruby Implementation of the Sheets API](#ruby-implementation-of-the-sheets-api)
-  * [Other Links](#other-links)
 * [Installation](#installation)
+* [Important links for programming Google Sheets](#important-links-for-programming-google-sheets)
+  * [General API documentation](#general-api-documentation)
+  * [Ruby implementation of the Sheets API](#ruby-implementation-of-the-sheets-api)
+  * [Other Links](#other-links)
+* [Getting Started](#getting-started)
+  * [Creating a Google Cloud project](#creating-a-google-cloud-project)
+  * [Enable the APIs you want to use](#enable-the-apis-you-want-to-use)
+  * [Create a Google API credentials](#create-a-google-api-credentials)
 * [Usage](#usage)
   * [Obtaining an authenticated SheetsService](#obtaining-an-authenticated-sheetsservice)
+  * [Building a request](#building-a-request)
+    * [Method 1: constructing requests using `Google::Apis::SheetsV4::*` objects](#method-1-constructing-requests-using-googleapissheetsv4-objects)
+    * [Method 2: constructing requests using hashes](#method-2-constructing-requests-using-hashes)
+    * [Which method should be used?](#which-method-should-be-used)
+  * [Validating requests](#validating-requests)
   * [Colors](#colors)
 * [Development](#development)
-* [Creating a Google API Service Account](#creating-a-google-api-service-account)
 * [Contributing](#contributing)
 * [License](#license)
 
-## Important Links for Programming Google Sheets
+## Installation
 
-### General API Documentation
+Install the gem and add to the application's Gemfile by executing:
+
+```shell
+bundle add sheets_v4
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```shell
+gem install sheets_v4
+```
+
+## Important links for programming Google Sheets
+
+### General API documentation
 
 * [Google Sheets API Overview](https://developers.google.com/sheets/api)
 * [Google Sheets API Reference](https://developers.google.com/sheets/api/reference/rest)
 * [Batch Update Requests](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request)
 * [Discovery Document for the Sheets API](https://sheets.googleapis.com/$discovery/rest?version=v4)
 
-### Ruby Implementation of the Sheets API
+### Ruby implementation of the Sheets API
 
 * [SheetsService Class](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/service.rb)
 * [All Other Sheets Classes](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/classes.rb)
@@ -40,19 +62,25 @@ Unofficial helpers for the Google Sheets V4 API
 
 * [Apps Script for Sheets](https://developers.google.com/apps-script/guides/sheets)
 
-## Installation
+## Getting Started
 
-Install the gem and add to the application's Gemfile by executing:
+In order to use this gem, you will need to obtain a Google API sheets service
+credential following the instructions below.
 
-```shell
-bundle add sheets_v4
-```
+### Creating a Google Cloud project
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Create a Google Cloud project using [these directions](https://developers.google.com/workspace/guides/create-project).
 
-```shell
-gem install sheets_v4
-```
+### Enable the APIs you want to use
+
+Enable the Sheets API for this project using [these directions](https://developers.google.com/workspace/guides/enable-apis).
+
+### Create a Google API credentials
+
+Create a service account and download credentials using [these directions](https://developers.google.com/workspace/guides/create-credentials#service-account).
+
+You can store the download credential files anywhere on your system. The recommended
+location is `~/.google-api-credential.json`.
 
 ## Usage
 
@@ -86,19 +114,165 @@ If the credential is stored elsewhere, pass the credential_source to `SheetsV4.s
 manually. `credential_source` can be a String:
 
 ```Ruby
-sheets_service = SheetsV4.sheets_service(credential_sourvce: File.read('credential.json'))
+sheets_service = SheetsV4.sheets_service(credential_source: File.read('credential.json'))
 ```
 
 an IO object:
 
 ```Ruby
 sheets_service = File.open('credential.json') do |credential_source|
-  SheetsV4.sheets_service(credential_sourvce:)
+  SheetsV4.sheets_service(credential_source:)
 end
 ```
 
 or an already constructed `Google::Auth::*`` object.
 
+### Building a request
+
+To use the Sheets API, you need to construct JSON formatted requests.
+
+These requests can be constructed using two different methods:
+1. constructing requests using `Google::Apis::SheetsV4::*` objects or
+2. constructing requests using hashes
+
+The following two sections show how each method can be used to construct
+a request to update a row of values in a sheet.
+
+For these two examples, values in the `values` array will be written to the
+sheet whose ID is 0. The values will be written one per row starting at cell A1.
+
+```Ruby
+values = %w[one two three four] # 'one' goes in A1, 'two' goes in A2, etc.
+```
+
+The method `SheetsService#batch_update_spreadsheet` will be used to write the values. This
+method takes a `batch_update_spreadsheet_request` object with a `update_cells` request
+that defines the update to perform.
+
+#### Method 1: constructing requests using `Google::Apis::SheetsV4::*` objects
+
+When using this method, keep the Ruby source file containing the SheetsService class
+([google/apis/sheets_v4/service.rb](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/service.rb))
+and the Ruby source file containing the defitions of the request & data classes
+([lib/google/apis/sheets_v4/classes.rb](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/classes.rb))
+open for easy searching. These files will give you all the information you need
+to construct valid requests.
+
+Here is the example constructing requests using `Google::Apis::SheetsV4::*` objects
+
+```Ruby
+def values = %w[one two three four]
+
+def row_data(value)
+  Google::Apis::SheetsV4::RowData.new(
+    values: [
+      Google::Apis::SheetsV4::CellData.new(
+        user_entered_value:
+          Google::Apis::SheetsV4::ExtendedValue.new(string_value: value.to_s)
+      )
+    ]
+  )
+end
+
+def rows
+  values.map { |value| row_data(value) }
+end
+
+def write_values_request
+  fields = 'user_entered_value'
+  start = Google::Apis::SheetsV4::GridCoordinate.new(
+    sheet_id: 0, row_index: 0, column_index: 0
+  )
+  Google::Apis::SheetsV4::Request.new(
+    update_cells: Google::Apis::SheetsV4::UpdateCellsRequest.new(rows:, fields:, start:)
+  )
+end
+
+requests = Google::Apis::SheetsV4::BatchUpdateSpreadsheetRequest.new(requests: [write_values_request])
+
+spreadsheet_id = '18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY'
+SheetsV4.sheets_service.batch_update_spreadsheet(spreadsheet_id, requests)
+```
+
+#### Method 2: constructing requests using hashes
+
+When constructing requests using this method, keep the [Google Sheets Rest API Reference](https://developers.google.com/sheets/api/reference/rest)
+documentation open. In particular, [the Batch Update Requests page](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#cutpasterequest)
+is particularly useful for building spreadsheet batch update requests.
+
+One caveat to keep in mind is that the Rest API documents object properties using
+Camel case BUT the Ruby API requires snake case.
+
+For instance, the Rest API documents the properties for a grid coordinate to be
+"sheetId", "rowIndex", and "columnIndex". However, in the Ruby API, you should
+construct this object using snake case:
+
+```Ruby
+grid_coordinate = { sheet_id: 0, row_index: 0, column_index: 0 }
+```
+
+Here is the example constructing requests using hashes:
+
+```Ruby
+def values = %w[one two three four]
+
+def rows
+  values.map do |value|
+    { values: [{ user_entered_value: { string_value: value } }] }
+  end
+end
+
+def write_values_request
+  fields = 'user_entered_value'
+  start = { sheet_id: 0, row_index: 0, column_index: 0 }
+  { update_cells: { rows:, fields:, start: } }
+end
+
+requests = { requests: [write_values_request] }
+
+spreadsheet_id = '18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY'
+response = SheetsV4.sheets_service.batch_update_spreadsheet(spreadsheet_id, requests)
+```
+
+#### Which method should be used?
+
+Either method will do the same job. I prefer "Method 2: constructing requests using
+hashes" because my code is more concise and easy to read.
+
+While either method can produce a malformed request, "Method 2" is more likely to
+result in malformed requests. Unfortunately, when given a malformed request, the
+Google Sheets API will do one of following depending on the nature of the problem:
+
+1. Raise a `Google::Apis::ClientError` with some additional information
+2. Raise a `Google::Apis::ClientError` with no additional information (this the most
+   common result)
+3. Not return an error with some of the batch requests not having the expected outcome
+
+Luckily, this library provides a way to validate that requests are valid and
+identifies precisely where the request objects do not conform to the API description.
+That is the subject of the next section [Validating requests](#validating-requests).
+
+### Validating requests
+
+The [`SheetsV4.validate_api_object`](https://rubydoc.info/gems/sheets_v4/SheetsV4#validate_api_object-class_method)
+method can be used to validate request objects prior to using them in the Google
+Sheets API.
+
+This method takes a `schema_name` and an `object` to validate. Schema names can be
+listed using [`SheetsV4.api_object_schema_names`](https://rubydoc.info/gems/sheets_v4/SheetsV4#api_object_schema_names-class_method).
+
+This method will either return `true` if `object` conforms to the schema OR it
+will raise a RuntimeError noting where the object structure did not conform to
+the schema.
+
+In the previous examples (see [Building a request](#building-a-request)), the
+following line can be inserted after the `requests =  ...` line to validate the
+request:
+
+```Ruby
+SheetsV4.validate_api_object(schema: 'batch_update_spreadsheet_request', object: requests)
+```
+
 ### Colors
 
 Color objects (with appropriate :red, :green, :blue values) can be retrieved by name
@@ -114,8 +288,8 @@ SheetsV4::Color.black #=> {:red=>0.0, :green=>0.0, :blue=>0.0}
 
 ## 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
+After checking out the repo, run `bin/setup` to install dependencies and then, run
+`rake` to run the tests, static analysis, etc. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To
@@ -124,9 +298,6 @@ release a new version, update the version number in `version.rb`, and then run
 commits and the created tag, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
-## Creating a Google API Service Account
-
-
 ## Contributing
 
 Bug reports and pull requests are welcome on [the main-branch/sheets_v4 GitHub project](https://github.com/main-branch/sheets_v4).

data/examples/set_background_color

@@ -43,10 +43,12 @@ end
 
 def requests = { requests: [write_names, set_background_colors] }
 
-# SheetsV4.validate_api_object(
-#   schema_name: 'BatchUpdateSpreadsheetRequest', object: request,
-#   logger: Logger.new(STDOUT, level: Logger::ERROR)
-# )
+# OPTIONAL: validate the requests against the schema before sending them to the API.
+#
+# While not necessary, it can be helpful to identify errors since the API will return
+# an error if the request is invalid but does not tell you where the problem is.
+#
+SheetsV4.validate_api_object(schema_name: 'batch_update_spreadsheet_request', object: requests)
 
 spreadsheet_id = '18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY'
 SheetsV4.sheets_service.batch_update_spreadsheet(spreadsheet_id, requests)

data/examples/set_background_color2

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'sheets_v4'
+require 'googleauth'
+
+# Example to show using the SheetsV4 module to set the background color of a cell
+#
+# GIVEN the credential file is at ~/.google-api-credential.json
+#   AND the spreadsheet id is 18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY
+#   AND the spreadsheet has a sheet whose id is 0
+# WHEN the script is run
+# THEN the sheet whose id is 0 will have the background color names starting at A2
+#   AND the background color of the cells in column B will be set to the color matching the color name in column A
+
+# Build the requests
+
+def name_rows
+  SheetsV4.color_names.map do |color_name|
+    Google::Apis::SheetsV4::RowData.new(
+      values: [
+        Google::Apis::SheetsV4::CellData.new(
+          user_entered_value: Google::Apis::SheetsV4::ExtendedValue.new(string_value: color_name.to_s)
+        )
+      ]
+    )
+    # { values: [{ user_entered_value: { string_value: color_name.to_s } }] }
+  end
+end
+
+def write_names
+  rows = name_rows
+  fields = 'user_entered_value'
+  start = Google::Apis::SheetsV4::GridCoordinate.new(sheet_id: 0, row_index: 1, column_index: 0)
+  Google::Apis::SheetsV4::Request.new(
+    update_cells: Google::Apis::SheetsV4::UpdateCellsRequest.new(rows:, fields:, start:)
+  )
+end
+
+def background_color_rows
+  SheetsV4.color_names.map { |color_name| SheetsV4.color(color_name) }.map do |color|
+    background_color = Google::Apis::SheetsV4::Color.new(**color)
+    user_entered_format = Google::Apis::SheetsV4::CellFormat.new(background_color:)
+    cell_data = Google::Apis::SheetsV4::CellData.new(user_entered_format:)
+    Google::Apis::SheetsV4::RowData.new(values: [cell_data])
+  end
+end
+
+def set_background_colors
+  rows = background_color_rows
+  fields = 'user_entered_format'
+  start = Google::Apis::SheetsV4::GridCoordinate.new(sheet_id: 0, row_index: 1, column_index: 1)
+  update_cells = Google::Apis::SheetsV4::UpdateCellsRequest.new(rows:, fields:, start:)
+  Google::Apis::SheetsV4::Request.new(update_cells:)
+end
+
+def requests = Google::Apis::SheetsV4::BatchUpdateSpreadsheetRequest.new(requests: [write_names, set_background_colors])
+
+# OPTIONAL: validate the requests against the schema before sending them to the API.
+#
+# While not necessary, it can be helpful to identify errors since the API will return
+# an error if the request is invalid but does not tell you where the problem is.
+#
+SheetsV4.validate_api_object(schema_name: 'batch_update_spreadsheet_request', object: requests.to_h)
+
+spreadsheet_id = '18FAcgotK7nDfLTOTQuGCIjKwxkJMAguhn1OVzpFFgWY'
+SheetsV4.sheets_service.batch_update_spreadsheet(spreadsheet_id, requests)

data/lib/sheets_v4/validate_api_objects/load_schemas.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  module ValidateApiObjects
+    # Load the Google Discovery API description for the Sheets V4 API
+    #
+    # @example
+    #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
+    #   schemas = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call
+    #
+    # @api private
+    #
+    class LoadSchemas
+      # Loads schemas for the Sheets V4 API object from the Google Discovery API
+      #
+      # By default, a nil logger is used. This means that nothing is logged.
+      #
+      # The schemas are only loaded once and cached.
+      #
+      # @example
+      #   schema_loader = SheetsV4::ValidateApiObjects::LoadSchemas.new
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # The logger to use internally for logging errors
+      #
+      # @example
+      #   logger = Logger.new(STDOUT, :level => Logger::INFO)
+      #   validator = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger)
+      #   validator.logger == logger # => true
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      # A hash of schemas keyed by the schema name loaded from the Google Discovery API
+      #
+      # @example
+      #   SheetsV4.api_object_schemas #=> { 'PersonSchema' => { 'type' => 'object', ... } ... }
+      #
+      # @return [Hash<String, Object>] a hash of schemas keyed by schema name
+      #
+      def call
+        self.class.schema_load_semaphore.synchronize { @call ||= load_api_object_schemas }
+      end
+
+      private
+
+      # Validate
+      # A mutex used to synchronize access to the schemas so they are only loaded
+      # once.
+      #
+      @schema_load_semaphore = Thread::Mutex.new
+
+      class << self
+        # A mutex used to synchronize access to the schemas so they are only loaded once
+        #
+        # @return [Thread::Mutex]
+        #
+        # @api private
+        #
+        attr_reader :schema_load_semaphore
+      end
+
+      # Load the schemas from the Google Discovery API
+      #
+      # @return [Hash<String, Object>] a hash of schemas keyed by schema name
+      #
+      # @api private
+      #
+      def load_api_object_schemas
+        source = 'https://sheets.googleapis.com/$discovery/rest?version=v4'
+        http_response = Net::HTTP.get_response(URI.parse(source))
+        raise_error(http_response) if http_response.code != '200'
+
+        data = http_response.body
+        JSON.parse(data)['schemas'].tap { |schemas| post_process_schemas(schemas) }
+      end
+
+      # Log an error and raise a RuntimeError based on the HTTP response code
+      # @param http_response [Net::HTTPResponse] the HTTP response
+      # @return [void]
+      # @raises [RuntimeError]
+      # @api private
+      def raise_error(http_response)
+        message = "HTTP Error '#{http_response.code}' loading schemas from '#{http_response.uri}'"
+        logger.error(message)
+        raise message
+      end
+
+      REF_KEY = '$ref'
+
+      # A visitor for the schema object tree that fixes up the tree as it goes
+      # @return [void]
+      # @api private
+      def schema_visitor(path:, object:)
+        return unless object.is_a? Hash
+
+        convert_schema_names_to_snake_case(path, object)
+        convert_schema_ids_to_snake_case(path, object)
+        add_unevaluated_properties(path, object)
+        convert_property_names_to_snake_case(path, object)
+        convert_ref_values_to_snake_case(path, object)
+      end
+
+      # Convert schema names to snake case
+      # @return [void]
+      # @api private
+      def convert_schema_names_to_snake_case(path, object)
+        object.transform_keys!(&:underscore) if path.empty?
+      end
+
+      # Convert schema IDs to snake case
+      # @return [void]
+      # @api private
+      def convert_schema_ids_to_snake_case(path, object)
+        object['id'] = object['id'].underscore if object.key?('id') && path.size == 1
+      end
+
+      # Add 'unevaluatedProperties: false' to all schemas
+      # @return [void]
+      # @api private
+      def add_unevaluated_properties(path, object)
+        object['unevaluatedProperties'] = false if path.size == 1
+      end
+
+      # Convert object property names to snake case
+      # @return [void]
+      # @api private
+      def convert_property_names_to_snake_case(path, object)
+        object.transform_keys!(&:underscore) if path[-1] == 'properties'
+      end
+
+      # Convert reference values to snake case
+      # @return [void]
+      # @api private
+      def convert_ref_values_to_snake_case(_path, object)
+        object[REF_KEY] = object[REF_KEY].underscore if object.key?(REF_KEY)
+      end
+
+      # Traverse the schema object tree and apply the schema visitor to each node
+      # @return [void]
+      # @api private
+      def post_process_schemas(schemas)
+        SheetsV4::ValidateApiObjects::TraverseObjectTree.call(
+          object: schemas, visitor: ->(path:, object:) { schema_visitor(path:, object:) }
+        )
+      end
+    end
+  end
+end

data/lib/sheets_v4/validate_api_objects/resolve_schema_ref.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  module ValidateApiObjects
+    # Resolve a JSON schema reference to a Google Sheets API schema
+    #
+    # This class uses the Google Discovery API to get the schemas. Any schema reference
+    # in the form `{ "$ref": "schema_name" }` will be resolved by looking up the schema
+    # name in the Google Discovery API and returning the schema object (as a Hash).
+    #
+    # This means that `{ "$ref": "cell_data" }` is resolved by returning
+    # `SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call['cell_data']`.
+    #
+    # An RuntimeError is raised if `SheetsV4::ValidateApiObjects::LoadSchemas.new.call`
+    # does not have a key matching the schema name.
+    #
+    # @example
+    #   logger = Logger.new(STDOUT, level: Logger::INFO)
+    #   ref_resolver = SheetsV4::ValidateApiObjects::ResolveSchemaRef.new(logger:)
+    #   people_schema = { 'type' => 'array', 'items' => { '$ref' => 'person' } }
+    #   json_validator = JSONSchemer.schema(people_schema, ref_resolver:)
+    #   people_json = [{ 'name' => { 'first' => 'John', 'last' => 'Doe' } }]
+    #
+    #   # Trying to validate people_json using json_validator as follows:
+    #
+    #   json_validator.validate(people_json)
+    #
+    #   # will try to load the referenced schema for 'person'. json_validator will
+    #   # do this by calling `ref_resolver.call(URI.parse('json-schemer://schema/person'))`
+    #
+    # @api private
+    #
+    class ResolveSchemaRef
+      # Create a new schema resolver
+      #
+      # @param logger [Logger] the logger to use
+      #
+      # @api private
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # The logger to use internally
+      #
+      # Currently, only debug messages are logged.
+      #
+      # @return [Logger]
+      #
+      # @api private
+      #
+      attr_reader :logger
+
+      # Resolve a JSON schema reference
+      #
+      # @param ref [URI] the reference to resolve usually in the form "json-schemer://schema/{name}"
+      #
+      # @return [Hash] the schema object as a hash
+      #
+      # @api private
+      #
+      def call(ref)
+        schema_name = ref.path[1..]
+        logger.debug { "Reading schema #{schema_name}" }
+        schemas = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call
+        schemas[schema_name].tap do |schema_object|
+          raise "Schema for #{ref} not found" unless schema_object
+        end
+      end
+    end
+  end
+end

data/lib/sheets_v4/validate_api_objects/traverse_object_tree.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  module ValidateApiObjects
+    # Visit all objects in arbitrarily nested object tree of hashes and/or arrays
+    #
+    # @api public
+    #
+    class TraverseObjectTree
+      # Visit all objects in arbitrarily nested object tree of hashes and/or arrays
+      #
+      # For each object, the visitor is called with the path to the object and the object
+      # itself.
+      #
+      # In the examples below assume the elided code is the following:
+      #
+      # ```Ruby
+      # visitor = -> (path:, object:) { puts "path: #{path}, object: #{obj}" }
+      # SheetsV4::ValidateApiObjects::TraverseObjectTree.call(object:, visitor:)
+      # ```
+      #
+      # @example Given a simple object (not very exciting)
+      #   object = 1
+      #   ...
+      #   #=> path: [], object: 1
+      #
+      # @example Given an array
+      #   object = [1, 2, 3]
+      #   ...
+      #   #=> path: [], object: [1, 2, 3]
+      #   #=> path: [0], object: 1
+      #   #=> path: [1], object: 2
+      #   #=> path: [2], object: 3
+      #
+      # @example Given a hash
+      #   object = { name: 'James', age: 42 }
+      #   ...
+      #   #=> path: [], object: { name: 'James', age: 42 }
+      #   #=> path: [:name], object: James
+      #   #=> path: [:age], object: 42
+      #
+      # @example Given an array of hashes
+      #   object = [{ name: 'James', age: 42 }, { name: 'Jane', age: 43 }]
+      #   ...
+      #   #=> path: [], object: [{ name: 'James', age: 42 }, { name: 'Jane', age: 43 }]
+      #   #=> path: [0], object: { name: 'James', age: 42 }
+      #   #=> path: [0, :name], object: James
+      #   #=> path: [0, :age], object: 42
+      #   #=> path: [1], object: { name: 'Jane', age: 43 }
+      #   #=> path: [1, :name], object: Jane
+      #   #=> path: [1, :age], object: 43
+      #
+      # @example Given a hash of hashes
+      #   object = { person1: { name: 'James', age: 42 }, person2: { name: 'Jane', age: 43 } }
+      #   ...
+      #   #=> path: [], object: { person1: { name: 'James', age: 42 }, person2: { name: 'Jane', age: 43 } }
+      #   #=> path: [:person1], object: { name: 'James', age: 42 }
+      #   #=> path: [:person1, :name], object: James
+      #   #=> path: [:person1, :age], object: 42
+      #   #=> path: [:person2], object: { name: 'Jane', age: 43 }
+      #   #=> path: [:person2, :name], object: Jane
+      #   #=> path: [:person2, :age], object: 43
+      #
+      # @param path [Array] the path to the object
+      # @param object [Object] the object to visit
+      # @param visitor [#call] the visitor to call for each object
+      #
+      # @return [void]
+      #
+      # @api public
+      #
+      def self.call(object:, visitor:, path: [])
+        visitor&.call(path:, object:)
+        if object.is_a? Hash
+          object.each { |k, obj| call(path: (path + [k]), object: obj, visitor:) }
+        elsif object.is_a? Array
+          object.each_with_index { |obj, k| call(path: (path + [k]), object: obj, visitor:) }
+        end
+      end
+    end
+  end
+end

data/lib/sheets_v4/validate_api_objects/validate.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+require 'json_schemer'
+
+module SheetsV4
+  module ValidateApiObjects
+    # Validate objects against a Google Sheets API request object schema
+    #
+    # @api public
+    #
+    class Validate
+      # Create a new validator
+      #
+      # By default, a nil logger is used. This means that no messages are logged.
+      #
+      # @example
+      #   validator = SheetsV4::ValidateApiObjects::Validator.new
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # The logger to use internally
+      #
+      # Validation errors are logged at the error level. Other messages are logged
+      # at the debug level.
+      #
+      # @example
+      #   logger = Logger.new(STDOUT, :level => Logger::INFO)
+      #   validator = SheetsV4::ValidateApiObjects::Validator.new(logger)
+      #   validator.logger == logger # => true
+      #   validator.logger.debug { "Debug message" }
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      # Validate the object using the JSON schema named schema_name
+      #
+      # @example
+      #   schema_name = 'batch_update_spreadsheet_request'
+      #   object = { 'requests' => [] }
+      #   validator = SheetsV4::ValidateApiObjects::Validator.new
+      #   validator.call(schema_name:, object:)
+      #
+      # @param schema_name [String] the name of the schema to validate against
+      # @param object [Object] the object to validate
+      #
+      # @raise [RuntimeError] if the object does not conform to the schema
+      #
+      # @return [void]
+      #
+      def call(schema_name:, object:)
+        logger.debug { "Validating #{object} against #{schema_name}" }
+
+        schema = { '$ref' => schema_name }
+        schemer = JSONSchemer.schema(schema, ref_resolver:)
+        errors = schemer.validate(object)
+        raise_error!(schema_name, object, errors) if errors.any?
+
+        logger.debug { "Object #{object} conforms to #{schema_name}" }
+      end
+
+      private
+
+      # The resolver to use to resolve JSON schema references
+      # @return [ResolveSchemaRef]
+      # @api private
+      def ref_resolver = @ref_resolver ||= SheetsV4::ValidateApiObjects::ResolveSchemaRef.new(logger:)
+
+      # Raise an error when the object does not conform to the schema
+      # @return [void]
+      # @raise [RuntimeError]
+      # @api private
+      def raise_error!(schema_name, object, errors)
+        error = errors.first['error']
+        error_message = "Object #{object} does not conform to #{schema_name}: #{error}"
+        logger.error(error_message)
+        raise error_message
+      end
+    end
+  end
+end

data/lib/sheets_v4/validate_api_objects.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  # Validate API Objects against the Google Discovery API
+  #
+  # @example
+  #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
+  #   schema_name = 'batch_update_spreadsheet_request'
+  #   object = { 'requests' => [] }
+  #   SheetsV4::ValidateApiObjects::Validator.new(logger:).call(schema_name:, object:)
+  #
+  # @api public
+  #
+  module ValidateApiObjects; end
+end
+
+require_relative 'validate_api_objects/load_schemas'
+require_relative 'validate_api_objects/resolve_schema_ref'
+require_relative 'validate_api_objects/traverse_object_tree'
+require_relative 'validate_api_objects/validate'

data/lib/sheets_v4/version.rb

@@ -2,5 +2,5 @@
 
 module SheetsV4
   # The version of this gem
-  VERSION = '0.4.0'
+  VERSION = '0.6.0'
 end

data/lib/sheets_v4.rb

@@ -3,7 +3,7 @@
 require_relative 'sheets_v4/version'
 require_relative 'sheets_v4/color'
 require_relative 'sheets_v4/credential_creator'
-require_relative 'sheets_v4/validate_api_object'
+require_relative 'sheets_v4/validate_api_objects'
 
 require 'google/apis/sheets_v4'
 require 'json'
@@ -19,12 +19,16 @@ module SheetsV4
   #
   # Simplifies creating and configuring a the credential.
   #
-  # @example using the crednetial in `~/.google-api-credential`
+  # @example using the credential in `~/.google-api-credential`
   #   SheetsV4.sheets_service
   #
   # @example using a credential passed in as a string
-  #   credential_source = File.read(File.join(Dir.home, '.credential'))
-  #   SheetsV4.sheets_service(credential_source:
+  #   credential_source = File.read(File.expand_path('~/.google-api-credential.json'))
+  #   SheetsV4.sheets_service(credential_source:)
+  #
+  # @example using a credential passed in as an IO
+  #   credential_source = File.open(File.expand_path('~/.google-api-credential.json'))
+  #   SheetsV4.sheets_service(credential_source:)
   #
   # @param credential_source [nil, String, IO, Google::Auth::*] may
   #   be either an already constructed credential, the credential read into a String or
@@ -50,10 +54,10 @@ module SheetsV4
   # Validate the object using the named JSON schema
   #
   # The JSON schemas are loaded from the Google Disocvery API. The schemas names are
-  # returned by `SheetsV4.api_object_schemas.keys`.
+  # returned by `SheetsV4.api_object_schema_names`.
   #
   # @example
-  #   schema_name = 'BatchUpdateSpreadsheetRequest'
+  #   schema_name = 'batch_update_spreadsheet_request'
   #   object = { 'requests' => [] }
   #   SheetsV4.validate_api_object(schema_name:, object:)
   #
@@ -66,7 +70,18 @@ module SheetsV4
   # @return [void]
   #
   def self.validate_api_object(schema_name:, object:, logger: Logger.new(nil))
-    ValidateApiObject.new(logger).call(schema_name, object)
+    SheetsV4::ValidateApiObjects::Validate.new(logger:).call(schema_name:, object:)
+  end
+
+  # List the names of the schemas available to use in the Google Sheets API
+  #
+  # @example List the name of the schemas available
+  #   SheetsV4.api_object_schema_names #=> ["add_banding_request", "add_banding_response", ...]
+  #
+  # @return [Array<String>] the names of the schemas available
+  #
+  def self.api_object_schema_names(logger: Logger.new(nil))
+    SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call.keys.sort
   end
 
   # Given the name of the color, return a Google Sheets API color object

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sheets_v4
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-30 00:00:00.000000000 Z
+date: 2023-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -258,10 +258,15 @@ files:
 - Rakefile
 - examples/README.md
 - examples/set_background_color
+- examples/set_background_color2
 - lib/sheets_v4.rb
 - lib/sheets_v4/color.rb
 - lib/sheets_v4/credential_creator.rb
-- lib/sheets_v4/validate_api_object.rb
+- lib/sheets_v4/validate_api_objects.rb
+- lib/sheets_v4/validate_api_objects/load_schemas.rb
+- lib/sheets_v4/validate_api_objects/resolve_schema_ref.rb
+- lib/sheets_v4/validate_api_objects/traverse_object_tree.rb
+- lib/sheets_v4/validate_api_objects/validate.rb
 - lib/sheets_v4/version.rb
 homepage: https://github.com/main-branch/sheets_v4
 licenses:

data/lib/sheets_v4/validate_api_object.rb

@@ -1,174 +0,0 @@
-# frozen_string_literal: true
-
-require 'json_schemer'
-
-module SheetsV4
-  # Validate objects against a Google Sheets API request object schema
-  #
-  # @api public
-  #
-  class ValidateApiObject
-    # Create a new validator
-    #
-    # By default, a nil logger is used. This means that no messages are logged.
-    #
-    # @example
-    #   logger = Logger.new(STDOUT, :level => Logger::INFO)
-    #   validator = SheetsV4::ValidateApiObject.new(logger)
-    #
-    # @param logger [Logger] the logger to use
-    #
-    def initialize(logger = Logger.new(nil))
-      @logger = logger
-    end
-
-    # The logger to use internally
-    #
-    # Validation errors are logged at the error level. Other messages are logged
-    # at the debug level.
-    #
-    # @example
-    #   logger = Logger.new(STDOUT, :level => Logger::INFO)
-    #   validator = SheetsV4::ValidateApiObject.new(logger)
-    #   validator.logger == logger # => true
-    #   validator.logger.debug { "Debug message" }
-    #
-    # @return [Logger]
-    #
-    attr_reader :logger
-
-    # Validate the object using the JSON schema named schema_name
-    #
-    # @example
-    #   schema_name = 'BatchUpdateSpreadsheetRequest'
-    #   object = { 'requests' => [] }
-    #   validator = SheetsV4::ValidateApiObject.new
-    #   validator.call(schema_name, object)
-    #
-    # @param schema_name [String] the name of the schema to validate against
-    # @param object [Object] the object to validate
-    #
-    # @raise [RuntimeError] if the object does not conform to the schema
-    #
-    # @return [void]
-    #
-    def call(schema_name, object)
-      logger.debug { "Validating #{object} against #{schema_name}" }
-
-      schema = { '$ref' => schema_name }
-      schemer = JSONSchemer.schema(schema, ref_resolver:)
-      errors = schemer.validate(object)
-      raise_error!(schema_name, object, errors) if errors.any?
-
-      logger.debug { "Object #{object} conforms to #{schema_name}" }
-    end
-
-    private
-
-    # The resolver to use to resolve JSON schema references
-    # @return [SchemaRefResolver]
-    # @api private
-    def ref_resolver = @ref_resolver ||= SchemaRefResolver.new(logger)
-
-    # Raise an error when the object does not conform to the schema
-    # @return [void]
-    # @raise [RuntimeError]
-    # @api private
-    def raise_error!(schema_name, object, errors)
-      error = errors.first['error']
-      error_message = "Object #{object} does not conform to #{schema_name}: #{error}"
-      logger.error(error_message)
-      raise error_message
-    end
-  end
-
-  # Resolve JSON schema references to Google Sheets API schemas
-  #
-  # Uses the Google Discovery API to get the schemas. This is an implementation
-  # detail used to interact with JSONSchemer.
-  #
-  # @api private
-  #
-  class SchemaRefResolver
-    # Create a new schema resolver
-    #
-    # @param logger [Logger] the logger to use
-    #
-    # @api private
-    #
-    def initialize(logger)
-      @logger = logger
-    end
-
-    # The logger to use internally
-    #
-    # Currently, only info messages are logged.
-    #
-    # @return [Logger]
-    #
-    # @api private
-    #
-    attr_reader :logger
-
-    # Resolve a JSON schema reference
-    #
-    # @param ref [String] the reference to resolve usually in the form "#/definitions/schema_name"
-    #
-    # @return [Hash] the schema object as a hash
-    #
-    # @api private
-    #
-    def call(ref)
-      schema_name = ref.path[1..]
-      logger.debug { "Reading schema #{schema_name}" }
-      schema_object = self.class.api_object_schemas[schema_name]
-      raise "Schema for #{ref} not found" unless schema_object
-
-      schema_object.to_h.tap do |schema|
-        schema['unevaluatedProperties'] = false
-      end
-    end
-
-    # A hash of schemas keyed by the schema name loaded from the Google Discovery API
-    #
-    # @example
-    #   SheetsV4.api_object_schemas #=> { 'PersonSchema' => { 'type' => 'object', ... } ... }
-    #
-    # @return [Hash<String, Object>] a hash of schemas keyed by schema name
-    #
-    def self.api_object_schemas
-      schema_load_semaphore.synchronize { @api_object_schemas ||= load_api_object_schemas }
-    end
-
-    # Validate
-    # A mutex used to synchronize access to the schemas so they are only loaded
-    # once.
-    #
-    @schema_load_semaphore = Thread::Mutex.new
-
-    class << self
-      # A mutex used to synchronize access to the schemas so they are only loaded once
-      #
-      # @return [Thread::Mutex]
-      #
-      # @api private
-      #
-      attr_reader :schema_load_semaphore
-    end
-
-    # Load the schemas from the Google Discovery API
-    #
-    # @return [Hash<String, Object>] a hash of schemas keyed by schema name
-    #
-    # @api private
-    #
-    def self.load_api_object_schemas
-      source = 'https://sheets.googleapis.com/$discovery/rest?version=v4'
-      resp = Net::HTTP.get_response(URI.parse(source))
-      data = resp.body
-      JSON.parse(data)['schemas'].tap do |schemas|
-        schemas.each { |_name, schema| schema['unevaluatedProperties'] = false }
-      end
-    end
-  end
-end