anki_record 0.3.2 → 0.4.1

data/lib/anki_record/note/note.rb

@@ -2,78 +2,113 @@
 
 require "securerandom"
 
+require_relative "../helpers/anki_guid_helper"
 require_relative "../helpers/checksum_helper"
 require_relative "../helpers/time_helper"
 require_relative "note_attributes"
-require_relative "note_guid_helper"
 
-# rubocop:disable Metrics/ClassLength
 module AnkiRecord
   ##
-  # Represents an Anki note.
+  # Note represents Anki notes, which are the main thing that Anki Record is intended to create or update.
   class Note
     include Helpers::ChecksumHelper
     include NoteAttributes
-    include NoteGuidHelper
     include Helpers::TimeHelper
     include Helpers::SharedConstantsHelper
 
     ##
-    # Instantiates a note of type +note_type+ and belonging to deck +deck+.
-    def initialize(note_type: nil, deck: nil, collection: nil, data: nil)
+    # Instantiates a note of type +note_type+ and belonging to deck +deck+
+    def initialize(note_type: nil, deck: nil, anki21_database: nil, data: nil)
       if note_type && deck
-        setup_instance_variables_for_new_note(note_type: note_type, deck: deck)
-      elsif collection && data
-        setup_instance_variables_from_existing(collection: collection,
-                                               note_data: data[:note_data], cards_data: data[:cards_data])
+        setup_new_note(note_type:, deck:)
+      elsif anki21_database && data
+        setup_existing_note(anki21_database:,
+                            note_data: data[:note_data], cards_data: data[:cards_data])
       else
         raise ArgumentError
       end
     end
 
-    private
+    ##
+    # Saves the note and its cards
+    def save
+      anki21_database.find_note_by(id: @id) ? update_note_in_collection_anki21 : insert_new_note_in_collection_anki21
+      true
+    end
 
-      def setup_instance_variables_for_new_note(note_type:, deck:)
-        raise ArgumentError unless note_type.collection == deck.collection
+    ##
+    # Overrides BasicObject#method_missing and creates "ghost methods"
+    #
+    # The ghost methods are the setters and getters for the note field values.
+    #
+    # For example, if the note type has a field called "front" then there will be two ghost methods: front and front=.
+    def method_missing(method_name, field_content = nil)
+      raise NoMethodError, "##{method_name} is not defined or a ghost method" unless respond_to_missing? method_name
 
-        setup_collaborator_object_instance_variables_for_new_note(note_type: note_type, deck: deck)
-        setup_simple_instance_variables_for_new_note
+      method_name = method_name.to_s
+      return @field_contents[method_name] unless method_name.end_with?("=")
+
+      @field_contents[method_name.chomp("=")] = field_content
+    end
+
+    ##
+    # This allows #respond_to? to be accurate for the ghost methods created by #method_missing.
+    def respond_to_missing?(method_name, *)
+      method_name = method_name.to_s
+      if method_name.end_with?("=")
+        note_type.snake_case_field_names.include?(method_name.chomp("="))
+      else
+        note_type.snake_case_field_names.include?(method_name)
       end
+    end
+
+    ##
+    # Returns the text value of the note's sfld (sort field) which is determined by
+    # the note's note type
+    def sort_field_value
+      @field_contents[note_type.snake_case_sort_field_name]
+    end
+
+    private
+
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/MethodLength
+      def setup_new_note(note_type:, deck:)
+        raise ArgumentError unless note_type.anki21_database == deck.anki21_database
 
-      def setup_collaborator_object_instance_variables_for_new_note(note_type:, deck:)
         @note_type = note_type
         @deck = deck
-        @collection = deck.collection
+        @anki21_database = note_type.anki21_database
         @field_contents = setup_empty_field_contents_hash
         @cards = @note_type.card_templates.map do |card_template|
-          Card.new(note: self, card_template: card_template)
+          Card.new(note: self, card_template:)
         end
-      end
-
-      def setup_simple_instance_variables_for_new_note
         @id = milliseconds_since_epoch
-        @guid = globally_unique_id
-        @last_modified_timestamp = seconds_since_epoch
+        @guid = Helpers::AnkiGuidHelper.globally_unique_id
+        @last_modified_timestamp = nil
         @usn = NEW_OBJECT_USN
         @tags = []
         @flags = 0
         @data = ""
       end
 
-      def setup_instance_variables_from_existing(collection:, note_data:, cards_data:)
-        setup_collaborator_object_instance_variables_from_existing(collection: collection, note_data: note_data,
-                                                                   cards_data: cards_data)
-        setup_simple_instance_variables_from_existing(note_data: note_data)
-      end
-
-      def setup_collaborator_object_instance_variables_from_existing(collection:, note_data:, cards_data:)
-        @collection = collection
-        @note_type = collection.find_note_type_by id: note_data["mid"]
-        @field_contents = setup_field_contents_hash_from_existing(note_data: note_data)
+      def setup_existing_note(anki21_database:, note_data:, cards_data:)
+        @anki21_database = anki21_database
+        @note_type = anki21_database.find_note_type_by id: note_data["mid"]
+        @field_contents = setup_field_contents_hash_from_existing(note_data:)
         @cards = @note_type.card_templates.map.with_index do |_card_template, index|
           Card.new(note: self, card_data: cards_data[index])
         end
+        @id = note_data["id"]
+        @guid = note_data["guid"]
+        @last_modified_timestamp = note_data["mod"]
+        @usn = note_data["usn"]
+        @tags = note_data["tags"].split
+        @flags = note_data["flags"]
+        @data = note_data["data"]
       end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/MethodLength
 
       def setup_field_contents_hash_from_existing(note_data:)
         field_contents = setup_empty_field_contents_hash
@@ -84,93 +119,37 @@ module AnkiRecord
         field_contents
       end
 
-      def setup_simple_instance_variables_from_existing(note_data:)
-        @id = note_data["id"]
-        @guid = note_data["guid"]
-        @last_modified_timestamp = note_data["mod"]
-        @usn = note_data["usn"]
-        @tags = note_data["tags"].split
-        @flags = note_data["flags"]
-        @data = note_data["data"]
-      end
-
       def setup_empty_field_contents_hash
         field_contents = {}
         note_type.snake_case_field_names.each { |field_name| field_contents[field_name] = "" }
         field_contents
       end
 
-    public
-
-    ##
-    # Saves the note to the collection.anki21 database.
-    #
-    # This also saves the note's cards.
-    def save
-      collection.find_note_by(id: @id) ? update_note_in_collection_anki21 : insert_new_note_in_collection_anki21
-      true
-    end
-
-    private
-
       def update_note_in_collection_anki21
-        statement = @collection.anki_package.prepare <<~SQL
+        statement = anki21_database.prepare <<~SQL
           update notes set guid = ?, mid = ?, mod = ?, usn = ?, tags = ?,
                                       flds = ?, sfld = ?, csum = ?, flags = ?, data = ? where id = ?
         SQL
-        statement.execute([@guid, note_type.id, @last_modified_timestamp,
+        statement.execute([@guid, note_type.id, seconds_since_epoch,
                            @usn, @tags.join(" "), field_values_separated_by_us, sort_field_value,
                            checksum(sort_field_value), @flags, @data, @id])
         cards.each { |card| card.save(note_exists_already: true) }
       end
 
       def insert_new_note_in_collection_anki21
-        statement = @collection.anki_package.prepare <<~SQL
+        statement = anki21_database.prepare <<~SQL
           insert into notes (id, guid, mid, mod, usn, tags, flds, sfld, csum, flags, data)
                       values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         SQL
-        statement.execute([@id, @guid, note_type.id, @last_modified_timestamp,
+        statement.execute([@id, @guid, note_type.id, seconds_since_epoch,
                            @usn, @tags.join(" "), field_values_separated_by_us, sort_field_value,
                            checksum(sort_field_value), @flags, @data])
         cards.each(&:save)
       end
 
-    public
-
-    ##
-    # Overrides BasicObject#method_missing and creates "ghost methods".
-    #
-    # The ghost methods are the setters and getters for the note field values.
-    def method_missing(method_name, field_content = nil)
-      raise NoMethodError, "##{method_name} is not defined or a ghost method" unless respond_to_missing? method_name
-
-      method_name = method_name.to_s
-      return @field_contents[method_name] unless method_name.end_with?("=")
-
-      @field_contents[method_name.chomp("=")] = field_content
-    end
-
-    ##
-    # This allows #respond_to? to be accurate for the ghost methods created by #method_missing.
-    def respond_to_missing?(method_name, *)
-      method_name = method_name.to_s
-      if method_name.end_with?("=")
-        note_type.snake_case_field_names.include?(method_name.chomp("="))
-      else
-        note_type.snake_case_field_names.include?(method_name)
-      end
-    end
-
-    private
-
       def field_values_separated_by_us
         # The ASCII control code represented by hexadecimal 1F is the Unit Separator (US)
         note_type.snake_case_field_names.map { |field_name| @field_contents[field_name] }.join("\x1F")
       end
-
-      def sort_field_value
-        @field_contents[note_type.snake_case_sort_field_name]
-      end
   end
 end
-# rubocop:enable Metrics/ClassLength

data/lib/anki_record/note/note_attributes.rb

@@ -1,56 +1,57 @@
 # frozen_string_literal: true
 
 module AnkiRecord
-  # Module with the Note class's attribute readers, writers, and accessors.
+  # Module with Note's attribute readers, writers, and accessors.
   module NoteAttributes
+    attr_reader :anki21_database # :nodoc:
+
     ##
-    # The note's id.
+    # The note's id
     attr_reader :id
 
     ##
-    # The note's globally unique id.
+    # The note's globally unique id
+    #
+    # This is used by Anki to match an imported note to an existing note and
+    # update it rather than duplicate the note.
     attr_accessor :guid
 
     ##
-    # The number of seconds since the 1970 epoch at which the note was last modified.
+    # The number of seconds since the 1970 epoch when the note was last modified.
     attr_reader :last_modified_timestamp
 
     ##
-    # The note's update sequence number.
+    # The note's update sequence number
     attr_reader :usn
 
     ##
-    # The note's tags, as an array. The tags are strings.
+    # The note's tags, as an array of strings
     attr_reader :tags
 
     ##
-    # The note's field contents, as a hash.
+    # The note's field contents as a hash
     attr_reader :field_contents
 
     ##
-    # The note's deck object.
+    # The note's deck.
     #
-    # When the note is saved, the cards will belong to this deck.
+    # When the note is saved, the note will belong to this deck
     attr_reader :deck
 
     ##
-    # The note's note type object.
+    # The note's note type
     attr_reader :note_type
 
     ##
-    # The note's collection object.
-    attr_reader :collection
-
-    ##
-    # The note's card objects, as an array.
+    # The note's card objects, as an array
     attr_reader :cards
 
     ##
-    # Corresponds to the flags column in the collection.anki21 notes table.
+    # Corresponds to the flags column in the collection.anki21 notes table
     attr_reader :flags
 
     ##
-    # Corresponds to the data column in the collection.anki21 notes table.
+    # Corresponds to the data column in the collection.anki21 notes table
     attr_reader :data
   end
 end

data/lib/anki_record/note_field/note_field.rb

@@ -5,7 +5,7 @@ require_relative "note_field_defaults"
 
 module AnkiRecord
   ##
-  # NoteField represents a field of an Anki note type.
+  # NoteField represents a field of an Anki note type
   class NoteField
     include NoteFieldAttributes
     include NoteFieldDefaults
@@ -17,9 +17,9 @@ module AnkiRecord
 
       @note_type = note_type
       if args
-        setup_note_field_instance_variables_from_existing(args: args)
+        setup_note_field_instance_variables_from_existing(args:)
       else
-        setup_note_field_instance_variables_for_new_field(name: name)
+        setup_note_field_instance_variables_for_new_field(name:)
       end
 
       @note_type.add_note_field self

data/lib/anki_record/note_field/note_field_attributes.rb

@@ -2,38 +2,38 @@
 
 module AnkiRecord
   ##
-  # Module with the NoteField class's attribute readers, writers, and accessors.
+  # Module with NoteField class's attribute readers, writers, and accessors.
   module NoteFieldAttributes
     ##
-    # The field's note type.
+    # The field's note type
     attr_reader :note_type
 
     ##
-    # The field's name.
+    # The field's name
     attr_accessor :name
 
     ##
-    # A boolean that indicates if the field is sticky.
+    # A boolean that indicates if the field is sticky
     attr_accessor :sticky
 
     ##
-    # A boolean that indicates if the field is right to left.
+    # A boolean that indicates if the field is right to left
     attr_accessor :right_to_left
 
     ##
-    # The field's font style used when editing.
+    # The field's font style used when editing
     attr_accessor :font_style
 
     ##
-    # The field's font size used when editing.
+    # The field's font size used when editing
     attr_accessor :font_size
 
     ##
-    # The field's description.
+    # The field's description
     attr_accessor :description
 
     ##
-    # 0 for the first field of the note type, 1 for the second, etc.
+    # 0 for the first field of the note type, 1 for the second, etc
     attr_reader :ordinal_number
   end
 end

data/lib/anki_record/note_type/note_type.rb

@@ -10,8 +10,6 @@ require_relative "note_type_defaults"
 module AnkiRecord
   ##
   # NoteType represents an Anki note type (also called a model).
-  #
-  # The attributes are documented in the NoteTypeAttributes module.
   class NoteType
     include Helpers::SharedConstantsHelper
     include Helpers::TimeHelper
@@ -21,28 +19,29 @@ module AnkiRecord
     NOTE_TYPES_WITHOUT_TAGS_AND_VERS_VALUES = ["Basic", "Basic (and reversed card)",
                                                "Basic (optional reversed card)", "Basic (type in the answer)"].freeze
 
-    def initialize(collection:, name: nil, args: nil)
+    ##
+    # Instantiates a new note type belonging to +anki21_database+ with name +name+
+    def initialize(anki21_database:, name: nil, args: nil)
       raise ArgumentError unless (name && args.nil?) || (args && args["name"])
 
-      @collection = collection
+      @anki21_database = anki21_database
 
       if args
-        setup_note_type_instance_variables_from_existing(args: args)
+        setup_note_type_instance_variables_from_existing(args:)
       else
-        setup_instance_variables_for_new_note_type(name: name)
+        setup_instance_variables_for_new_note_type(name:)
       end
 
-      @collection.add_note_type self
-      save
+      @anki21_database.add_note_type self
     end
 
     ##
     # Saves the note type to the collection.anki21 database
     def save
-      collection_models_hash = collection.models_json
+      collection_models_hash = anki21_database.models_json
       collection_models_hash[@id] = to_h
       sql = "update col set models = ? where id = ?"
-      collection.anki_package.prepare(sql).execute([JSON.generate(collection_models_hash), collection.id])
+      anki21_database.prepare(sql).execute([JSON.generate(collection_models_hash), anki21_database.collection.id])
     end
 
     def to_h # :nodoc:
@@ -68,7 +67,7 @@ module AnkiRecord
     end
 
     def snake_case_field_names # :nodoc:
-      field_names_in_order.map { |field_name| field_name.downcase.gsub(" ", "_") }
+      field_names_in_order.map { |field_name| field_name.downcase.tr(" ", "_") }
     end
 
     ##
@@ -78,7 +77,7 @@ module AnkiRecord
     end
 
     def snake_case_sort_field_name # :nodoc:
-      sort_field_name.downcase.gsub(" ", "_")
+      sort_field_name.downcase.tr(" ", "_")
     end
 
     ##
@@ -109,8 +108,8 @@ module AnkiRecord
     private
 
       def setup_note_type_instance_variables_from_existing(args:)
-        setup_collaborator_object_instance_variables_from_existing(args: args)
-        setup_simple_instance_variables_from_existing(args: args)
+        setup_collaborator_object_instance_variables_from_existing(args:)
+        setup_simple_instance_variables_from_existing(args:)
       end
 
       def setup_collaborator_object_instance_variables_from_existing(args:)

data/lib/anki_record/note_type/note_type_attributes.rb

@@ -2,70 +2,68 @@
 
 module AnkiRecord
   ##
-  # Module with the NoteType class's attribute readers, writers, and accessors.
+  # Module with the NoteType class's attribute readers, writers, and accessors
   module NoteTypeAttributes
-    ##
-    # The note type's collection object.
-    attr_reader :collection
+    attr_reader :anki21_database, :latex_svg, :tags, :req, :vers
 
     ##
-    # The note type's id.
+    # The note type's id
     attr_reader :id
 
     ##
-    # The note type's name.
+    # The note type's name
     attr_accessor :name
 
     ##
-    # A boolean that indicates if this note type is a cloze-deletion note type.
+    # A boolean that indicates if this note type is a cloze-deletion note type
     attr_accessor :cloze
 
     ##
-    # The number of seconds since the 1970 epoch at which the note type was last modified.
+    # The number of seconds since the 1970 epoch at which the note type was last modified
     attr_reader :last_modified_timestamp
 
     ##
-    # The note type's update sequence number.
+    # The note type's update sequence number
     attr_reader :usn
 
     ##
-    # The note type's sort field.
+    # The note type's sort field
     attr_reader :sort_field
 
     ##
-    # The note type's CSS.
+    # The note type's CSS
     attr_accessor :css
 
     ##
-    # The note type's LaTeX preamble.
+    # The note type's LaTeX preamble
     attr_reader :latex_preamble
 
     ##
-    # The note type's LaTeX postamble.
+    # The note type's LaTeX postamble
     attr_reader :latex_postamble
 
     ##
-    # The note type's card template objects, as an array.
+    # The note type's card template objects, as an array
     attr_reader :card_templates
 
     ##
-    # The note type's field objects, as an array.
+    # The note type's field objects, as an array
     attr_reader :note_fields
 
     ##
-    # The note type's deck's id.
+    # The note type's deck's id
     attr_reader :deck_id
 
     ##
-    # The note type's deck.
+    # The note type's deck
     def deck
       return nil unless @deck_id
 
-      @collection.find_deck_by id: @deck_id
+      anki21_database.find_deck_by id: @deck_id
     end
 
     ##
-    # Sets the note type's deck object.
+    # Sets the note type's deck object
     def deck=(deck)
       unless deck.instance_of?(AnkiRecord::Deck)
         raise ArgumentError,
@@ -74,7 +72,5 @@ module AnkiRecord
 
       @deck_id = deck.id
     end
-
-    attr_reader :latex_svg, :tags, :req, :vers
   end
 end

data/lib/anki_record/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AnkiRecord
-  VERSION = "0.3.2" # :nodoc:
+  VERSION = "0.4.1" # :nodoc:
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anki_record
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - Kyle Rego
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-05-20 00:00:00.000000000 Z
+date: 2023-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-description: "  A Ruby library which provides a programmatic interface to Anki flashcard
-  decks (.apkg files/zipped Anki SQLite databases).\n"
+description: "  Anki Record lets you create Anki deck packages or update existing
+  ones with the Ruby programming language.\n"
 email:
 - regoky@outlook.com
 executables: []
@@ -57,6 +57,10 @@ files:
 - Rakefile
 - anki_record.gemspec
 - lib/anki_record.rb
+- lib/anki_record/anki21_database/anki21_database.rb
+- lib/anki_record/anki21_database/anki21_database_attributes.rb
+- lib/anki_record/anki21_database/anki21_database_constructors.rb
+- lib/anki_record/anki2_database/anki2_database.rb
 - lib/anki_record/anki_package/anki_package.rb
 - lib/anki_record/card/card.rb
 - lib/anki_record/card/card_attributes.rb
@@ -70,13 +74,13 @@ files:
 - lib/anki_record/deck/deck_defaults.rb
 - lib/anki_record/deck_options_group/deck_options_group.rb
 - lib/anki_record/deck_options_group/deck_options_group_attributes.rb
+- lib/anki_record/helpers/anki_guid_helper.rb
 - lib/anki_record/helpers/checksum_helper.rb
-- lib/anki_record/helpers/data_query_helper.rb
 - lib/anki_record/helpers/shared_constants_helper.rb
 - lib/anki_record/helpers/time_helper.rb
+- lib/anki_record/media/media.rb
 - lib/anki_record/note/note.rb
 - lib/anki_record/note/note_attributes.rb
-- lib/anki_record/note/note_guid_helper.rb
 - lib/anki_record/note_field/note_field.rb
 - lib/anki_record/note_field/note_field_attributes.rb
 - lib/anki_record/note_field/note_field_defaults.rb
@@ -110,5 +114,5 @@ requirements: []
 rubygems_version: 3.4.6
 signing_key: 
 specification_version: 4
-summary: Automate Anki flashcard editing with the Ruby programming language.
+summary: Create and update Anki deck packages with Ruby.
 test_files: []

data/lib/anki_record/helpers/data_query_helper.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module AnkiRecord
-  module Helpers
-    module DataQueryHelper # :nodoc:
-      def note_cards_data_for_note_id(sql_able:, id:)
-        note_data = sql_able.prepare("select * from notes where id = ?").execute([id]).first
-        return nil unless note_data
-
-        cards_data = sql_able.prepare("select * from cards where nid = ?").execute([id]).to_a
-        { note_data: note_data, cards_data: cards_data }
-      end
-    end
-  end
-end

data/lib/anki_record/note/note_guid_helper.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-module AnkiRecord
-  # Module with the helper method to generate the note guid.
-  module NoteGuidHelper
-    def globally_unique_id
-      SecureRandom.uuid.slice(5...15)
-    end
-  end
-end