anki_record 0.2.0 → 0.3.1

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

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 Helpers::SharedConstantsHelper
+    include Helpers::TimeHelper
+    include NoteTypeAttributes
+    include 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.2.0" # :nodoc:
+  VERSION = "0.3.1" # :nodoc:
 end

data/lib/anki_record.rb

@@ -3,24 +3,9 @@
 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
-# - Card
-# - CardTemplate
-# - Collection
-# - DeckOptionsGroup
-# - Deck
-# - Note
-# - 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.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Kyle Rego
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-03-05 00:00:00.000000000 Z
+date: 2023-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-description: "  This Ruby library, which is currently in development, will provide
-  an interface to inspect, update, and create Anki SQLite3 databases (*.apkg files).\n"
+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: []
@@ -57,21 +57,31 @@ files:
 - Rakefile
 - 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
-- 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/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/database_setup_constants.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.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:

data/lib/anki_record/anki_package.rb

@@ -1,194 +0,0 @@
-# frozen_string_literal: true
-
-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"
-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
-
-    ##
-    # The collection object of the package
-    attr_reader :collection
-
-    ##
-    # 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 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)
-
-      execute_closure_and_zip(self, &closure) if block_given?
-    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 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
-        @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:, target_directory: nil, &closure)
-      pathname = check_file_at_path_is_valid(path: path)
-      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:)
-          pathname = Pathname.new(path)
-          raise PATH_ERROR_MESSAGE unless pathname.file? && pathname.extname == ".apkg"
-
-          pathname
-        end
-    end
-
-    ##
-    # Zips the temporary files into the *.apkg package and deletes the temporary files.
-    def zip
-      create_zip_file && destroy_temporary_directory
-    end
-
-    private
-
-      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))
-          end
-        end
-        true
-      end
-
-      def target_zip_file
-        "#{@directory}/#{@name}.apkg"
-      end
-
-      def destroy_temporary_directory
-        @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