sheets_db 0.10.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 142c393d8b757f2b1f97ad8f2f809220380f9da7950590939e3801838c23a013
-  data.tar.gz: 47cafcb65c5e2aa3dda6e30f99d791ad6af633add8b89d76fa22fba94732d9a4
+  metadata.gz: 8186e2c37fc147e8bcc4fed8c4bf288b05dde2466c9145e24882d7e1c41d3d35
+  data.tar.gz: cdaf52978086b08fed7cd9635aed44ae2f06bfb756058f1eb4d4fc0bf73e8945
 SHA512:
-  metadata.gz: b7ebc9d05766af291454fe522ca8855c4bfd222e011cfb59e99b423245a2c7c8c242c63ab351d601c51b85594435e3a57855f908ddcb3287f830a3b97442b11f
-  data.tar.gz: d85572aafbbbd0d84a9cdfbbd6a0f401033087d962a00c713184b8bedf4edcb49b3781b85c75a813f844c7a71efdaf534bf8964b4ba53ce755b1a7422fe7771b
+  metadata.gz: 89fd0245435dcfe13010330ca1220bc1d1ec1082333583021cb65f1d74857f6886eebf4325d7f1107ccdc3a406eb58877c914ef3bbdab8b9c4f1e98ffedb7e70
+  data.tar.gz: 2575c45b0f15e24cdbe8296d79a0429eb8120a41414cf112328106b650c70142df3312de2e1d86ffe63ae7c65e32f839bf413ee94c3ea647deae2d2eb692d77a

data/.ruby-version

@@ -1 +1 @@
-2.6.
+3.0.

data/documentation/example_models/pet.rb

@@ -1,7 +1,7 @@
 class Pet < SheetsDB::Worksheet::Row
   attribute :id
   attribute :first_name, transform: ->(first_name) { first_name.upcase }
-  attribute :favorite_colors, multiple: true
+  attribute :favorite_colors, aliases: [:favorite_colours], multiple: true
 
   belongs_to_one :parent, from_collection: :users, foreign_key: :pet_ids
 end

data/documentation/usage.md

@@ -2,7 +2,7 @@
 
 ## Usage
 
-**NOTE**: Currently, SheetsDB only supports reading and updating entities within Google Drive and Sheets; adding new entities or deleting existing ones is not available yet.  Also, updating is restricted to worksheet rows, so folders and spreadsheets are not yet renamable using SheetsDB.
+**NOTE**: Currently, SheetsDB only supports reading and updating entities within Google Drive and Sheets; adding new entities or deleting existing ones is not available yet. Also, updating is restricted to worksheet rows, so folders and spreadsheets are not yet renamable using SheetsDB.
 
 ### The Data Model
 
@@ -10,23 +10,23 @@ For the sake of documentation, we'll set up an example data model that looks lik
 
 ![](images/example_erd.png)
 
-SheetsDB works with several layers of the hierarchy in Google Sheets and Drive (within a worksheet, across worksheets in a Sheet, and across folders in Drive).  We'll briefly go over each of these, and then later we'll dive more deeply.
+SheetsDB works with several layers of the hierarchy in Google Sheets and Drive (within a worksheet, across worksheets in a Sheet, and across folders in Drive). We'll briefly go over each of these, and then later we'll dive more deeply.
 
 #### Worksheets
 
-Worksheets are the best analog we have to database tables - they contain rows, and we can use one of the rows as a header to establish columns.  In SheetsDB, a worksheet is the only way we can represent arbitrary tabular data (outside of relationships that map directly to the folder and file structure in Google Drive).  Therefore, for the example above, we'll need to use worksheets to describe the `Task`, `User`, and `Pet` models.
+Worksheets are the best analog we have to database tables - they contain rows, and we can use one of the rows as a header to establish columns. In SheetsDB, a worksheet is the only way we can represent arbitrary tabular data (outside of relationships that map directly to the folder and file structure in Google Drive). Therefore, for the example above, we'll need to use worksheets to describe the `Task`, `User`, and `Pet` models.
 
 #### Spreadsheets
 
-All worksheets live in a spreadsheet, and there is no way to access a worksheet or its rows outside of the spreadsheet context.  Therefore, there will always be a single parent relationship from the worksheet-based models to a spreadsheet-based model, in this case `Project`.  Note that we can't persist any arbitrary metadata at the project level in this example - if we needed to, `Project` would need to become a worksheet-based model.  Within the spreadsheet, worksheets can contain rows having relationships to rows in other worksheets.
+All worksheets live in a spreadsheet, and there is no way to access a worksheet or its rows outside of the spreadsheet context. Therefore, there will always be a single parent relationship from the worksheet-based models to a spreadsheet-based model, in this case `Project`. Note that we can't persist any arbitrary metadata at the project level in this example - if we needed to, `Project` would need to become a worksheet-based model. Within the spreadsheet, worksheets can contain rows having relationships to rows in other worksheets.
 
 #### Folders
 
-Folders can contain spreadsheets, other folders, or both (obviously Drive folders can also contain other types of files, but SheetsDB ignores these).  They inherently have a zero-to-many relationship with subfolders or any number of spreadsheets, and also (unless they are root folders) can have a one-to-many relationship to parent folders.  Therefore, `Organization` and `Team` will both be folder-based models.
+Folders can contain spreadsheets, other folders, or both (obviously Drive folders can also contain other types of files, but SheetsDB ignores these). They inherently have a zero-to-many relationship with subfolders or any number of spreadsheets, and also (unless they are root folders) can have a one-to-many relationship to parent folders. Therefore, `Organization` and `Team` will both be folder-based models.
 
-Note that subfolders within a folder-based model must all be the same type - there is no support for different kinds of subfolder relationships from a single folder type.  For example, in the data model we're working with, we couldn't have some subfolders of an `Organization` folder be `Team` folders while others were "`Building`" folders.  The same goes for spreadsheets within a folder-based model - only one spreadsheet type relationship is possible.
+Note that subfolders within a folder-based model must all be the same type - there is no support for different kinds of subfolder relationships from a single folder type. For example, in the data model we're working with, we couldn't have some subfolders of an `Organization` folder be `Team` folders while others were "`Building`" folders. The same goes for spreadsheets within a folder-based model - only one spreadsheet type relationship is possible.
 
-You *can*, however, have a single type of subfolder relationship and also a single type of spreadsheet relationship.  In the example above, that would mean a `Team` folder could have many spreadsheets, which would all have to be set up as `Project` spreadsheets; but also many subfolders, which would all have to be set up as the same kind of folder-based model.
+You _can_, however, have a single type of subfolder relationship and also a single type of spreadsheet relationship. In the example above, that would mean a `Team` folder could have many spreadsheets, which would all have to be set up as `Project` spreadsheets; but also many subfolders, which would all have to be set up as the same kind of folder-based model.
 
 ### Setting Up the Structure in Google Drive
 
@@ -34,21 +34,21 @@ To create the structures in Google Drive to represent our example data model, we
 
 #### Folders
 
-First, go into your Google Drive account and create a new folder that will represent the top of our hierarchy.  It doesn't matter where you create this folder, since we'll reference it directly by its id within Google Drive; it can be at the root, or deep within nested folders.  Let's call this folder "Organization A" (though the folder name is meaningless); we'll map this to an `Organization` instance in SheetsDB.
+First, go into your Google Drive account and create a new folder that will represent the top of our hierarchy. It doesn't matter where you create this folder, since we'll reference it directly by its id within Google Drive; it can be at the root, or deep within nested folders. Let's call this folder "Organization A" (though the folder name is meaningless); we'll map this to an `Organization` instance in SheetsDB.
 
-Since our data model specifies that an `Organization` has zero-to-many `Team`s, and `Team` is a folder-based model, all subfolders in our new folder will represent teams.  Navigate into the "Organization A" folder and create two new folders: "Team Alpha" and "Team Bravo".  We're creating two just to demonstrate the subfolder relationship, but we'll work only in "Team Alpha" for now.
+Since our data model specifies that an `Organization` has zero-to-many `Team`s, and `Team` is a folder-based model, all subfolders in our new folder will represent teams. Navigate into the "Organization A" folder and create two new folders: "Team Alpha" and "Team Bravo". We're creating two just to demonstrate the subfolder relationship, but we'll work only in "Team Alpha" for now.
 
 #### Spreadsheets
 
-Navigate into the "Team Alpha" folder.  This folder represents a `Team` in our data model, and `Team`s have many `Project`s.  A `Project` is a spreadsheet-based model, so let's create a new Google Sheets spreadsheet in this folder.  Name your new empty spreadsheet "Test Project 1".  Later, when you want to create a new `Project`, you'll go back into one of your `Team` folders and create a new spreadsheet there; for now, we'll just use a single `Project` spreadsheet.
+Navigate into the "Team Alpha" folder. This folder represents a `Team` in our data model, and `Team`s have many `Project`s. A `Project` is a spreadsheet-based model, so let's create a new Google Sheets spreadsheet in this folder. Name your new empty spreadsheet "Test Project 1". Later, when you want to create a new `Project`, you'll go back into one of your `Team` folders and create a new spreadsheet there; for now, we'll just use a single `Project` spreadsheet.
 
 #### Worksheets
 
-Now we get to the fun part - representing tabular data and relationships between worksheets.  In our data model, a `Project` has three child relationships - `Task`s, `User`s, and `Pet`s.  Therefore, let's create three worksheets.  What you name these worksheets is flexible and doesn't have to be the same as the relationship name, but obviously it'll be less confusing to map them semantically.  So let's call the three worksheets "Tasks", "Users", and "Pets".
+Now we get to the fun part - representing tabular data and relationships between worksheets. In our data model, a `Project` has three child relationships - `Task`s, `User`s, and `Pet`s. Therefore, let's create three worksheets. What you name these worksheets is flexible and doesn't have to be the same as the relationship name, but obviously it'll be less confusing to map them semantically. So let's call the three worksheets "Tasks", "Users", and "Pets".
 
-Within the "Tasks" worksheet, set up a header row with each cell being one of the `Task` column names from our data model (`id`, `name`, `creator_id`, `assignee_id`, and `finished_at`).  Repeat this for the "Users" worksheet with `User` columns (`id`, `first_name`, `last_name`, and `pet_ids`), and the "Pets" worksheet with `Pet` columns (`id`, `first_name`, and `favorite_colors`).
+Within the "Tasks" worksheet, set up a header row with each cell being one of the `Task` column names from our data model (`id`, `name`, `creator_id`, `assignee_id`, and `finished_at`). Repeat this for the "Users" worksheet with `User` columns (`id`, `first_name`, `last_name`, and `pet_ids`), and the "Pets" worksheet with `Pet` columns (`id`, `first_name`, and `favorite_colors`).
 
-Now let's fill in some dummy data.  Make sure any entries in association columns (like `creator_id` and `pet_ids`) reference the `id` column in their respective child worksheets.  For multiple value columns (`pet_ids` and `favorite_colors`), use a comma-separated list of values (__currently, values that contain commas themselves aren't supported - we'll add escaping in a later version__).
+Now let's fill in some dummy data. Make sure any entries in association columns (like `creator_id` and `pet_ids`) reference the `id` column in their respective child worksheets. For multiple value columns (`pet_ids` and `favorite_colors`), use a comma-separated list of values (**currently, values that contain commas themselves aren't supported - we'll add escaping in a later version**).
 
 When you're done, your spreadsheet should look similar to the following:
 
@@ -56,17 +56,17 @@ When you're done, your spreadsheet should look similar to the following:
 
 **A few things to note:**
 
-1. Empty cells will result in null values.  Blank string values are currently not supported in any way.
-2. The `finished_at` column actually represents a date & time in Google Sheets and not an arbitrary string field; you can confirm this by highlighting one of those cells and seeing the value in the formula bar.  If you want to use a column as a Ruby `DateTime` in SheetsDB, make sure the actual data is formatted as `%m/%d/%Y %H:%M:%S` (single digit months and days are acceptable).
-3. In comma-separated lists of values, spaces after commas are ignored, so "1, 2,  3" works just as well as "1,2,3".
+1. Empty cells will result in null values. Blank string values are currently not supported in any way.
+2. The `finished_at` column actually represents a date & time in Google Sheets and not an arbitrary string field; you can confirm this by highlighting one of those cells and seeing the value in the formula bar. If you want to use a column as a Ruby `DateTime` in SheetsDB, make sure the actual data is formatted as `%m/%d/%Y %H:%M:%S` (single digit months and days are acceptable).
+3. In comma-separated lists of values, spaces after commas are ignored, so "1, 2, 3" works just as well as "1,2,3".
 
 ### Accessing the Data
 
-Now that we're done entering all our data, let's set up our models in Ruby so we can start reading and updating this data.  All the example model classes below are also in the [examples](example_models) directory.
+Now that we're done entering all our data, let's set up our models in Ruby so we can start reading and updating this data. All the example model classes below are also in the [examples](example_models) directory.
 
 #### Creating a Session
 
-To access your files in Google Drive, you need to start by creating a SheetsDB::Session.  This is done by wrapping a GoogleDrive::Session.  There are several ways to do this, all described in the `google_drive` gem's documentation [here](https://github.com/gimite/google-drive-ruby/blob/master/doc/authorization.md).  Note that the GoogleDrive gem is already available to you if you're using SheetsDB, as it is a loaded dependency.
+To access your files in Google Drive, you need to start by creating a SheetsDB::Session. This is done by wrapping a GoogleDrive::Session. There are several ways to do this, all described in the `google_drive` gem's documentation [here](https://github.com/gimite/google-drive-ruby/blob/master/doc/authorization.md). Note that the GoogleDrive gem is already available to you if you're using SheetsDB, as it is a loaded dependency.
 
 Once you have a GoogleDrive::Session, create a SheetsDB::Session using it:
 
@@ -95,7 +95,7 @@ Great, now we have a session and we can fetch resources from Google Drive!
 
 #### Folder Models
 
-Model classes representing folders should inherit from `SheetsDB::Collection`, and can have relationships to subfolders using the `has_many` class method.  Here is our `Organization` class:
+Model classes representing folders should inherit from `SheetsDB::Collection`, and can have relationships to subfolders using the `has_many` class method. Here is our `Organization` class:
 
 ```ruby
 class Organization < SheetsDB::Collection
@@ -103,7 +103,7 @@ class Organization < SheetsDB::Collection
 end
 ```
 
-Our `Team` class is similar, but specifies that `Project` children are spreadsheets (instead of subfolders), and also uses the `belongs_to_many` method to define the parent relationship to `Organization`.  Note that there is no way to restrict a folder or file's parent structure to allow only one parent; therefore, there is no `belongs_to_one` method.  If you know your structure will only ever have a single parent for a given resource, you could set up a method to access the first element of this collection, as we've done in the `Team` class:
+Our `Team` class is similar, but specifies that `Project` children are spreadsheets (instead of subfolders), and also uses the `belongs_to_many` method to define the parent relationship to `Organization`. Note that there is no way to restrict a folder or file's parent structure to allow only one parent; therefore, there is no `belongs_to_one` method. If you know your structure will only ever have a single parent for a given resource, you could set up a method to access the first element of this collection, as we've done in the `Team` class:
 
 ```ruby
 class Team < SheetsDB::Collection
@@ -118,7 +118,7 @@ end
 
 #### Spreadsheet Models
 
-The `Project` model uses a different base class (`SheetsDB::Spreadsheet`).  From this type of model class, the `has_many` method references worksheets instead of subfolders or spreadsheets, so it has a different signature:
+The `Project` model uses a different base class (`SheetsDB::Spreadsheet`). From this type of model class, the `has_many` method references worksheets instead of subfolders or spreadsheets, so it has a different signature:
 
 ```ruby
 class Project < SheetsDB::Spreadsheet
@@ -131,7 +131,7 @@ end
 
 #### Worksheet Row Models
 
-Finally, we get to the worksheets.  We're not trying to model the worksheets themselves - those are analogous to the schema of a table.  What we're modeling is rows within the worksheets, so each of these models will inherit from `SheetsDB::Worksheet::Row`.  We'll need to specify what the attributes are, to set up accessor methods and to specify their types; we'll also be setting up relationships to other worksheet models.  Here are the three models:
+Finally, we get to the worksheets. We're not trying to model the worksheets themselves - those are analogous to the schema of a table. What we're modeling is rows within the worksheets, so each of these models will inherit from `SheetsDB::Worksheet::Row`. We'll need to specify what the attributes are, to set up accessor methods and to specify their types; we'll also be setting up relationships to other worksheet models. Here are the three models:
 
 ```ruby
 class Task < SheetsDB::Worksheet::Row
@@ -159,7 +159,7 @@ end
 class Pet < SheetsDB::Worksheet::Row
   attribute :id
   attribute :first_name, transform: ->(first_name) { first_name.upcase }
-  attribute :favorite_colors, multiple: true
+  attribute :favorite_colors, aliases: [:favorite_colours], multiple: true
 
   belongs_to_one :parent, from_collection: :users, foreign_key: :pet_ids
 end
@@ -167,20 +167,22 @@ end
 
 ##### The Attribute Method
 
-The only required argument to the `attribute` class method is the name of the column itself.  All other options are optional:
+The only required argument to the `attribute` class method is the name of the column itself. All other options are optional:
 
-`type`: The `attribute` method currently supports five types: `Integer`, `Float`, `DateTime`, `Boolean` and the default `String`.  Any other value given to the `type` option will be ignored and the default will be used.  (Note that the `Boolean` type must be specified as a string or symbol (`type: :Boolean`) since there is no actual `Boolean` class in Ruby.)
+`type`: The `attribute` method currently supports five types: `Integer`, `Float`, `DateTime`, `Boolean` and the default `String`. Any other value given to the `type` option will be ignored and the default will be used. (Note that the `Boolean` type must be specified as a string or symbol (`type: :Boolean`) since there is no actual `Boolean` class in Ruby.)
 
-`multiple`: This option defaults to false.  If true, it tells SheetsDB to parse the value as a comma-separated list of values, and return an array by splitting on the comma (if no comma is found, it will return a single element array).
+`multiple`: This option defaults to false. If true, it tells SheetsDB to parse the value as a comma-separated list of values, and return an array by splitting on the comma (if no comma is found, it will return a single element array).
 
-`transform`: If you supply a Proc (or lambda) to the `transform` option, reading this column from the spreadsheet will cause it to first be sent through this transformation Proc.  For `multiple` columns, each element will be transformed independently.
+`transform`: If you supply a Proc (or lambda) to the `transform` option, reading this column from the spreadsheet will cause it to first be sent through this transformation Proc. For `multiple` columns, each element will be transformed independently.
 
-`column_name`: By default, SheetsDB will use the attribute name as the name of the column to look for in the header row (first row) of the worksheet.  You can override this, however, by specifying the `column_name` option.
+`column_name`: By default, SheetsDB will use the attribute name as the name of the column to look for in the header row (first row) of the worksheet. You can override this, however, by specifying the `column_name` option.
+
+`aliases`: If the attribute might be found in a column with a different name, you can specify alias column names to search for. This is helpful when changing column names in a model, creating aliases for backwards compatibility, or when you expect potential slightly different spellings. This is optional; by default, there will be no aliases set.
 
 ##### `has_many` and `has_one` associations
 
-For associations in which the key exists in the specifying row, use `has_many` or `has_one`.  The `from_collection` parameter should reference the `has_many` entry on the Spreadsheet model that maps to the target worksheet, and the `key` parameter is the name of the local column that maps to the foreign worksheet's `id` column.
+For associations in which the key exists in the specifying row, use `has_many` or `has_one`. The `from_collection` parameter should reference the `has_many` entry on the Spreadsheet model that maps to the target worksheet, and the `key` parameter is the name of the local column that maps to the foreign worksheet's `id` column.
 
 ##### `belongs_to_many` and `belongs_to_one` associations
 
-For associations in which the key exists in the foreign row, use `belongs_to_many` or `belongs_to_one`.  The `from_collection` parameter should reference the `has_many` entry on the Spreadsheet model that maps to the target worksheet, and the `foreign_key` parameter is the name of the foreign worksheet's column that maps to the local worksheet's `id` column.
+For associations in which the key exists in the foreign row, use `belongs_to_many` or `belongs_to_one`. The `from_collection` parameter should reference the `has_many` entry on the Spreadsheet model that maps to the target worksheet, and the `foreign_key` parameter is the name of the foreign worksheet's column that maps to the local worksheet's `id` column.

data/lib/sheets_db/collection.rb

@@ -2,17 +2,40 @@ module SheetsDB
   class Collection < Resource
     set_resource_type GoogleDrive::Collection
 
-    def self.has_many(resource, class_name:, resource_type: :subcollections)
-      unless [:subcollections, :spreadsheets].include?(resource_type)
-        raise ArgumentError, "resource_type must be :subcollections or :spreadsheets"
+    class << self
+      def has_many(resource, class_name:, resource_type: :subcollections)
+        unless [:subcollections, :spreadsheets].include?(resource_type)
+          raise ArgumentError, "resource_type must be :subcollections or :spreadsheets"
+        end
+        register_association(resource, class_name: class_name, resource_type: resource_type)
+        define_method(resource) do
+          @associated_resources ||= {}
+          @associated_resources[resource] ||= google_drive_resource.send(resource_type).map { |raw|
+            Support.constantize(class_name).new(raw)
+          }
+        end
       end
-      register_association(resource, class_name: class_name, resource_type: resource_type)
-      define_method(resource) do
-        result = instance_variable_get(:"@#{resource}")
-        result || instance_variable_set(:"@#{resource}",
-          google_drive_resource.send(resource_type).map { |raw| Support.constantize(class_name).new(raw) }
-        )
+    end
+
+    %i[
+      spreadsheet
+      subcollection
+    ].each do |child_resource_type|
+      define_method :"google_drive_#{child_resource_type}_by_title" do |title, **kwargs|
+        find_child_google_drive_resource_by(type: child_resource_type, title: title, **kwargs)
       end
     end
+
+    def spreadsheets
+      @anonymous_resources ||= {}
+      @anonymous_resources[:spreadsheets] ||=
+        google_drive_resource.spreadsheets.map { |raw| Spreadsheet.new(raw) }
+    end
+
+    def collections
+      @anonymous_resources ||= {}
+      @anonymous_resources[:collections] ||=
+        google_drive_resource.subcollections.map { |raw| Collection.new(raw) }
+    end
   end
-end
+end

data/lib/sheets_db/resource.rb

@@ -2,6 +2,7 @@ module SheetsDB
   class Resource
     class ResourceTypeMismatchError < StandardError; end
     class CollectionTypeAlreadyRegisteredError < StandardError; end
+    class ChildResourceNotFoundError < StandardError; end
 
     class << self
       attr_reader :resource_type
@@ -17,8 +18,8 @@ module SheetsDB
 
       def find_by_id(id, session: SheetsDB::Session.default)
         google_drive_resource = session.raw_file_by_id(id)
-        if @resource_type && !google_drive_resource.is_a?(@resource_type)
-          fail(ResourceTypeMismatchError, "The file with id #{id} is not a #{@resource_type}")
+        if resource_type && !google_drive_resource.is_a?(resource_type)
+          fail(ResourceTypeMismatchError, "The file with id #{id} is not a #{resource_type}")
         end
         new(google_drive_resource)
       end
@@ -26,10 +27,10 @@ module SheetsDB
       def belongs_to_many(resource, class_name:)
         register_association(resource, class_name: class_name, resource_type: :parents)
         define_method(resource) do
-          result = instance_variable_get(:"@#{resource}")
-          result || instance_variable_set(:"@#{resource}",
-            google_drive_resource.parents.map { |id| Support.constantize(class_name).find_by_id(id) }
-          )
+          @associated_resources ||= {}
+          @associated_resources[resource] ||= google_drive_resource.parents.map { |id|
+            Support.constantize(class_name).find_by_id(id)
+          }
         end
       end
 
@@ -43,6 +44,15 @@ module SheetsDB
           class_name: class_name
         }
       end
+
+      def association_methods_for_type(type)
+        raise ArgumentError unless %i[spreadsheet worksheet subcollection].include?(type)
+
+        google_type = type == :spreadsheet ? :file : type
+        create_prefix = type == :worksheet ? :add : :create
+
+        OpenStruct.new(find: :"#{google_type}_by_title", create: :"#{create_prefix}_#{type}")
+      end
     end
 
     extend Forwardable
@@ -56,6 +66,16 @@ module SheetsDB
       @google_drive_resource = google_drive_resource
     end
 
+    def reload!
+      @associated_resources = nil
+      @anonymous_resources = nil
+      google_drive_resource.reload_metadata
+    end
+
+    def delete!
+      google_drive_resource.delete
+    end
+
     def ==(other)
       other.is_a?(self.class) &&
         other.google_drive_resource == google_drive_resource
@@ -75,5 +95,14 @@ module SheetsDB
         updated_at: updated_at
       }
     end
+
+    def find_child_google_drive_resource_by(type:, title:, create: false)
+      association_methods = self.class.association_methods_for_type(type)
+      child_resource = google_drive_resource.public_send(association_methods.find, title)
+      child_resource ||= google_drive_resource.public_send(association_methods.create, title) if create
+      raise ChildResourceNotFoundError, [self, type, title] if child_resource.nil?
+
+      child_resource
+    end
   end
 end

data/lib/sheets_db/spreadsheet.rb

@@ -5,33 +5,26 @@ module SheetsDB
 
     set_resource_type GoogleDrive::Spreadsheet
 
-    def self.has_many(resource, worksheet_name:, class_name:)
-      register_worksheet_association(resource, worksheet_name: worksheet_name, class_name: class_name)
-      create_worksheet_association(resource, worksheet_name: worksheet_name, class_name: class_name)
-    end
+    class << self
+      def has_many(resource, worksheet_name:, class_name:)
+        register_worksheet_association(resource, worksheet_name: worksheet_name, class_name: class_name)
+        create_worksheet_association(resource, worksheet_name: worksheet_name, class_name: class_name)
+      end
 
-    def self.register_worksheet_association(resource, worksheet_name:, class_name:)
-      @associations ||= {}
-      if @associations.fetch(resource, nil)
-        raise WorksheetAssociationAlreadyRegisteredError
+      def register_worksheet_association(resource, worksheet_name:, class_name:)
+        @associations ||= {}
+        if @associations.fetch(resource, nil)
+          raise WorksheetAssociationAlreadyRegisteredError
+        end
+        @associations[resource] = {
+          worksheet_name: worksheet_name,
+          class_name: class_name
+        }
       end
-      @associations[resource] = {
-        worksheet_name: worksheet_name,
-        class_name: class_name
-      }
-    end
 
-    def self.create_worksheet_association(resource, worksheet_name:, class_name:)
-      define_method(resource) do
-        @worksheets ||= {}
-        @worksheets[resource] ||= begin
-          google_drive_worksheet = google_drive_resource.worksheet_by_title(worksheet_name)
-          raise WorksheetNotFoundError, worksheet_name if google_drive_worksheet.nil?
-          Worksheet.new(
-            spreadsheet: self,
-            google_drive_resource: google_drive_worksheet,
-            type: Support.constantize(class_name)
-          )
+      def create_worksheet_association(resource, **kwargs)
+        define_method(resource) do
+          worksheet_association(resource, **kwargs)
         end
       end
     end
@@ -51,5 +44,35 @@ module SheetsDB
     def select_from_association(association_name, &block)
       send(association_name).select(&block)
     end
+
+    def worksheet_association(association_name, worksheet_name:, class_name:)
+      @associated_resources ||= {}
+      @associated_resources[association_name] ||=
+        find_or_create_worksheet!(title: worksheet_name, type: Support.constantize(class_name))
+    end
+
+    def worksheets
+      @anonymous_resources ||= {}
+      @anonymous_resources[:worksheets] ||= google_drive_resource.worksheets.map { |raw|
+        set_up_worksheet!(google_drive_resource: raw)
+      }
+    end
+
+    def set_up_worksheet!(google_drive_resource:, type: nil)
+      Worksheet.new(
+        google_drive_resource: google_drive_resource,
+        spreadsheet: self,
+        type: type
+      ).set_up!
+    end
+
+    def find_or_create_worksheet!(title:, type: nil)
+      resource = google_drive_worksheet_by_title(title, create: true)
+      set_up_worksheet!(google_drive_resource: resource, type: type)
+    end
+
+    def google_drive_worksheet_by_title(title, **kwargs)
+      find_child_google_drive_resource_by(type: :worksheet, title: title, **kwargs)
+    end
   end
 end

data/lib/sheets_db/version.rb

@@ -1,3 +1,3 @@
 module SheetsDB
-  VERSION = "0.10.1"
+  VERSION = "0.12.0"
 end

data/lib/sheets_db/worksheet/row.rb

@@ -13,8 +13,8 @@ module SheetsDB
           )
         end
 
-        def attribute(name, type: String, multiple: false, transform: nil, column_name: nil, if_column_missing: nil)
-          register_attribute(name, type: type, multiple: multiple, transform: transform, column_name: (column_name || name).to_s, association: false, if_column_missing: if_column_missing)
+        def attribute(name, type: String, multiple: false, transform: nil, column_name: nil, aliases: [], if_column_missing: nil)
+          register_attribute(name, type: type, multiple: multiple, transform: transform, column_name: (column_name || name).to_s, association: false, aliases: aliases, if_column_missing: if_column_missing)
 
           define_method(name) do
             begin
@@ -172,6 +172,7 @@ module SheetsDB
       def reload!
         worksheet.reload!
         reset_attributes_and_associations_cache
+        self
       end
 
       def save!
@@ -179,6 +180,7 @@ module SheetsDB
         worksheet.update_attributes_at_row_position(staged_attributes, row_position: row_position)
         save_changed_foreign_items!
         reset_attributes_and_associations_cache
+        self
       end
 
       def assign_next_row_position_if_not_set
@@ -192,6 +194,7 @@ module SheetsDB
       def reset_attributes_and_associations_cache
         @loaded_attributes = {}
         @loaded_associations = {}
+        self
       end
 
       def staged_attributes

data/lib/sheets_db/worksheet.rb

@@ -7,15 +7,34 @@ module SheetsDB
 
     include Enumerable
 
-    attr_reader :spreadsheet, :google_drive_resource, :type, :synchronizing
+    attr_reader :spreadsheet, :worksheet_title, :google_drive_resource, :synchronizing
 
-    def initialize(spreadsheet:, google_drive_resource:, type:)
+    def initialize(spreadsheet:, google_drive_resource:, type: nil)
       @spreadsheet = spreadsheet
       @google_drive_resource = google_drive_resource
+      @worksheet_title = google_drive_resource.title
       @type = type
       @synchronizing = true
     end
 
+    def set_up!
+      if google_drive_resource.num_rows == 0
+        registered_column_names = attribute_definitions.map { |name, definition| definition[:column_name] }
+        write_matrix!([registered_column_names])
+      end
+      self
+    end
+
+    def type
+      @type || @generated_type ||= begin
+        Class.new(Row).tap { |generated_type_class|
+          column_names.each do |name|
+            generated_type_class.attribute name.to_sym
+          end
+        }
+      end
+    end
+
     def ==(other)
       other.is_a?(self.class) &&
         other.google_drive_resource == google_drive_resource &&
@@ -31,7 +50,8 @@ module SheetsDB
     def columns
       @columns ||= begin
         {}.tap { |directory|
-          google_drive_resource.rows.first.each_with_index do |name, i|
+          header_row = google_drive_resource.rows.first || []
+          header_row.each_with_index do |name, i|
             unless name == ""
               directory[name] = Column.new(name: name, column_position: i + 1)
             end
@@ -49,14 +69,23 @@ module SheetsDB
     end
 
     def get_definition_and_column(attribute_name)
-      attribute_definition = attribute_definitions.fetch(attribute_name)
-      column_name = attribute_definition.fetch(:column_name, attribute_name)
+      column_name = first_existing_column_name(attribute_name)
       [
-        attribute_definition,
-        columns[column_name.to_s]
+        attribute_definitions.fetch(attribute_name),
+        column_name && columns[column_name.to_s]
       ]
     end
 
+    def first_existing_column_name(attribute_name)
+      attribute_definition = attribute_definitions.fetch(attribute_name)
+      [
+        attribute_definition.fetch(:column_name, attribute_name),
+        attribute_definition.fetch(:aliases, [])
+      ].flatten.detect { |name|
+        columns.key?(name.to_s)
+      }
+    end
+
     def value_if_column_missing(attribute_definition)
       unless attribute_definition[:if_column_missing]
         raise ColumnNotFoundError, attribute_definition[:column_name]
@@ -89,12 +118,20 @@ module SheetsDB
 
     def update_attributes_at_row_position(staged_attributes, row_position:)
       staged_attributes.each do |attribute_name, value|
-        attribute_definition, column = get_definition_and_column(attribute_name)
-        raise ColumnNotFoundError, column unless column
-        assignment_value = attribute_definition[:multiple] ? value.join(",") : value
-        google_drive_resource[row_position, column.column_position] = assignment_value
+        update_attribute_at_row_position(
+          attribute_name: attribute_name,
+          value: value,
+          row_position: row_position
+        )
       end
-      google_drive_resource.synchronize if synchronizing
+      synchronize! if synchronizing
+    end
+
+    def update_attribute_at_row_position(attribute_name:, value:, row_position:)
+      attribute_definition, column = get_definition_and_column(attribute_name)
+      raise ColumnNotFoundError, column unless column
+      assignment_value = attribute_definition[:multiple] ? value.join(",") : value
+      google_drive_resource[row_position, column.column_position] = assignment_value
     end
 
     def next_available_row_position
@@ -154,7 +191,11 @@ module SheetsDB
     end
 
     def reload!
+      @columns = nil
+      @existing_raw_data = nil
+      @generated_type = nil
       google_drive_resource.reload
+      self
     end
 
     def convert_to_boolean(raw_value)
@@ -196,9 +237,64 @@ module SheetsDB
     def transaction
       disable_synchronization!
       yield
-      google_drive_resource.synchronize
+      synchronize!
     ensure
       enable_synchronization!
     end
+
+    def delete_google_drive_resource!
+      google_drive_resource.delete
+      @google_drive_resource = nil
+      spreadsheet.reload!
+    end
+
+    def truncate!
+      clear_google_drive_resource!
+      set_up!
+      reload!
+    end
+
+    def write_matrix(matrix, rewrite: false, save: false)
+      clear_google_drive_resource if rewrite
+      google_drive_resource.update_cells(1, 1, matrix)
+      synchronize! if save
+      self
+    end
+
+    def write_matrix!(matrix, **options)
+      write_matrix(matrix, **options.merge(save: true))
+    end
+
+    def write_raw_data(data, **options)
+      raise ArgumentError, "mismatched keys" if data.map(&:keys).uniq.count > 1
+
+      write_matrix(data.map(&:values).prepend(data.first.keys), **options)
+    end
+
+    def write_raw_data!(data, **options)
+      write_raw_data(data, **options.merge(save: true))
+    end
+
+    def clear_google_drive_resource(save: false)
+      empty_matrix = Array.new(google_drive_resource.num_rows, Array.new(google_drive_resource.num_cols))
+      write_matrix(empty_matrix, save: save)
+    end
+
+    def clear_google_drive_resource!
+      clear_google_drive_resource(save: true)
+    end
+
+    def synchronize!
+      google_drive_resource.synchronize
+      @existing_raw_data = nil
+      self
+    end
+
+    def existing_raw_data
+      @existing_raw_data ||= begin
+        rows = google_drive_resource.rows
+        rows.drop(1).map { |row| Hash[rows.first.zip(row)] }
+      end
+    end
   end
 end

data/sheets_db.gemspec

@@ -22,6 +22,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 2.1"
   spec.add_development_dependency "rake", "~> 13"
-  spec.add_development_dependency "rspec", "~> 3.10"
+  spec.add_development_dependency "rspec", "~> 3.11"
   spec.add_development_dependency "simplecov"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sheets_db
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Ravi Gadad
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-13 00:00:00.000000000 Z
+date: 2023-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google_drive
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.11'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -138,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: Adapter for pseudo-relational data stored in Google Sheets