anki_record 0.1.1 → 0.3.0

data/lib/anki_record/deck/deck.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "deck_attributes"
+require_relative "deck_defaults"
+require_relative "../helpers/shared_constants_helper"
+require_relative "../helpers/time_helper"
+
+module AnkiRecord
+  ##
+  # Deck represents an Anki deck.
+  # In the collection.anki21 database, the deck is a JSON object
+  # which is part of a larger JSON object: the value of the col record's decks column.
+  class Deck
+    include DeckAttributes
+    include DeckDefaults
+    include SharedConstantsHelper
+    include TimeHelper
+
+    ##
+    # Instantiates a new Deck object belonging to +collection+ with name +name+.
+    def initialize(collection:, name: nil, args: nil)
+      raise ArgumentError unless (name && args.nil?) || (args && args["name"])
+
+      @collection = collection
+      if args
+        setup_deck_instance_variables_from_existing(args: args)
+      else
+        setup_deck_instance_variables(name: name)
+      end
+
+      @collection.add_deck self
+      save
+    end
+
+    ##
+    # Saves the deck (or updates it) in the collection.anki21 database.
+    def save
+      collection_decks_hash = collection.decks_json
+      collection_decks_hash[@id] = to_h
+      sql = "update col set decks = ? where id = ?"
+      collection.anki_package.prepare(sql).execute([JSON.generate(collection_decks_hash), collection.id])
+    end
+
+    def to_h # :nodoc:
+      {
+        id: @id, mod: @last_modified_timestamp, name: @name, usn: @usn,
+        lrnToday: @learn_today, revToday: @review_today, newToday: @new_today, timeToday: @time_today,
+        collapsed: @collapsed_in_main_window, browserCollapsed: @collapsed_in_browser,
+        desc: @description, dyn: @dyn, conf: @deck_options_group.id,
+        extendNew: @extend_new, extendRev: @extend_review
+      }
+    end
+
+    # :nodoc:
+    # :nocov:
+    def inspect
+      "#<AnkiRecord::Deck:#{object_id} id: #{id} name: #{name} description: #{description}>"
+    end
+
+    private
+
+      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize
+      def setup_deck_instance_variables_from_existing(args:)
+        @id = args["id"]
+        @last_modified_timestamp = args["mod"]
+        @name = args["name"]
+        @usn = args["usn"]
+        @learn_today = args["lrnToday"]
+        @review_today = args["revToday"]
+        @new_today = args["newToday"]
+        @time_today = args["timeToday"]
+        @collapsed_in_main_window = args["collapsed"]
+        @collapsed_in_browser = args["browserCollapsed"]
+        @description = args["desc"]
+        @dyn = args["dyn"]
+        @deck_options_group = @collection.find_deck_options_group_by id: args["conf"]
+        @extend_new = args["extendNew"]
+        @extend_review = args["extendRev"]
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/MethodLength
+      def setup_deck_instance_variables(name:)
+        @id = milliseconds_since_epoch
+        @last_modified_timestamp = seconds_since_epoch
+        @name = name
+        @usn = NEW_OBJECT_USN
+        @learn_today = @review_today = @new_today = @time_today = default_deck_today_array
+        @collapsed_in_main_window = default_collapsed
+        @collapsed_in_browser = default_collapsed
+        @description = ""
+        @dyn = NON_FILTERED_DECK_DYN
+        @deck_options_group = @collection.find_deck_options_group_by id: default_deck_options_group_id
+        @extend_new = 0
+        @extend_review = 0
+      end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/anki_record/deck/deck_attributes.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  # Module with the Deck class's attribute readers, writers, and accessors.
+  module DeckAttributes
+    ##
+    # The deck's collection object.
+    attr_reader :collection
+
+    ##
+    # The deck's name.
+    attr_accessor :name
+
+    ##
+    # The deck's description.
+    attr_accessor :description
+
+    ##
+    # The deck's id.
+    attr_reader :id
+
+    ##
+    # The number of seconds since the 1970 epoch when the deck was last modified.
+    attr_reader :last_modified_timestamp
+
+    ##
+    # The deck's deck options group object.
+    attr_reader :deck_options_group
+  end
+end

data/lib/anki_record/deck/deck_defaults.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  module DeckDefaults # :nodoc:
+    private
+
+      def default_deck_options_group_id
+        collection.deck_options_groups.min_by(&:id).id
+      end
+
+      def default_deck_today_array
+        [0, 0].freeze
+      end
+
+      def default_collapsed
+        false
+      end
+  end
+end

data/lib/anki_record/{deck_options_group.rb → deck_options_group/deck_options_group.rb}

@@ -1,31 +1,20 @@
 # frozen_string_literal: true
 
-require "pry"
-
-require_relative "helpers/shared_constants_helper"
-require_relative "helpers/time_helper"
+require_relative "../helpers/shared_constants_helper"
+require_relative "../helpers/time_helper"
+require_relative "deck_options_group_attributes"
 
 module AnkiRecord
   ##
-  # Represents the set of options that can be applied to a deck
+  # DeckOptionsGroup represents a set of options that can be applied to an Anki deck.
   class DeckOptionsGroup
+    include DeckOptionsGroupAttributes
     include SharedConstantsHelper
     include TimeHelper
 
     ##
-    # The name of the options group
-    attr_accessor :name
-
-    ##
-    # One of many attributes that is currently read-only and needs to be documented.
-    attr_reader :collection, :id, :last_modified_time, :usn, :max_taken, :auto_play, :timer, :replay_question,
-                :new_options, :review_options, :lapse_options, :dyn, :new_mix, :new_per_day_minimum,
-                :interday_learning_mix, :review_order, :new_sort_order, :new_gather_priority, :bury_interday_learning
-
-    ##
-    # Instantiates a new deck options group called +name+ with defaults
+    # Instantiates a new deck options group belonging to +collection+ with name +name+.
     def initialize(collection:, name: nil, args: nil)
-      # TODO: extract this check to a shared helper
       raise ArgumentError unless (name && args.nil?) || (args && args["name"])
 
       @collection = collection
@@ -35,6 +24,8 @@ module AnkiRecord
       else
         setup_deck_options_group_instance_variables(name: name)
       end
+
+      @collection.add_deck_options_group self
     end
 
     private
@@ -43,7 +34,7 @@ module AnkiRecord
       # rubocop:disable Metrics/AbcSize
       def setup_deck_options_group_instance_variables_from_existing(args:)
         @id = args["id"]
-        @last_modified_time = args["mod"]
+        @last_modified_timestamp = args["mod"]
         @name = args["name"]
         @usn = args["usn"]
         @max_taken = args["maxTaken"]
@@ -62,14 +53,10 @@ module AnkiRecord
         @new_gather_priority = args["newGatherPriority"]
         @bury_interday_learning = args["buryInterdayLearning"]
       end
-      # rubocop:enable Metrics/AbcSize
-      # rubocop:enable Metrics/MethodLength
 
-      # rubocop:disable Metrics/MethodLength
-      # rubocop:disable Metrics/AbcSize
       def setup_deck_options_group_instance_variables(name:)
         @id = milliseconds_since_epoch
-        @last_modified_time = seconds_since_epoch
+        @last_modified_timestamp = seconds_since_epoch
         @name = name
         @usn = NEW_OBJECT_USN
         @max_taken = 60

data/lib/anki_record/deck_options_group/deck_options_group_attributes.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  ##
+  # Module with the Card class's attribute readers, writers, and accessors.
+  module DeckOptionsGroupAttributes
+    ##
+    # The deck options group's collection object.
+    attr_reader :collection
+
+    ##
+    # The deck option group's name.
+    attr_accessor :name
+
+    ##
+    # The deck option group's id.
+    attr_reader :id
+
+    ##
+    # The number of milliseconds since the 1970 epoch at which the deck options group was modified.
+    attr_reader :last_modified_timestamp
+  end
+end

data/lib/anki_record/helpers/checksum_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module AnkiRecord
+  ##
+  # A module for the method that calculates the checksum value of notes.
+  #
+  # This checksum may be used by Anki to detect duplicates.
+  module ChecksumHelper
+    ##
+    # Returns the integer representation of the first 8 characters of the SHA-1 digest of the +sfld+ argument
+    def checksum(sfld)
+      Digest::SHA1.hexdigest(sfld)[0...8].to_i(16).to_s
+    end
+  end
+end

data/lib/anki_record/helpers/data_query_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  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

data/lib/anki_record/helpers/shared_constants_helper.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
 module AnkiRecord
-  ##
-  # Helper module to hold the constants used by multiple classes
-  module SharedConstantsHelper
+  module SharedConstantsHelper # :nodoc:
     NEW_OBJECT_USN = -1
     NON_FILTERED_DECK_DYN = 0
     private_constant :NEW_OBJECT_USN, :NON_FILTERED_DECK_DYN

data/lib/anki_record/helpers/time_helper.rb

@@ -4,18 +4,20 @@ require "date"
 
 module AnkiRecord
   ##
-  # Helper module to calculate integer time values since the 1970 epoch
+  # Helper module to calculate integer time values since the 1970 epoch.
   #
-  # Specifically, the time that has passed since 00:00:00 UTC Jan 1 1970
+  # Specifically, the time that has passed since 00:00:00 UTC Jan 1 1970.
   module TimeHelper
     ##
-    # Return the number of milliseconds since the 1970 epoch
+    # Returns approximately the number of milliseconds since the 1970 epoch.
+    # A random amount of milliseconds between -5000 and 5000 is added so that
+    # primary key ids calculated with this should be unique.
     def milliseconds_since_epoch
-      DateTime.now.strftime("%Q").to_i
+      DateTime.now.strftime("%Q").to_i + rand(-5000..5000)
     end
 
     ##
-    # Return the number of seconds since the 1970 epoch
+    # Returns approximately the number of seconds since the 1970 epoch.
     def seconds_since_epoch
       Time.now.to_i
     end

data/lib/anki_record/note/note.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "../helpers/checksum_helper"
+require_relative "../helpers/time_helper"
+require_relative "note_attributes"
+
+# rubocop:disable Metrics/ClassLength
+module AnkiRecord
+  ##
+  # Represents an Anki note. The note object corresponds to a record in the `notes`
+  # table in the collection.anki21 database.
+  class Note
+    include ChecksumHelper
+    include NoteAttributes
+    include TimeHelper
+    include SharedConstantsHelper
+
+    ##
+    # Instantiates a note of type +note_type+ and belonging to deck +deck+.
+    #
+    # If +note_type+ and +deck+ arguments are used, +collection+ and +data should not be given.
+    def initialize(note_type: nil, deck: nil, collection: 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])
+      else
+        raise ArgumentError
+      end
+    end
+
+    private
+
+      def setup_instance_variables_for_new_note(note_type:, deck:)
+        raise ArgumentError unless note_type.collection == deck.collection
+
+        setup_collaborator_object_instance_variables_for_new_note(note_type: note_type, deck: deck)
+        setup_simple_instance_variables_for_new_note
+      end
+
+      def setup_collaborator_object_instance_variables_for_new_note(note_type:, deck:)
+        @note_type = note_type
+        @deck = deck
+        @collection = deck.collection
+        @field_contents = setup_empty_field_contents_hash
+        @cards = @note_type.card_templates.map do |card_template|
+          Card.new(note: self, card_template: 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
+        @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)
+        @cards = @note_type.card_templates.map.with_index do |_card_template, index|
+          Card.new(note: self, card_data: cards_data[index])
+        end
+      end
+
+      def setup_field_contents_hash_from_existing(note_data:)
+        field_contents = setup_empty_field_contents_hash
+        snake_case_field_names_in_order = note_type.snake_case_field_names
+        note_data["flds"].split("\x1F").each_with_index do |fld, ordinal|
+          field_contents[snake_case_field_names_in_order[ordinal]] = fld
+        end
+        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
+          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,
+                           @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
+          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,
+                           @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 globally_unique_id
+        SecureRandom.uuid.slice(5...15)
+      end
+
+      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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  # Module with the Note class's attribute readers, writers, and accessors.
+  module NoteAttributes
+    ##
+    # The note's id.
+    attr_reader :id
+
+    ##
+    # The note's globally unique id.
+    attr_reader :guid
+
+    ##
+    # The number of seconds since the 1970 epoch at which the note was last modified.
+    attr_reader :last_modified_timestamp
+
+    ##
+    # The note's update sequence number.
+    attr_reader :usn
+
+    ##
+    # The note's tags, as an array. The tags are strings.
+    attr_reader :tags
+
+    ##
+    # The note's field contents, as a hash.
+    attr_reader :field_contents
+
+    ##
+    # The note's deck object.
+    #
+    # When the note is saved, the cards will belong to this deck.
+    attr_reader :deck
+
+    ##
+    # The note's note type object.
+    attr_reader :note_type
+
+    ##
+    # The note's collection object.
+    attr_reader :collection
+
+    ##
+    # The note's card objects, as an array.
+    attr_reader :cards
+
+    ##
+    # 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.
+    attr_reader :data
+  end
+end

data/lib/anki_record/note_field/note_field.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "note_field_attributes"
+require_relative "note_field_defaults"
+
+module AnkiRecord
+  ##
+  # NoteField represents a field of an Anki note type.
+  class NoteField
+    include NoteFieldAttributes
+    include NoteFieldDefaults
+
+    ##
+    # Instantiates a new field for the note type +note_type+ with name +name+.
+    def initialize(note_type:, name: nil, args: nil)
+      raise ArgumentError unless (name && args.nil?) || (args && args["name"])
+
+      @note_type = note_type
+      if args
+        setup_note_field_instance_variables_from_existing(args: args)
+      else
+        setup_note_field_instance_variables_for_new_field(name: name)
+      end
+
+      @note_type.add_note_field self
+    end
+
+    def to_h # :nodoc:
+      {
+        name: @name,
+        ord: @ordinal_number,
+        sticky: @sticky,
+        rtl: @right_to_left,
+        font: @font_style,
+        size: @font_size,
+        description: @description
+      }
+    end
+
+    private
+
+      def setup_note_field_instance_variables_from_existing(args:)
+        @name = args["name"]
+        @ordinal_number = args["ord"]
+        @sticky = args["sticky"]
+        @right_to_left = args["rtl"]
+        @font_style = args["font"]
+        @font_size = args["size"]
+        @description = args["description"]
+      end
+
+      def setup_note_field_instance_variables_for_new_field(name:)
+        @name = name
+        @ordinal_number = @note_type.note_fields.length
+        @sticky = false
+        @right_to_left = false
+        @font_style = default_field_font_style
+        @font_size = default_field_font_size
+        @description = default_field_description
+      end
+  end
+end

data/lib/anki_record/note_field/note_field_attributes.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  ##
+  # Module with the NoteField class's attribute readers, writers, and accessors.
+  module NoteFieldAttributes
+    ##
+    # The field's note type.
+    attr_reader :note_type
+
+    ##
+    # The field's name.
+    attr_accessor :name
+
+    ##
+    # A boolean that indicates if the field is sticky.
+    attr_accessor :sticky
+
+    ##
+    # A boolean that indicates if the field is right to left.
+    attr_accessor :right_to_left
+
+    ##
+    # The field's font style used when editing.
+    attr_accessor :font_style
+
+    ##
+    # The field's font size used when editing.
+    attr_accessor :font_size
+
+    ##
+    # The field's description.
+    attr_accessor :description
+
+    ##
+    # 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_field/note_field_defaults.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  module NoteFieldDefaults # :nodoc:
+    private
+
+      def default_field_font_style
+        "Arial"
+      end
+
+      def default_field_font_size
+        20
+      end
+
+      def default_field_description
+        ""
+      end
+  end
+end