anki_record 0.4 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 625337f0aac620a6662e846e1bf08a4ebe7a57224386b7154e24381ff275a507
-  data.tar.gz: cb8e0001a1b37ad480ef3b218a1e64ef1a7429da777bb7f7bd9b68b51d2cbd9a
+  metadata.gz: e1a86e3c0c6ba10ebfe3867e0bdc62d5a3e8e1218fc4783c1ade86c34d790318
+  data.tar.gz: 662ec96ab3e29c26b0de4405b1c699ba99a6b180af5dbb2a24eb6ad4e7919cef
 SHA512:
-  metadata.gz: c0e0fbf06f373cf555bd233c6f42aff0123858f80e58b5a525ca72f53bec28572930c91988424b9c3a3756182f779177a92c4f6dc8d8eae86cb46a95d3216ae1
-  data.tar.gz: e89bc47239ad32052e9b51f1825073bc1dd40e8586b56360437fac0dbf7258fd8b6e7eb4d9f7f5a4b4dee8b00f66482fccf3b99aa03a024c83c636a54a4c5e0a
+  metadata.gz: 9d6de87dfadcc19fe0777202f67a97d632ddaec65426d171eda9ac74d87e7d99acc2afeb964e02529a695c1409a6c0fe26a9ee026d7b6fdbfb8c2d3b284230de
+  data.tar.gz: c35379873392e86fe7d6a402212d84c7c8d557543b84909d24c07e1ac34a927819628f13eff335f1b2a2e0d8bc7eda6218b86dca742660838d6b2148c16e4eee

data/CHANGELOG.md

@@ -54,3 +54,9 @@
 - Responsibilites of `Collection` have been reorganized to `Anki21Database`.
 - The `guid` attribute of notes ic computed in a different way that allows a larger number of possible values.
 - `globally_unique_id` is now a module method rather than an included instance method.
+
+## [0.4.1] - 08-21-2023
+- `Anki21Database#find_note_by` now can take the sort field value of a note as argument.
+- `Anki21Database#find_notes_by_exact_text_match` is a new method that returns an array of notes that have in any field text matching the argument.
+- Trying to create an Anki package file with a path/name that already exists raises a more helpful error message.
+- Saving a note to the database saves the `mod` column (last modified time) to make it easier to import an updated package into Anki.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    anki_record (0.4)
+    anki_record (0.4.1)
       rubyzip (>= 2.3)
       sqlite3 (~> 1.3)
 

data/README.md

@@ -14,9 +14,9 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-This example shows how to create a new Anki package and also most of the features of the gem:
+This example shows how to create a new Anki package and most of the API:
 
-```
+```ruby
 require "anki_record"
 
 AnkiRecord::AnkiPackage.create(name: "example") do |anki21_database|
@@ -25,13 +25,18 @@ AnkiRecord::AnkiPackage.create(name: "example") do |anki21_database|
   custom_deck.save
 
   # Creating a new note type
-  custom_note_type = AnkiRecord::NoteType.new(anki21_database:, name: "New custom note type")
-  AnkiRecord::NoteField.new(note_type: custom_note_type, name: "custom front")
-  AnkiRecord::NoteField.new(note_type: custom_note_type, name: "custom back")
-  custom_card_template = AnkiRecord::CardTemplate.new(note_type: custom_note_type, name: "Custom template 1")
+  custom_note_type = AnkiRecord::NoteType.new(anki21_database:,
+                                              name: "New custom note type")
+  AnkiRecord::NoteField.new(note_type: custom_note_type,
+                            name: "custom front")
+  AnkiRecord::NoteField.new(note_type: custom_note_type,
+                            name: "custom back")
+  custom_card_template = AnkiRecord::CardTemplate.new(note_type: custom_note_type,
+                                                      name: "Custom template 1")
   custom_card_template.question_format = "{{custom front}}"
   custom_card_template.answer_format = "{{custom back}}"
-  second_custom_card_template = AnkiRecord::CardTemplate.new(note_type: custom_note_type, name: "Custom template 2")
+  second_custom_card_template = AnkiRecord::CardTemplate.new(note_type: custom_note_type,
+                                                             name: "Custom template 2")
   second_custom_card_template.question_format = "{{custom back}}"
   second_custom_card_template.answer_format = "{{custom front}}"
 
@@ -46,45 +51,49 @@ AnkiRecord::AnkiPackage.create(name: "example") do |anki21_database|
   custom_note_type.css = css
   custom_note_type.save
 
-  # Creating a note with the custom note type
+  # Creating a new note with the custom note type
   note = AnkiRecord::Note.new(note_type: custom_note_type, deck: custom_deck)
   note.custom_front = "Content of the 'custom front' field"
   note.custom_back = "Content of the 'custom back' field"
   note.save
 
-  # The default deck
+  # Finding the default deck
   default_deck = anki21_database.find_deck_by(name: "Default")
 
-  # All of the default Anki note types
+  # Finding all of the default Anki note types
   basic_note_type = anki21_database.find_note_type_by(name: "Basic")
   basic_and_reversed_card_note_type = anki21_database.find_note_type_by(name: "Basic (and reversed card)")
   basic_and_optional_reversed_card_note_type = anki21_database.find_note_type_by(name: "Basic (optional reversed card)")
   basic_type_in_the_answer_note_type = anki21_database.find_note_type_by(name: "Basic (type in the answer)")
   cloze_note_type = anki21_database.find_note_type_by(name: "Cloze")
 
-  # Creating notes using the default note types
+  # Creating new notes using the default note types
 
   basic_note = AnkiRecord::Note.new(note_type: basic_note_type, deck: default_deck)
   basic_note.front = "What molecule is most relevant to the name aerobic exercise?"
   basic_note.back = "Oxygen"
   basic_note.save
 
-  # Creating a nested deck
-  amino_acids_deck = AnkiRecord::Deck.new(anki21_database:, name: "Biochemistry::Amino acids")
+  # Creating a new nested deck
+  amino_acids_deck = AnkiRecord::Deck.new(anki21_database:,
+                                          name: "Biochemistry::Amino acids")
   amino_acids_deck.save
 
-  basic_and_reversed_note = AnkiRecord::Note.new(note_type: basic_and_reversed_card_note_type, deck: amino_acids_deck)
+  basic_and_reversed_note = AnkiRecord::Note.new(note_type: basic_and_reversed_card_note_type,
+                                                 deck: amino_acids_deck)
   basic_and_reversed_note.front = "Tyrosine"
   basic_and_reversed_note.back = "Y"
   basic_and_reversed_note.save
 
-  basic_and_optional_reversed_note = AnkiRecord::Note.new(note_type: basic_and_optional_reversed_card_note_type, deck: default_deck)
+  basic_and_optional_reversed_note = AnkiRecord::Note.new(note_type: basic_and_optional_reversed_card_note_type,
+                                                          deck: default_deck)
   basic_and_optional_reversed_note.front = "A technique where locations along a route are memorized and associated with ideas"
   basic_and_optional_reversed_note.back = "The method of loci"
   basic_and_optional_reversed_note.add_reverse = "Have a reverse card too"
   basic_and_optional_reversed_note.save
 
-  basic_type_in_the_answer_note = AnkiRecord::Note.new(note_type: basic_type_in_the_answer_note_type, deck: default_deck)
+  basic_type_in_the_answer_note = AnkiRecord::Note.new(note_type: basic_type_in_the_answer_note_type,
+                                                       deck: default_deck)
   basic_type_in_the_answer_note.front = "What Git command commits staged changes by changing the previous commit without editing the commit message?"
   basic_type_in_the_answer_note.back = "git commit --amend --no-edit"
   basic_type_in_the_answer_note.save
@@ -94,7 +103,8 @@ AnkiRecord::AnkiPackage.create(name: "example") do |anki21_database|
   cloze_note.back_extra = "This condition involves one cranial nerve but can have myriad neurological symptoms"
   cloze_note.save
 end
-# The example.apkg package now exists in the current working directory and contains 6 notes.
+# An example.apkg file should be in the current
+# working directory with 6 notes.
 
 ```
 
@@ -102,7 +112,7 @@ end
 
 The gem can also be used to update an existing Anki package:
 
-```
+```ruby
 require "anki_record"
 
 AnkiRecord::AnkiPackage.update(path: "./example.apkg") do |anki21_database|
@@ -117,7 +127,7 @@ If an error is thrown in the block here, the original Anki package will not be c
 
 ## Documentation
 
-The [API Documentation](https://kylerego.github.io/anki_record_docs) is generated from comments in the source code could be useful if the above examples are not sufficient for your use case.
+The [API Documentation](https://kylerego.github.io/anki_record_docs) generated from source code comments might be useful but I think the examples above show everything you can do that you would want to do.
 
 ## Development
 

data/lib/anki_record/anki21_database/anki21_database.rb

@@ -30,21 +30,49 @@ module AnkiRecord
       database.prepare sql
     end
 
+    # rubocop:disable Metrics/MethodLength
     ##
-    # Returns the note found by +id+, or nil if it is not found.
-    def find_note_by(id:)
-      note_cards_data = note_cards_data_for_note_id(id:)
+    # Returns the note found by either +sfld" or +id+, or nil if it is not found.
+    def find_note_by(sfld: nil, id: nil)
+      if (id && sfld) || (id.nil? && sfld.nil?)
+        raise ArgumentError,
+              "You must pass either an id or sfld keyword argument to find_note_by."
+      end
+      note_cards_data = if id
+                          note_cards_data_for_note(id:)
+                        else
+                          note_cards_data_for_note(sfld:)
+                        end
       return nil unless note_cards_data
 
       AnkiRecord::Note.new(anki21_database: self, data: note_cards_data)
     end
+    # rubocop:enable Metrics/MethodLength
+
+    ##
+    # Returns an array of notes that have any field value matching +text+
+    def find_notes_by_exact_text_match(text:)
+      return [] if text == ""
+
+      like_matcher = "%#{text}%"
+      note_datas = prepare("select * from notes where flds LIKE ?").execute([like_matcher])
+
+      note_datas.map do |note_data|
+        id = note_data["id"]
+
+        cards_data = prepare("select * from cards where nid = ?").execute([id]).to_a
+        note_cards_data = { note_data:, cards_data: }
+
+        AnkiRecord::Note.new(anki21_database: self, data: note_cards_data)
+      end
+    end
 
     ##
     # Returns the note type found by either +name+ or +id+, or nil if it is not found.
     def find_note_type_by(name: nil, id: nil)
       if (id && name) || (id.nil? && name.nil?)
         raise ArgumentError,
-              "You must pass either an id or name keyword argument."
+              "You must pass either an id or name keyword argument to find_note_type_by."
       end
 
       name ? find_note_type_by_name(name:) : find_note_type_by_id(id:)
@@ -55,7 +83,7 @@ module AnkiRecord
     def find_deck_by(name: nil, id: nil)
       if (id && name) || (id.nil? && name.nil?)
         raise ArgumentError,
-              "You must pass either an id or name keyword argument."
+              "You must pass either an id or name keyword argument to find_deck_by."
       end
 
       name ? find_deck_by_name(name:) : find_deck_by_id(id:)
@@ -127,10 +155,16 @@ module AnkiRecord
         decks.find { |deck| deck.id == id }
       end
 
-      def note_cards_data_for_note_id(id:)
-        note_data = prepare("select * from notes where id = ?").execute([id]).first
+      def note_cards_data_for_note(id: nil, sfld: nil)
+        note_data = if id
+                      prepare("select * from notes where id = ?").execute([id]).first
+                    elsif sfld
+                      prepare("select * from notes where sfld = ?").execute([sfld]).first
+                    end
         return nil unless note_data
 
+        id ||= note_data["id"]
+
         cards_data = prepare("select * from cards where nid = ?").execute([id]).to_a
         { note_data:, cards_data: }
       end

data/lib/anki_record/anki_package/anki_package.rb

@@ -96,6 +96,7 @@ module AnkiRecord
       def validate_arguments(name:, target_directory:)
         check_name_argument_is_valid(name:)
         check_target_directory_argument_is_valid(target_directory:)
+        check_anki_package_does_not_already_exist(name:, target_directory:)
       end
 
       def check_name_argument_is_valid(name:)
@@ -110,6 +111,12 @@ module AnkiRecord
         raise ArgumentError, "No directory was found at the given path."
       end
 
+      def check_anki_package_does_not_already_exist(name:, target_directory:)
+        return unless Pathname.new("#{target_directory}/#{new_apkg_name(name:)}.apkg").exist?
+
+        raise ArgumentError, "An Anki package with that name already exists."
+      end
+
       def new_apkg_name(name:)
         name.end_with?(".apkg") ? name[0, name.length - 5] : name
       end

data/lib/anki_record/note/note.rb

@@ -62,6 +62,13 @@ module AnkiRecord
       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
@@ -78,7 +85,7 @@ module AnkiRecord
         end
         @id = milliseconds_since_epoch
         @guid = Helpers::AnkiGuidHelper.globally_unique_id
-        @last_modified_timestamp = seconds_since_epoch
+        @last_modified_timestamp = nil
         @usn = NEW_OBJECT_USN
         @tags = []
         @flags = 0
@@ -123,7 +130,7 @@ module AnkiRecord
           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) }
@@ -134,7 +141,7 @@ module AnkiRecord
           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)
@@ -144,9 +151,5 @@ module AnkiRecord
         # 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

data/lib/anki_record/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AnkiRecord
-  VERSION = "0.4" # :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.4'
+  version: 0.4.1
 platform: ruby
 authors:
 - Kyle Rego
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-08 00:00:00.000000000 Z
+date: 2023-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip