anki_record 0.1.1 → 0.3.0

data/lib/anki_record/note_type/note_type.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "../card_template/card_template"
+require_relative "../helpers/shared_constants_helper"
+require_relative "../helpers/time_helper"
+require_relative "../note_field/note_field"
+require_relative "note_type_attributes"
+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 AnkiRecord::SharedConstantsHelper
+    include AnkiRecord::TimeHelper
+    include AnkiRecord::NoteTypeAttributes
+    include AnkiRecord::NoteTypeDefaults
+
+    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)
+      raise ArgumentError unless (name && args.nil?) || (args && args["name"])
+
+      @collection = collection
+
+      if args
+        setup_note_type_instance_variables_from_existing(args: args)
+      else
+        setup_instance_variables_for_new_note_type(name: name)
+      end
+
+      @collection.add_note_type self
+      save
+    end
+
+    ##
+    # Saves the note type to the collection.anki21 database
+    def save
+      collection_models_hash = collection.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])
+    end
+
+    def to_h # :nodoc:
+      self_to_h = { id: @id, name: @name, type: @cloze ? 1 : 0,
+                    mod: @last_modified_timestamp, usn: @usn, sortf: @sort_field, did: @deck_id,
+                    tmpls: @card_templates.map(&:to_h), flds: @note_fields.map(&:to_h), css: @css,
+                    latexPre: @latex_preamble, latexPost: @latex_postamble, latexsvg: @latex_svg,
+                    req: @req }
+      self_to_h.merge({ tags: @tags, vers: @vers }) unless NOTE_TYPES_WITHOUT_TAGS_AND_VERS_VALUES.include?(@name)
+      self_to_h
+    end
+
+    ##
+    # Returns the note type object's card template with name +name+ or nil if it is not found
+    def find_card_template_by(name:)
+      card_templates.find { |template| template.name == name }
+    end
+
+    ##
+    # Returns an array of the note type's fields' names ordered by field ordinal values.
+    def field_names_in_order
+      @note_fields.sort_by(&:ordinal_number).map(&:name)
+    end
+
+    def snake_case_field_names # :nodoc:
+      field_names_in_order.map { |field_name| field_name.downcase.gsub(" ", "_") }
+    end
+
+    ##
+    # Returns the name of the note type's field used to sort notes in the browser.
+    def sort_field_name
+      @note_fields.find { |field| field.ordinal_number == @sort_field }&.name
+    end
+
+    def snake_case_sort_field_name # :nodoc:
+      sort_field_name.downcase.gsub(" ", "_")
+    end
+
+    ##
+    # Returns allowed field_name values in {{field_name}} in the question format.
+    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
+
+    ##
+    # Returns allowed field_name values in {{field_name}} in the answer format.
+    def allowed_card_template_answer_format_field_names
+      allowed_card_template_question_format_field_names + ["FrontSide"]
+    end
+
+    def add_note_field(note_field) # :nodoc:
+      raise ArgumentError unless note_field.instance_of?(AnkiRecord::NoteField)
+
+      @note_fields << note_field
+    end
+
+    def add_card_template(card_template) # :nodoc:
+      raise ArgumentError unless card_template.instance_of?(AnkiRecord::CardTemplate)
+
+      @card_templates << card_template
+    end
+
+    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)
+      end
+
+      def setup_collaborator_object_instance_variables_from_existing(args:)
+        @note_fields = []
+        args["flds"].each { |fld| NoteField.new(note_type: self, args: fld) }
+        @card_templates = []
+        args["tmpls"].each { |tmpl| CardTemplate.new(note_type: self, args: tmpl) }
+      end
+
+      def setup_simple_instance_variables_from_existing(args:)
+        %w[id name usn css req tags vers].each do |note_type_attribute|
+          instance_variable_set "@#{note_type_attribute}", args[note_type_attribute]
+        end
+        @cloze = args["type"] == 1
+        @last_modified_timestamp = args["mod"]
+        @sort_field = args["sortf"]
+        @deck_id = args["did"]
+        @latex_preamble = args["latexPre"]
+        @latex_postamble = args["latexPost"]
+        @latex_svg = args["latexsvg"]
+      end
+
+      def setup_instance_variables_for_new_note_type(name:)
+        @name = name
+        @cloze = false
+        setup_collaborator_object_instance_variables_for_new_note_type
+        setup_simple_instance_variables_for_new_note_type
+      end
+
+      def setup_collaborator_object_instance_variables_for_new_note_type
+        @note_fields = []
+        @card_templates = []
+      end
+
+      def setup_simple_instance_variables_for_new_note_type
+        @id = milliseconds_since_epoch
+        @last_modified_timestamp = seconds_since_epoch
+        @usn = NEW_OBJECT_USN
+        @sort_field = default_note_type_sort_field
+        @deck_id = @tags = @vers = nil
+        @css = default_css
+        @latex_preamble = default_latex_preamble
+        @latex_postamble = default_latex_postamble
+        @latex_svg = false
+        @req = []
+      end
+  end
+end

data/lib/anki_record/note_type/note_type_attributes.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  ##
+  # Module with the NoteType class's attribute readers, writers, and accessors.
+  module NoteTypeAttributes
+    ##
+    # The note type's collection object.
+    attr_reader :collection
+
+    ##
+    # The note type's id.
+    attr_reader :id
+
+    ##
+    # The note type's name.
+    attr_accessor :name
+
+    ##
+    # 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.
+    attr_reader :last_modified_timestamp
+
+    ##
+    # The note type's update sequence number.
+    attr_reader :usn
+
+    ##
+    # The note type's sort field.
+    attr_reader :sort_field
+
+    ##
+    # The note type's CSS.
+    attr_accessor :css
+
+    ##
+    # The note type's LaTeX preamble.
+    attr_reader :latex_preamble
+
+    ##
+    # The note type's LaTeX postamble.
+    attr_reader :latex_postamble
+
+    ##
+    # The note type's card template objects, as an array.
+    attr_reader :card_templates
+
+    ##
+    # The note type's field objects, as an array.
+    attr_reader :note_fields
+
+    ##
+    # The note type's deck's id.
+    attr_reader :deck_id
+
+    ##
+    # The note type's deck.
+    def deck
+      return nil unless @deck_id
+
+      @collection.find_deck_by id: @deck_id
+    end
+
+    ##
+    # Sets the note type's deck object.
+    def deck=(deck)
+      unless deck.instance_of?(AnkiRecord::Deck)
+        raise ArgumentError,
+              "You can only set this attribute to an instance of AnkiRecord::Deck."
+      end
+
+      @deck_id = deck.id
+    end
+
+    attr_reader :latex_svg, :tags, :req, :vers
+  end
+end

data/lib/anki_record/note_type/note_type_defaults.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AnkiRecord
+  module NoteTypeDefaults # :nodoc:
+    private
+
+      def default_note_type_sort_field
+        0
+      end
+
+      def default_css
+        <<~CSS
+          .card {
+            color: black;
+            background-color: transparent;
+            text-align: center;
+          }
+        CSS
+      end
+
+      def default_latex_preamble
+        <<~LATEX_PRE
+          \\documentclass[12pt]{article}
+          \\special{papersize=3in,5in}
+          \\usepackage{amssymb,amsmath}
+          \\pagestyle{empty}
+          \\setlength{\\parindent}{0in}
+          \\begin{document}
+        LATEX_PRE
+      end
+
+      def default_latex_postamble
+        <<~LATEX_POST
+          \\end{document}
+        LATEX_POST
+      end
+  end
+end

data/lib/anki_record/version.rb

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

data/lib/anki_record.rb

@@ -1,25 +1,11 @@
 # frozen_string_literal: true
 
-require "securerandom"
 require "sqlite3"
 require "zip"
 
-require_relative "anki_record/anki_package"
+require_relative "anki_record/anki_package/anki_package"
 require_relative "anki_record/version"
 
-##
-# This module is the namespace for all AnkiRecord classes:
-# - AnkiPackage
-# - CardTemplate
-# - Collection
-# - DeckOptionsGroup
-# - Deck
-# - NoteField
-# - NoteType
-#
-# And modules:
-# - SharedConstantsHelper
-# - TimeHelper
 module AnkiRecord
   class Error < StandardError; end # :nodoc:
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anki_record
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kyle Rego
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-02-24 00:00:00.000000000 Z
+date: 2023-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -28,25 +28,24 @@ 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'
-description: "  This Ruby library, which is currently in development, will provide
-  an interface to inspect, update, and create Anki SQLite3 databases (*.apkg files).\n"
+        version: '1.3'
+description: "  A Ruby library which provides a programmatic interface to Anki flashcard
+  decks (.apkg files/zipped Anki SQLite databases).\n"
 email:
 - regoky@outlook.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rdoc_options"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -58,18 +57,31 @@ files:
 - Rakefile
 - anki_record.gemspec
 - lib/anki_record.rb
-- lib/anki_record/anki_package.rb
-- lib/anki_record/card_template.rb
-- lib/anki_record/collection.rb
-- lib/anki_record/db/anki_schema_definition.rb
-- lib/anki_record/db/clean_collection21_record.rb
-- lib/anki_record/db/clean_collection2_record.rb
-- lib/anki_record/deck.rb
-- lib/anki_record/deck_options_group.rb
+- lib/anki_record/anki_package/anki_package.rb
+- lib/anki_record/anki_package/database_setup_constants.rb
+- lib/anki_record/card/card.rb
+- lib/anki_record/card/card_attributes.rb
+- lib/anki_record/card_template/card_template.rb
+- lib/anki_record/card_template/card_template_attributes.rb
+- lib/anki_record/collection/collection.rb
+- lib/anki_record/collection/collection_attributes.rb
+- lib/anki_record/deck/deck.rb
+- lib/anki_record/deck/deck_attributes.rb
+- 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/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/note_field.rb
-- lib/anki_record/note_type.rb
+- lib/anki_record/note/note.rb
+- lib/anki_record/note/note_attributes.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
+- lib/anki_record/note_type/note_type.rb
+- lib/anki_record/note_type/note_type_attributes.rb
+- lib/anki_record/note_type/note_type_defaults.rb
 - lib/anki_record/version.rb
 homepage: https://github.com/KyleRego/anki_record
 licenses:
@@ -94,7 +106,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: 

data/lib/anki_record/anki_package.rb

@@ -1,183 +0,0 @@
-# frozen_string_literal: true
-
-require "pry"
-require "pathname"
-
-require_relative "db/anki_schema_definition"
-require_relative "db/clean_collection2_record"
-require_relative "db/clean_collection21_record"
-require_relative "collection"
-
-module AnkiRecord
-  ##
-  # Represents an Anki SQLite3 package/database
-  #
-  # Use ::new to create a new object or ::open to create an object from an existing one
-  class AnkiPackage
-    NAME_ERROR_MESSAGE = "The name argument must be a string without spaces."
-    PATH_ERROR_MESSAGE = "*No .apkg file was found at the given path."
-    STANDARD_ERROR_MESSAGE = <<-MSG
-    An error occurred.
-    The temporary *.anki21 database has been deleted.
-    No *.apkg zip file has been saved.
-    MSG
-
-    private_constant :NAME_ERROR_MESSAGE, :PATH_ERROR_MESSAGE, :STANDARD_ERROR_MESSAGE
-
-    ##
-    # Creates a new object which represents an Anki SQLite3 database
-    #
-    # This method takes an optional block argument.
-    #
-    # When a block argument is used, execution is yielded to the block.
-    # After the block executes, the temporary files are zipped into the +name+.apkg file
-    # 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)
-      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
-    end
-
-    ##
-    # Executes a raw SQL statement against the *.anki21 database
-    #
-    # Do not use this to execute data definition language SQL statements
-    # (i.e. do not create, alter, or drop tables or indexes)
-    # unless you have a good reason to change the database schema.
-    def execute(raw_sql_string)
-      @anki21_database.execute raw_sql_string
-    end
-
-    private
-
-      def setup_package_instance_variables(name:, directory:)
-        @name = check_name_is_valid(name: name)
-        @directory = directory # TODO: check directory is valid
-        @tmpdir = Dir.mktmpdir
-        @tmp_files = []
-        @anki21_database = setup_anki21_database_object
-        @anki2_database = setup_anki2_database_object
-        @media_file = setup_media
-        @collection = Collection.new(anki_package: self)
-      end
-
-      def check_name_is_valid(name:)
-        raise ArgumentError, NAME_ERROR_MESSAGE unless name.instance_of?(String) && !name.empty? && !name.include?(" ")
-
-        name.end_with?(".apkg") ? name[0, name.length - 5] : name
-      end
-
-      def setup_anki21_database_object
-        anki21_file_name = "collection.anki21"
-        db = SQLite3::Database.new "#{@tmpdir}/#{anki21_file_name}", options: {}
-        @tmp_files << anki21_file_name
-        db.execute_batch ANKI_SCHEMA_DEFINITION
-        db.execute CLEAN_COLLECTION_21_RECORD
-        db.results_as_hash = true
-        db
-      end
-
-      def setup_anki2_database_object
-        anki2_file_name = "collection.anki2"
-        db = SQLite3::Database.new "#{@tmpdir}/#{anki2_file_name}", options: {}
-        @tmp_files << anki2_file_name
-        db.execute_batch ANKI_SCHEMA_DEFINITION
-        db.execute CLEAN_COLLECTION_2_RECORD
-        db.close
-        db
-      end
-
-      def setup_media
-        media_file_path = FileUtils.touch("#{@tmpdir}/media")[0]
-        media_file = File.open(media_file_path, mode: "w")
-        media_file.write("{}")
-        media_file.close
-        @tmp_files << "media"
-        media_file
-      end
-
-      def puts_error_and_standard_message(error:)
-        puts "#{error}\n#{STANDARD_ERROR_MESSAGE}"
-      end
-
-    public
-
-    ##
-    # 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)
-      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)
-    end
-
-    class << self
-      private
-
-        def check_file_at_path_is_valid(path:)
-          pathname = Pathname.new(path)
-          raise PATH_ERROR_MESSAGE unless pathname.file? && pathname.extname == ".apkg"
-
-          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
-    end
-
-    private
-
-      def zip
-        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))
-          end
-        end
-        true
-      end
-
-      def target_zip_file
-        "#{@directory}/#{@name}.apkg"
-      end
-
-      def close
-        @anki21_database.close
-        FileUtils.rm_rf(@tmpdir)
-      end
-
-    public
-
-    ##
-    # Returns true if the database is open
-    def open?
-      !closed?
-    end
-
-    ##
-    # Returns true if the database is closed
-    def closed?
-      @anki21_database.closed?
-    end
-  end
-end

data/lib/anki_record/collection.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require "pry"
-require "json"
-
-require_relative "deck"
-require_relative "deck_options_group"
-require_relative "helpers/time_helper"
-require_relative "note_type"
-
-module AnkiRecord
-  ##
-  # Collection represents the single record in the Anki database `col` table
-  class Collection
-    include AnkiRecord::TimeHelper
-
-    ##
-    # An array of the collection's note type objects
-    attr_reader :note_types
-
-    ##
-    # An array of the collection's deck objects
-    attr_reader :decks
-
-    ##
-    # Instantiates the collection object for the +anki_package+
-    def initialize(anki_package:)
-      setup_collection_instance_variables(anki_package: anki_package)
-    end
-
-    private
-
-      # rubocop:disable Metrics/MethodLength
-      # rubocop:disable Metrics/AbcSize
-      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
-        @scm = col_record["scm"]
-        @ver = col_record["ver"]
-        @dty = col_record["dty"]
-        @usn = col_record["usn"]
-        @ls = col_record["ls"]
-        @configuration = JSON.parse(col_record["conf"])
-        @note_types = JSON.parse(col_record["models"]).values.map do |model_hash|
-          NoteType.new(collection: self, args: model_hash)
-        end
-        @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|
-          DeckOptionsGroup.new(collection: self, args: dconf_hash)
-        end
-        @tags = JSON.parse(col_record["tags"])
-        remove_instance_variable(:@col_record)
-      end
-      # rubocop:enable Metrics/AbcSize
-      # rubocop:enable Metrics/MethodLength
-
-      def col_record
-        @col_record ||= @anki_package.execute("select * from col;").first
-      end
-  end
-end