anki_record 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b6bcf30a94ecdc25ac6632007ec16125c92ee8a35a13d93dfbe61b721a5564c
-  data.tar.gz: d3ad70a4966a2fb260447e44d6da5f33fb799a4559a5147d8deb554ea6fbe5c1
+  metadata.gz: 060b1e641776c8bf67bc20fa50029c1801ca7b367e2e038b2aa9b3024cd7b22b
+  data.tar.gz: 21a27f8b9d0726122bc2ba22eb6132573e161d30d73e4db866f081db87ea8409
 SHA512:
-  metadata.gz: 8ff665346db80061992e832cada84a373b22bd480bfbbbf3e1deab9ca2e3915d4a668442bccee98de746ed1a636ab6a978bc5ef0c61e640908a4df5fe0c57bf3
-  data.tar.gz: 563d4c9984ab0c98af1565748904263902c9fa374af61e3882b8c618dcb471856f2d36137e8590489354148b13c1492f94e9744970addf5e8acad07f40efce17
+  metadata.gz: 8fdf8b0330814f95a11dffba1fbf2d113aa97269a8eba51d3675d7a8a761e37148dc5561b5fd96eeb9c94fd8b416ae00ade70acf88b20a0e5f7a9a668c4a8a7b
+  data.tar.gz: de6e49c1acbb6f56b952f682be94affaa8beecfcea79fb473fed9b53f0970e40394302b48a2b2cc167315589d8200669a13f5f4721ac184a4606b8a3ef4972f2

data/CHANGELOG.md

@@ -2,8 +2,15 @@
 
 ## [Unreleased/0.1.0] - 02-22-2023
 
-- First version that can be used to create a complete *.apkg file that imports into Anki
+- The gem can be used to create an *.apkg zip file that successfully imports into Anki.
+- Raw SQL statements can be executed against the temporary database before it is zipped.
 
 ## [0.1.1] - 02-24-2023
 
-- Updated documentation
+- Updated documentation to release the first version
+
+## [0.2.0] - 03-05-2023
+
+- `AnkiPackage#zip_and_close` is changed to `AnkiPackage#zip`
+- Decks and note types can be accessed through the collection object
+- Notes can be created, updated, and saved to the database and this also populates the corresponding records in the `cards` table

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    anki_record (0.1.1)
+    anki_record (0.2.0)
       rubyzip (>= 2.3)
-      sqlite3
+      sqlite3 (~> 1.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,10 +1,8 @@
 # AnkiRecord
 
-AnkiRecord provides an interface to Anki SQLite databases through the Ruby programming language.
+AnkiRecord is a Ruby gem which provides a programmatic interface to creating and updating Anki flashcard deck files (`*.apkg` Anki SQLite databases). **This gem is in an early stage of development--I do not recommend you use it yet.**
 
-Currently it can be used to create an empty Anki database file, execute raw SQL statements against it, and then zip the database into an *.apkg file which can be imported into Anki.
-
-[Documentation](https://kylerego.github.io/anki_record_docs)
+[API Documentation](https://kylerego.github.io/anki_record_docs)
 
 ## Installation
 
@@ -18,16 +16,60 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+The Anki package object is instantiated with `AnkiRecord::AnkiPackage.new` and if passed a block, will execute the block and zip the `*.apkg` file:
+
 ```ruby
 require "anki_record"
 
-db = AnkiRecord::AnkiPackage.new name: "test1"
-db.execute "any valid SQL statement"
-db.zip_and_close # creates test.apkg file in the current working directory
+AnkiRecord::AnkiPackage.new(name: "test") do |apkg|
+  3.times do |number|
+    puts "#{3 - number}..."
+  end
+  puts "Countdown complete. Write any Ruby you want in here!"
+end
+```
+
+If an exception is raised inside the block, the temporary `collection.anki2` and `collection.anki21` databases are deleted without creating a new `*.apkg` zip file, so this is the recommended way.
 
+Alternatively, if `AnkiRecord::Package::new` is not passed a block, the `zip` method must be explicitly called on the Anki package object:
+
+```ruby
+require "anki_record"
+
+apkg = AnkiRecord::AnkiPackage.new(name: "test")
+apkg.zip
 ```
 
-The RSpec tests are written BDD-style as executable documentation; reading them might help to understand the gem (e.g. [anki_package_spec.rb](https://github.com/KyleRego/anki_record/blob/main/spec/anki_record/anki_package_spec.rb)).
+A new Anki package object is initialized with the "Default" deck and the default note types of a new Anki collection (including "Basic" and "Cloze"). The deck and note type objects can be accessed through the `collection` attribute of the Anki package object through the `find_deck_by` and `find_note_type_by` methods by passing the `name` keyword argument:
+
+```ruby
+require "anki_record"
+
+apkg = AnkiRecord::AnkiPackage.new name: "test"
+
+deck = apkg.collection.find_deck_by name: "Default"
+
+note_type = apkg.collection.find_note_type_by name: "Basic"
+
+note = AnkiRecord::Note.new note_type: note_type, deck: deck
+note.front = "Hello"
+note.back = "World"
+note.save
+
+note_type2 = apkg.collection.find_note_type_by name: "Cloze"
+
+note2 = AnkiRecord::Note.new note_type: note_type2, deck: deck
+note2.text = "Cloze {{c1::Hello}}"
+note2.back_extra = "World"
+note2.save
+
+apkg.zip
+
+```
+
+This example creates a `test.apkg` zip file in the current working directory, which when imported into Anki, will add one Basic note and one Cloze note.
+
+The RSpec examples are intended to provide executable documentation, and reading them may be helpful to understand the API (e.g. [anki_package_spec.rb](https://github.com/KyleRego/anki_record/blob/main/spec/anki_record/anki_package_spec.rb)).
 
 ## Development
 
@@ -35,10 +77,21 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Development road map: 
+- Work on creating and updating notes and cards to the collection.anki21 database
+- Validation logic of what makes the note valid based on the note type's card templates and fields
+- Work on adding media support
+  - Checksum for notes needs to be updated
+- Work on updating and saving decks
+- Work on updating and saving deck options groups
+- Work on updating and saving note types including the note fields and card templates
+
 ### Release checklist
-- Bump version
 - Update changelog
-- Regenerate documentation
+- Update usage examples
+- Update and regenerate documentation
+- Bump version
+- Release gem
 
 <!-- ## Contributing
 
@@ -50,4 +103,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the AnkiRecord project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/KyleRegoanki_record/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the AnkiRecord project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/KyleRego/anki_record/blob/main/CODE_OF_CONDUCT.md).

data/anki_record.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "rubyzip", ">= 2.3"
-  spec.add_dependency "sqlite3"
+  spec.add_dependency "sqlite3", "~> 1.3"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/anki_record/anki_package.rb

@@ -3,6 +3,9 @@
 require "pry"
 require "pathname"
 
+require_relative "card"
+require_relative "note"
+
 require_relative "db/anki_schema_definition"
 require_relative "db/clean_collection2_record"
 require_relative "db/clean_collection21_record"
@@ -24,6 +27,10 @@ module AnkiRecord
 
     private_constant :NAME_ERROR_MESSAGE, :PATH_ERROR_MESSAGE, :STANDARD_ERROR_MESSAGE
 
+    ##
+    # The collection object of the package
+    attr_reader :collection
+
     ##
     # Creates a new object which represents an Anki SQLite3 database
     #
@@ -34,20 +41,11 @@ module AnkiRecord
     # which is saved in +directory+. +directory+ is the current working directory by default.
     # If the block throws a runtime error, the temporary files are deleted but the zip file is not created.
     #
-    # When no block argument is used, #zip_and_close must be called explicitly at the end of your script.
-    def initialize(name:, directory: Dir.pwd)
+    # When no block argument is used, #zip must be called explicitly at the end of your script.
+    def initialize(name:, directory: Dir.pwd, &closure)
       setup_package_instance_variables(name: name, directory: directory)
 
-      return unless block_given?
-
-      begin
-        yield self
-      rescue StandardError => e
-        close
-        puts_error_and_standard_message(error: e)
-      else
-        zip_and_close
-      end
+      execute_closure_and_zip(self, &closure) if block_given?
     end
 
     ##
@@ -62,6 +60,15 @@ module AnkiRecord
 
     private
 
+      def execute_closure_and_zip(object_to_yield, &closure)
+        closure.call(object_to_yield)
+      rescue StandardError => e
+        destroy_temporary_directory
+        puts_error_and_standard_message(error: e)
+      else
+        zip
+      end
+
       def setup_package_instance_variables(name:, directory:)
         @name = check_name_is_valid(name: name)
         @directory = directory # TODO: check directory is valid
@@ -118,13 +125,22 @@ module AnkiRecord
     # Creates a new object which represents the Anki SQLite3 database file at +path+
     #
     # Development has focused on ::new so this method is not recommended at this time
-    def self.open(path:, create_backup: true)
+    def self.open(path:, target_directory: nil, &closure)
       pathname = check_file_at_path_is_valid(path: path)
-      copy_apkg_file(pathname: pathname) if create_backup
-      @anki_package = new(name: pathname.basename.to_s, directory: pathname.dirname)
+      new_apkg_name = "#{File.basename(pathname.to_s, ".apkg")}-#{seconds_since_epoch}"
+
+      @anki_package = if target_directory
+                        new(name: new_apkg_name, directory: target_directory)
+                      else
+                        new(name: new_apkg_name)
+                      end
+      @anki_package.send :execute_closure_and_zip, @anki_package, &closure if block_given?
+      @anki_package
     end
 
     class << self
+      include TimeHelper
+
       private
 
         def check_file_at_path_is_valid(path:)
@@ -133,22 +149,17 @@ module AnkiRecord
 
           pathname
         end
-
-        def copy_apkg_file(pathname:)
-          path = pathname.to_s
-          FileUtils.cp path, "#{path}.copy-#{Time.now.to_i}"
-        end
     end
 
     ##
     # Zips the temporary files into the *.apkg package and deletes the temporary files.
-    def zip_and_close
-      zip && close
+    def zip
+      create_zip_file && destroy_temporary_directory
     end
 
     private
 
-      def zip
+      def create_zip_file
         Zip::File.open(target_zip_file, create: true) do |zip_file|
           @tmp_files.each do |file_name|
             zip_file.add(file_name, File.join(@tmpdir, file_name))
@@ -161,7 +172,7 @@ module AnkiRecord
         "#{@directory}/#{@name}.apkg"
       end
 
-      def close
+      def destroy_temporary_directory
         @anki21_database.close
         FileUtils.rm_rf(@tmpdir)
       end

data/lib/anki_record/card.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "pry"
+
+require_relative "helpers/shared_constants_helper"
+require_relative "helpers/time_helper"
+
+module AnkiRecord
+  ##
+  # Card represents an Anki card.
+  class Card
+    include TimeHelper
+    include SharedConstantsHelper
+
+    ##
+    # The note that the card belongs to
+    attr_reader :note
+
+    ##
+    # The card template that the card uses
+    attr_reader :card_template
+
+    ##
+    # The id of the card, which is time it was created as the number of milliseconds since the 1970 epoch
+    attr_reader :id
+
+    ##
+    # The time that the card was last modified as the number of seconds since the 1970 epoch
+    attr_reader :last_modified_time
+
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+    def initialize(note:, card_template:)
+      raise ArgumentError unless note && card_template && note.note_type == card_template.note_type
+
+      @note = note
+      @apkg = @note.deck.collection.anki_package
+
+      @card_template = card_template
+
+      @id = milliseconds_since_epoch
+      @last_modified_time = seconds_since_epoch
+      @usn = NEW_OBJECT_USN
+      @type = 0
+      @queue = 0
+      @due = 0
+      @ivl = 0
+      @factor = 0
+      @reps = 0
+      @lapses = 0
+      @left = 0
+      @odue = 0
+      @odid = 0
+      @flags = 0
+      @data = {}
+    end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize
+
+    ##
+    # Saves the card to the collection.anki21 database
+    def save
+      @apkg.execute <<~SQL
+        insert into cards (id, nid, did, ord,
+                          mod, usn, type, queue,
+                          due, ivl, factor, reps,
+                          lapses, left, odue, odid, flags, data)
+                    values ('#{@id}', '#{@note.id}', '#{@note.deck.id}', '#{@card_template.ordinal_number}',
+                           '#{@last_modified_time}', '#{@usn}', '#{@type}', '#{@queue}',
+                           '#{@due}', '#{@ivl}', '#{@factor}', '#{@reps}',
+                           '#{@lapses}', '#{@left}', '#{@odue}', '#{@odid}', '#{@flags}', '#{@data}')
+      SQL
+    end
+  end
+end

data/lib/anki_record/card_template.rb

@@ -9,27 +9,53 @@ module AnkiRecord
   # CardTemplate represents a card template of an Anki note type
   class CardTemplate
     ##
-    # The name of this card template
+    # The name of the card template
     attr_accessor :name
 
     ##
-    # The question format
-    attr_accessor :question_format
+    # The font style shown for the card template in the browser
+    attr_accessor :browser_font_style
 
     ##
-    # The answer format
-    attr_accessor :answer_format
+    # The font size used for the card template in the browser
+    attr_accessor :browser_font_size
 
     ##
-    # The font style shown for this card template in the browser
-    attr_accessor :browser_font_style
+    # The question format of the card template
+    attr_reader :question_format
 
     ##
-    # The font size used for this card template in the browser
-    attr_accessor :browser_font_size
+    # Sets the question format and raises an ArgumentError if the specified format uses invalid fields
+    def question_format=(format)
+      fields_in_specified_format = format.scan(/{{.+?}}/).map do |capture|
+        capture.chomp("}}").reverse.chomp("{{").reverse
+      end
+      raise ArgumentError if fields_in_specified_format.any? do |field_name|
+                               !note_type.allowed_card_template_question_format_field_names.include?(field_name)
+                             end
+
+      @question_format = format
+    end
+
+    ##
+    # The answer format of the card template
+    attr_reader :answer_format
+
+    ##
+    # Sets the answer format and raises an ArgumentError if the specified format uses invalid fields
+    def answer_format=(format)
+      fields_in_specified_format = format.scan(/{{.+?}}/).map do |capture|
+        capture.chomp("}}").reverse.chomp("{{").reverse
+      end
+      raise ArgumentError if fields_in_specified_format.any? do |field_name|
+                               !note_type.allowed_card_template_answer_format_field_names.include?(field_name)
+                             end
+
+      @answer_format = format
+    end
 
     ##
-    # The note type that this card template belongs to
+    # The note type that the card template belongs to
     attr_reader :note_type
 
     ##
@@ -66,7 +92,7 @@ module AnkiRecord
 
       def setup_card_template_instance_variables(name:)
         @name =  name
-        @ordinal_number = @note_type.templates.length
+        @ordinal_number = @note_type.card_templates.length
         @question_format = ""
         @answer_format = ""
         @bqfmt =  ""
@@ -75,17 +101,5 @@ module AnkiRecord
         @browser_font_style = ""
         @browser_font_size = 0
       end
-
-    public
-
-    ##
-    # Returns the field names that are allowed in the answer format and question format
-    #
-    # These are the field_name values in {{field_name}} in those formats.
-    #
-    # They are equivalent to the names of the fields of the template's note type.
-    def allowed_field_names
-      @note_type.fields.map(&:name)
-    end
   end
 end

data/lib/anki_record/collection.rb

@@ -15,19 +15,59 @@ module AnkiRecord
     include AnkiRecord::TimeHelper
 
     ##
-    # An array of the collection's note type objects
+    # The instance of AnkiRecord::AnkiPackage that this collection object belongs to
+    attr_reader :anki_package
+
+    ##
+    # The id attribute will become, or is the same as, the primary key id of this record in the database
+    #
+    # Since there should be only one col record, this attribute should be 1
+    attr_reader :id
+
+    ##
+    # The time in milliseconds that the col record was created since the 1970 epoch
+    attr_reader :creation_timestamp
+
+    ##
+    # The last time that the col record was modified in milliseconds since the 1970 epoch
+    attr_reader :last_modified_time
+
+    ##
+    # An array of the collection's note type objects, which are instances of AnkiRecord::NoteType
     attr_reader :note_types
 
     ##
-    # An array of the collection's deck objects
+    # An array of the collection's deck objects, which are instances of AnkiRecord::Deck
     attr_reader :decks
 
+    ##
+    # An array of the collection's deck options group objects, which are instances of AnkiRecord::DeckOptionsGroup
+    #
+    # These represent groups of settings that can be applied to a deck.
+    attr_reader :deck_options_groups
+
     ##
     # Instantiates the collection object for the +anki_package+
+    #
+    # The collection object represents the single record of the collection.anki21 database col table.
+    #
+    # This record stores the note types used by the notes and the decks that they belong to.
     def initialize(anki_package:)
       setup_collection_instance_variables(anki_package: anki_package)
     end
 
+    ##
+    # Find one of the collection's note types by name
+    def find_note_type_by(name: nil)
+      note_types.find { |note_type| note_type.name == name }
+    end
+
+    ##
+    # Find one of the collection's decks by name
+    def find_deck_by(name: nil)
+      decks.find { |deck| deck.name == name }
+    end
+
     private
 
       # rubocop:disable Metrics/MethodLength
@@ -35,8 +75,8 @@ module AnkiRecord
       def setup_collection_instance_variables(anki_package:)
         @anki_package = anki_package
         @id = col_record["id"]
-        @crt = col_record["crt"]
-        @last_modified_time = (mod = col_record["mod"]).zero? ? milliseconds_since_epoch : mod
+        @creation_timestamp = col_record["crt"]
+        @last_modified_time = col_record["mod"]
         @scm = col_record["scm"]
         @ver = col_record["ver"]
         @dty = col_record["dty"]
@@ -49,7 +89,7 @@ module AnkiRecord
         @decks = JSON.parse(col_record["decks"]).values.map do |deck_hash|
           Deck.new(collection: self, args: deck_hash)
         end
-        @deck_option_groups = JSON.parse(col_record["dconf"]).values.map do |dconf_hash|
+        @deck_options_groups = JSON.parse(col_record["dconf"]).values.map do |dconf_hash|
           DeckOptionsGroup.new(collection: self, args: dconf_hash)
         end
         @tags = JSON.parse(col_record["tags"])

data/lib/anki_record/deck.rb

@@ -5,8 +5,6 @@ require "pry"
 require_relative "helpers/shared_constants_helper"
 require_relative "helpers/time_helper"
 
-# TODO: All instance variables should at least be readable
-
 module AnkiRecord
   ##
   # Deck represents an Anki deck
@@ -19,6 +17,10 @@ module AnkiRecord
 
     private_constant :DEFAULT_DECK_TODAY_ARRAY, :DEFAULT_COLLAPSED
 
+    ##
+    # The collection object that the deck belongs to
+    attr_reader :collection
+
     ##
     # The name of the deck
     attr_accessor :name
@@ -28,11 +30,21 @@ module AnkiRecord
     attr_accessor :description
 
     ##
-    # One of many attributes that is currently read-only and needs to be documented.
-    attr_reader :collection, :id, :last_modified_time, :deck_options_group_id
+    # The id of the deck
+    attr_reader :id
+
+    ##
+    # The last time the deck was modified in number of seconds since the epoch
+    #
+    # TODO: is this really supposed to be seconds? Should it be milliseconds?
+    attr_reader :last_modified_time
+
+    ##
+    # The id of the eck options/settings group that is applied to the deck
+    attr_reader :deck_options_group_id
 
     ##
-    # Instantiate a new Deck
+    # Instantiates a new Deck object
     def initialize(collection:, name: nil, args: nil)
       raise ArgumentError unless (name && args.nil?) || (args && args["name"])
 
@@ -79,7 +91,8 @@ module AnkiRecord
         @collapsed_in_browser = DEFAULT_COLLAPSED
         @description = ""
         @dyn = NON_FILTERED_DECK_DYN
-        @deck_options_group_id = nil # TODO
+        @deck_options_group_id = nil # TODO: Set id to the default deck options group?
+        # TODO: alternatively, if this is nil when the deck is saved, it can be set to the default options group id
         @extend_new = 0
         @extend_review = 0
       end

data/lib/anki_record/deck_options_group.rb

@@ -13,14 +13,20 @@ module AnkiRecord
     include TimeHelper
 
     ##
-    # The name of the options group
+    # The collection object that the deck options group belongs to
+    attr_reader :collection
+
+    ##
+    # The name of the deck 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
+    # The id of the deck options group
+    attr_reader :id
+
+    ##
+    # The last time that this deck options group was modified in milliseconds since the 1970 epoch
+    attr_reader :last_modified_time
 
     ##
     # Instantiates a new deck options group called +name+ with defaults

data/lib/anki_record/helpers/checksum_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module AnkiRecord
+  ##
+  # A module for the method that calculates the checksum value of notes.
+  #
+  # This checksum is used by Anki to detect duplicates.
+  module ChecksumHelper
+    ##
+    # Compute the integer representation of the first 8 characters of the digest
+    # (calculated using the SHA-1 Secure Hash Algorithm) of the argument
+    # TODO: This needs to be expanded to strip HTML (except media)
+    # and more tests to ensure it calculates the same value as Anki does in that case
+    def checksum(sfld)
+      Digest::SHA1.hexdigest(sfld)[0...8].to_i(16).to_s
+    end
+  end
+end

data/lib/anki_record/note.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "pry"
+require "securerandom"
+
+require_relative "helpers/checksum_helper"
+require_relative "helpers/time_helper"
+
+module AnkiRecord
+  ##
+  # Note represents an Anki note
+  class Note
+    include ChecksumHelper
+    include TimeHelper
+    include SharedConstantsHelper
+
+    ##
+    # The id of the note
+    attr_reader :id
+
+    ##
+    # The globally unique id of the note
+    attr_reader :guid
+
+    ##
+    # The last time the note was modified in seconds since the 1970 epoch
+    attr_reader :last_modified_time
+
+    ##
+    # The tags applied to the note
+    #
+    # TODO: a setter method for the tags of the note
+    attr_reader :tags
+
+    ##
+    # The deck that the note's cards will be put into when saved
+    attr_reader :deck
+
+    ##
+    # The note type of the note
+    attr_reader :note_type
+
+    ##
+    # The card objects of the note
+    attr_reader :cards
+
+    ##
+    # Instantiate a new note for a deck and note type
+    # or TODO: instantiate a new object from an already existing record
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+    def initialize(deck:, note_type:)
+      raise ArgumentError unless deck && note_type && deck.collection == note_type.collection
+
+      @apkg = deck.collection.anki_package
+
+      @id = milliseconds_since_epoch
+      @guid = globally_unique_id
+      @last_modified_time = seconds_since_epoch
+      @usn = NEW_OBJECT_USN
+      @tags = []
+      @deck = deck
+      @note_type = note_type
+      @field_contents = setup_field_contents
+      @cards = @note_type.card_templates.map { |card_template| Card.new(note: self, card_template: card_template) }
+    end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize
+
+    ##
+    # Save the note to the collection.anki21 database
+    def save
+      @apkg.execute <<~SQL
+        insert into notes (id, guid, mid, mod, usn, tags, flds, sfld, csum, flags, data)
+                    values ('#{@id}', '#{@guid}', '#{note_type.id}', '#{@last_modified_time}', '#{@usn}', '#{@tags.join(" ")}', '#{field_values_separated_by_us}', '#{sort_field_value}', '#{checksum(sort_field_value)}', '0', '')
+      SQL
+      cards.each(&:save)
+      true
+    end
+
+    ##
+    # This overrides BasicObject#method_missing and has the effect of creating "ghost methods"
+    #
+    # Specifically, creates setter and getter ghost methods for the fields of the note's note type
+    #
+    # TODO: This should raise a NoMethodError if
+    # the missing method does not end with '=' and is not a field of the note type
+    def method_missing(method_name, field_content = nil)
+      method_name = method_name.to_s
+      return @field_contents[method_name] unless method_name.end_with?("=")
+
+      method_name = method_name.chomp("=")
+      valid_fields_snake_names = @field_contents.keys
+      unless valid_fields_snake_names.include?(method_name)
+        raise ArgumentError, "Valid fields for the #{note_type.name} note type are one of #{valid_fields_snake_names.join(", ")}"
+      end
+
+      @field_contents[method_name] = 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 setup_field_contents
+        field_contents = {}
+        note_type.snake_case_field_names.each do |field_name|
+          field_contents[field_name] = ""
+        end
+        field_contents
+      end
+
+      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

data/lib/anki_record/note_field.rb

@@ -14,17 +14,37 @@ module AnkiRecord
     DEFAULT_FIELD_DESCRIPTION = ""
     private_constant :DEFAULT_FIELD_FONT_STYLE, :DEFAULT_FIELD_FONT_SIZE, :DEFAULT_FIELD_DESCRIPTION
 
+    ##
+    # The note type that the note field belongs to
+    attr_reader :note_type
+
     ##
     # The name of the note field
     attr_accessor :name
 
     ##
-    # One of many attributes that is readable and writeable but needs to be documented
-    attr_accessor :sticky, :right_to_left, :font_style, :font_size, :description
+    # A boolean that indicates if this field is sticky when adding cards of the note type in Anki
+    attr_accessor :sticky
+
+    ##
+    # A boolean that indicates if this field should be right to left
+    attr_accessor :right_to_left
+
+    ##
+    # The font style used when editing the note field
+    attr_accessor :font_style
+
+    ##
+    # The font size used when editing the note field
+    attr_accessor :font_size
+
+    ##
+    # The description of the note field
+    attr_accessor :description
 
     ##
-    # One of many attributes that is currently read-only and needs to be documented.
-    attr_reader :note_type, :ordinal_number
+    # 0 for the first field of the note type, 1 for the second, etc.
+    attr_reader :ordinal_number
 
     ##
     # Instantiates a new field for the given note type
@@ -48,6 +68,7 @@ module AnkiRecord
         @right_to_left = args["rtl"]
         @font_style = args["font"]
         @font_size = args["size"]
+        @description = args["description"]
       end
 
       def setup_note_field_instance_variables(name:)

data/lib/anki_record/note_type.rb

@@ -7,8 +7,6 @@ require_relative "helpers/shared_constants_helper"
 require_relative "helpers/time_helper"
 require_relative "note_field"
 
-# TODO: All instance variables should at least be readable
-
 module AnkiRecord
   ##
   # NoteType represents an Anki note type (also called a model)
@@ -19,20 +17,54 @@ module AnkiRecord
     private_constant :NEW_NOTE_TYPE_SORT_FIELD
 
     ##
-    # The name of this note type
+    # The collection object that the note type belongs to
+    attr_reader :collection
+
+    ##
+    # The id of the note type
+    attr_reader :id
+
+    ##
+    # The name of the note type
     attr_accessor :name
 
     ##
-    # true if the note type is a cloze note type and false if it is not
+    # A boolean that indicates if this note type is a cloze-deletion note type
     attr_accessor :cloze
 
     ##
-    # One of many attributes that is readable and writeable but needs to be documented
-    attr_accessor :css, :latex_preamble, :latex_postamble, :latex_svg
+    # The CSS styling of the note type
+    attr_reader :css
+
+    ##
+    # The LaTeX preamble of the note type
+    attr_reader :latex_preamble
+
+    ##
+    # The LaTeX postamble of the note type
+    attr_reader :latex_postamble
+
+    ##
+    # A boolean probably related to something with LaTeX and SVG.
+    #
+    # TODO: Investigate what this does
+    attr_reader :latex_svg
+
+    ##
+    # An array of the card template objects belonging to the note type
+    attr_reader :card_templates
 
     ##
-    # One of many attributes that is currently read-only and needs to be documented.
-    attr_reader :id, :templates, :fields, :deck_id
+    # An array of the field names of the card template
+    attr_reader :fields
+
+    ##
+    # TODO: Investigate the meaning of the deck id of a note type
+    attr_reader :deck_id
+
+    ##
+    # TODO: Investigate the meaning of tags of a note type
+    attr_reader :tags
 
     ##
     # Instantiates a new note type
@@ -44,19 +76,19 @@ module AnkiRecord
       if args
         setup_note_type_instance_variables_from_existing(args: args)
       else
-        setup_note_type_instance_variables(
-          name: name, cloze: cloze
-        )
+        setup_note_type_instance_variables(name: name, cloze: cloze)
       end
     end
 
     ##
-    # Create a new field and adds it to this note type's fields
+    # Creates a new field and adds it to this note type's fields
     #
     # The field is an instance of AnkiRecord::NoteField
     def new_note_field(name:)
-      # TODO: Check if name already used by a field in this note type
-      @fields << AnkiRecord::NoteField.new(note_type: self, name: name)
+      # TODO: Raise an exception if the name is already used by a field in this note type
+      note_field = AnkiRecord::NoteField.new(note_type: self, name: name)
+      @fields << note_field
+      note_field
     end
 
     ##
@@ -64,8 +96,65 @@ module AnkiRecord
     #
     # The card template is an instance of AnkiRecord::CardTemplate
     def new_card_template(name:)
-      # TODO: Check if name already used by a template in this note type
-      @templates << AnkiRecord::CardTemplate.new(note_type: self, name: name)
+      # TODO: Raise an exception if the name is already used by a template in this note type
+      card_template = AnkiRecord::CardTemplate.new(note_type: self, name: name)
+      @card_templates << card_template
+      card_template
+    end
+
+    ##
+    # Find one of the note type's card templates by name
+    def find_card_template_by(name:)
+      card_templates.find { |template| template.name == name }
+    end
+
+    ##
+    # The field names of the note type ordered by their ordinal values
+    def field_names_in_order
+      @fields.sort_by(&:ordinal_number).map(&:name)
+    end
+
+    ##
+    # The allowed field names of the note in snake_case
+    #
+    # TODO: make this more robust... what happens when the note type name has non-alphabetic characters?
+    def snake_case_field_names
+      field_names_in_order.map { |field_name| field_name.downcase.gsub(" ", "_") }
+    end
+
+    ##
+    # The name of the field used to sort notes of the note type in the Anki browser
+    def sort_field_name
+      @fields.find { |field| field.ordinal_number == @sort_field }&.name
+    end
+
+    ##
+    # The name of the sort field in snake_case
+    def snake_case_sort_field_name
+      sort_field_name.downcase.gsub(" ", "_")
+    end
+
+    ##
+    # The allowed field_name values in {{field_name}} of the note type's card templates' question format
+    #
+    # These are the note type's fields' names, and if the note type is a cloze type,
+    # these also include the note type's fields' names prepended with 'cloze:'.
+    #
+    # TODO: research if other special field names like e.g. 'FrontSide' are allowed
+    def allowed_card_template_question_format_field_names
+      allowed = field_names_in_order
+      cloze ? allowed + field_names_in_order.map { |field_name| "cloze:#{field_name}" } : allowed
+    end
+
+    ##
+    # The allowed field_name values in {{field_name}} of the note type's card templates' answer format
+    #
+    # These are the note type's fields' names, and if the note type is a cloze type,
+    # these also include the note type's fields' names prepended with 'cloze:'.
+    #
+    # TODO: research if other special field names like e.g. 'FrontSide' are allowed
+    def allowed_card_template_answer_format_field_names
+      allowed_card_template_question_format_field_names + ["FrontSide"]
     end
 
     private
@@ -81,7 +170,7 @@ module AnkiRecord
         @sort_field = args["sortf"]
         @deck_id = args["did"]
         @fields = args["flds"].map { |fld| NoteField.new(note_type: self, args: fld) }
-        @templates = args["tmpls"].map { |tmpl| CardTemplate.new(note_type: self, args: tmpl) }
+        @card_templates = args["tmpls"].map { |tmpl| CardTemplate.new(note_type: self, args: tmpl) }
         @css = args["css"]
         @latex_preamble = args["latexPre"]
         @latex_postamble = args["latexPost"]
@@ -103,7 +192,7 @@ module AnkiRecord
         @sort_field = NEW_NOTE_TYPE_SORT_FIELD
         @deck_id = nil
         @fields = []
-        @templates = []
+        @card_templates = []
         @css = default_css
         @latex_preamble = default_latex_preamble
         @latex_postamble = default_latex_postamble
@@ -114,7 +203,6 @@ module AnkiRecord
       end
       # rubocop:enable Metrics/MethodLength
 
-      # TODO: use constant here
       def default_css
         <<-CSS
         .card {
@@ -125,7 +213,6 @@ module AnkiRecord
         CSS
       end
 
-      # TODO: use constant here
       def default_latex_preamble
         <<-LATEX_PRE
         \\documentclass[12pt]{article}
@@ -137,7 +224,6 @@ module AnkiRecord
         LATEX_PRE
       end
 
-      # TODO: use constant here
       def default_latex_postamble
         <<-LATEX_POST
         \\end{document}

data/lib/anki_record/version.rb

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

data/lib/anki_record.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "securerandom"
 require "sqlite3"
 require "zip"
 
@@ -10,10 +9,12 @@ require_relative "anki_record/version"
 ##
 # This module is the namespace for all AnkiRecord classes:
 # - AnkiPackage
+# - Card
 # - CardTemplate
 # - Collection
 # - DeckOptionsGroup
 # - Deck
+# - Note
 # - NoteField
 # - NoteType
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anki_record
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Kyle Rego
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-02-24 00:00:00.000000000 Z
+date: 2023-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -28,16 +28,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
 description: "  This Ruby library, which is currently in development, will provide
   an interface to inspect, update, and create Anki SQLite3 databases (*.apkg files).\n"
 email:
@@ -46,7 +46,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rdoc_options"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -59,6 +58,7 @@ files:
 - anki_record.gemspec
 - lib/anki_record.rb
 - lib/anki_record/anki_package.rb
+- lib/anki_record/card.rb
 - lib/anki_record/card_template.rb
 - lib/anki_record/collection.rb
 - lib/anki_record/db/anki_schema_definition.rb
@@ -66,8 +66,10 @@ files:
 - lib/anki_record/db/clean_collection2_record.rb
 - lib/anki_record/deck.rb
 - lib/anki_record/deck_options_group.rb
+- lib/anki_record/helpers/checksum_helper.rb
 - lib/anki_record/helpers/shared_constants_helper.rb
 - lib/anki_record/helpers/time_helper.rb
+- lib/anki_record/note.rb
 - lib/anki_record/note_field.rb
 - lib/anki_record/note_type.rb
 - lib/anki_record/version.rb
@@ -94,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.4.6
 signing_key: 
 specification_version: 4
 summary: Automate Anki flashcard editing with the Ruby programming language.

data/.rdoc_options

@@ -1,27 +0,0 @@
----
-encoding: UTF-8
-static_path: []
-rdoc_include: []
-page_dir: 
-charset: UTF-8
-exclude:
-- "~\\z"
-- "\\.orig\\z"
-- "\\.rej\\z"
-- "\\.bak\\z"
-- "\\.gemspec\\z"
-hyperlink_all: false
-line_numbers: false
-locale: 
-locale_dir: locale
-locale_name: 
-main_page: 
-markup: rdoc
-output_decoration: true
-show_hash: false
-skip_tests: true
-tab_width: 8
-template_stylesheets: []
-title: 
-visibility: :protected
-webcvs: