sheets_v4 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaee6f486ac124cdefd974acfe3f18357ade8e9f90655a46e746ebfad53a391b
-  data.tar.gz: 0f3c1e513b45a841052be82817e5bcf157aba492282999f401bb069e048e2263
+  metadata.gz: d8730b843169d2404228e744281e52a37624c61f33cb061b99e38178faab2cc9
+  data.tar.gz: 4f156d01ec986dd39eb0c471f9838b1670d16c33240843dbec7b873489e10c68
 SHA512:
-  metadata.gz: c3762e42b88065e6bc76e5e749d629dc02073c2584053a9c979fd8b46196e70e155c2f06d87a768b511a93b30d38d09c5da6592ef875a9fb70cb7bd97b67ed7a
-  data.tar.gz: 64bed7345bcc3ee05d204b47770b297e8a53d05cc1deb6611bd114197cb46690df2683549e772b7b9453fbf158eba492efc05faf93e966047f57055e9d203d87
+  metadata.gz: 3b6558bcfc332037e0bf21a1b9605e94a629bdd89bc7621a6afe455bb4451395b1178e4ba92c23ba61e76adef6fd6a9ec4a9f8abc326f4068fcc505c97172ecc
+  data.tar.gz: 5fdce2afd7f3063452bbe79cc7ce35311d87d415c44027c566dbd27099e2ac748777b497a3a4f1e46a3e044e21463c4299fb58bf83df30f048d43a6f29c2529c

data/CHANGELOG.md

@@ -4,6 +4,14 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## v0.9.0 (2023-10-16)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.8.0..v0.9.0)
+
+Changes since v0.8.0:
+
+* 8fd7ec5 Add convenience methods to Spreadsheet to access Sheets (#28)
+
 ## v0.8.0 (2023-10-15)
 
 [Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.7.0..v0.8.0)

data/README.md

@@ -303,6 +303,13 @@ sheets_service, spreadsheet, and sheet objects separately.
 
 The `sheets_service` attribute is added and is set by `SheetsService#get_spreadsheet`.
 
+Convenience methods for getting sheets within the spreadsheet are added:
+
+* `sheet(id_or_title)`: returns the sheet matching the id or title given
+* `sheet_id(title)`: returns the ID  for the sheet matching the title given
+* `each_sheet(ids_or_titles)`: enumerates the sheets within a spreadsheet matching
+  the given IDs or titles.
+
 #### Sheet Extensions
 
 The `sheets_service` and `spreadsheet` attributes are added. Both are set when the

data/lib/sheets_v4/google_extensions/spreadsheet.rb

@@ -19,6 +19,86 @@ module SheetsV4
       #
       # @return [Google::Apis::SheetsV4::SheetsService]
       attr_reader :sheets_service
+
+      # Return the matching sheet object or nil
+      #
+      # If `id_or_title` is an Integer, it is assumed to be the sheet ID.  Otherwise,
+      # it is assumed to be the sheet title.
+      #
+      # @example Get the sheet whose title is 'Sheet1'
+      #   sheet = spreadsheet.sheet('Sheet1')
+      #
+      # @example Get the sheet whose title is '2023-03-15'
+      #   date = Date.new(2023, 3, 15)
+      #   sheet = spreadsheet.sheet(date)
+      #
+      # @example Get the sheet whose ID is 123456
+      #   sheet = spreadsheet.sheet(123456)
+      #
+      # @param id_or_title [Integer, #to_s] the ID or title of the sheet to return
+      #
+      # @return [Google::Apis::SheetsV4::Sheet, nil]
+      #
+      def sheet(id_or_title)
+        if id_or_title.is_a?(Integer)
+          sheets.find { |sheet| sheet.properties.sheet_id == id_or_title }
+        else
+          title = id_or_title.to_s
+          sheets.find { |sheet| sheet.properties.title == title }
+        end
+      end
+
+      # Return the ID of the matching sheet
+      #
+      # @example
+      #   id = spreadsheet.sheet_id('Sheet1')
+      #
+      # @param id_or_title [Integer, #to_s] the ID or title of the sheet
+      #
+      # @return [Integer]
+      #
+      def sheet_id(id_or_title)
+        sheet(id_or_title)&.properties&.sheet_id
+      end
+
+      # Iterate over sheets in a spreadsheet
+      #
+      # If `ids_or_titles` is not given or is nil, all sheets are enumerated.  Otherwise,
+      # only the sheets whose IDs or titles are in `sheets` are enumerated.
+      #
+      # @example Enumerate all sheets
+      #   spreadsheet.each_sheet { |sheet| puts sheet.properties.title }
+      #
+      # @example Enumerate sheets whose IDs are 123456 and 789012
+      #   sheets = [123456, 789012]
+      #   spreadsheet.each_sheet(sheets).with_index do |sheet, index|
+      #     puts "#{index}: #{sheet.properties.title} (#{sheet.properties.sheet_id})"
+      #   end
+      #
+      # @param ids_or_titles [Array<Integer, #to_s>] an array of sheet IDs and/or titles
+      #
+      #   An Integer in this array is match to the sheet ID. Anything else is matched
+      #   to the sheet title after calling `#to_s` on it.
+      #
+      # @return [void]
+      #
+      # @yield each matching sheet
+      # @yieldparam [Google::Apis::SheetsV4::Sheet] the matching sheet
+      #
+      # @raise [RuntimeError] if one of the sheets does not exist
+      # @raise [RuntimeError] if a block is not given
+      #
+      def each_sheet(ids_or_titles = sheets.map { |sheet| sheet.properties.sheet_id }, &block)
+        return enum_for(:each_sheet, ids_or_titles) unless block
+
+        matching_sheets = ids_or_titles.map do |id_or_title|
+          sheet(id_or_title) || raise("Could not find sheet '#{id_or_title}'")
+        end
+
+        matching_sheets.each { |sheet| block[sheet] }
+
+        self
+      end
     end
   end
 end

data/lib/sheets_v4/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sheets_v4
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - James Couball