From b3a01de8e6c50c2b5e27f72e07bba5187d27742a Mon Sep 17 00:00:00 2001 From: Thanos Apollo Date: Tue, 2 Jan 2024 11:12:54 +0200 Subject: Update docstrings - Update documentation for adding notes. - Replace Get -> Return --- gnosis.el | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 114 insertions(+), 22 deletions(-) diff --git a/gnosis.el b/gnosis.el index 2f846f6..e9b30f7 100644 --- a/gnosis.el +++ b/gnosis.el @@ -90,7 +90,7 @@ Example: (emacsql gnosis-db `[:update ,table :set ,value :where ,where])) (cl-defun gnosis-get (value table &optional (restrictions '1=1)) - "Get VALUE from TABLE, optionally with where RESTRICTIONS." + "Return VALUE from TABLE, optionally with where RESTRICTIONS." (caar (gnosis-select value table restrictions))) (defun gnosis-get-note-tags (id) @@ -256,13 +256,13 @@ Set SPLIT to t to split all input given." (message "Created deck '%s'" name))) (defun gnosis--get-deck-name () - "Get name from table DECKS." + "Return name from table DECKS." (when (equal (gnosis-select 'name 'decks) nil) (error "No decks found")) (completing-read "Deck: " (gnosis-select 'name 'decks))) (cl-defun gnosis--get-deck-id (&optional (deck (gnosis--get-deck-name))) - "Get id for DECK name." + "Return id for DECK name." (gnosis-get 'id 'decks `(= name ,deck))) (defun gnosis-delete-deck (deck) @@ -286,7 +286,9 @@ When called with a prefix, unsuspends all notes in deck." do (gnosis-update 'review-log `(= suspend ,suspend) `(= id ,(car note)))))) (defun gnosis-suspend-tag () - "Suspend all note(s) with tag." + "Suspend all note(s) with tag. + +When called with a prefix, unsuspends all notes for tag." (let ((notes (gnosis-select-by-tag (gnosis-tag-prompt nil t))) (suspend (if current-prefix-arg 0 1))) (cl-loop for note in notes @@ -308,7 +310,8 @@ When called with a prefix, unsuspends all notes in deck." DECK: Deck for new note. TYPE: Note type e.g \"mcq\" MAIN: Note's main part -OPTIONS: Note's options, e.g choices for mcq for or clozes for cloze type +OPTIONS: Note's options, e.g choices for mcq for OR hints for +cloze/basic type ANSWER: Correct answer for note, for MCQ is an integer while for cloze/basic a string/list of the right answer(s) EXTRA: Extra information to display after answering note @@ -328,7 +331,6 @@ SECOND-IMAGE: Image to display after user-input." ;; function, which prompts for user input and passes it to the hidden ;; function. - (cl-defun gnosis-add-note--mcq (&key deck question choices correct-answer extra (image nil) tags (suspend 0) (second-image nil)) "Create a NOTE with a list of multiple CHOICES. @@ -338,6 +340,8 @@ The user will be prompted to select the correct answer from a list of `CHOICES'. The `CORRECT-ANSWER' should be the index of the correct choice in the `CHOICES' list. Each note must correspond to one `DECK'. +`IMAGE' Image to display before user-input +`SECOND-IMAGE' Image to display after user-input `EXTRA' are extra information displayed after an answer is given. `TAGS' are used to organize questions. `SUSPEND' is a binary value, where 1 is for suspend." @@ -348,7 +352,16 @@ choice in the `CHOICES' list. Each note must correspond to one `DECK'. (gnosis-add-note-fields deck "mcq" question choices correct-answer extra tags suspend image second-image)) (defun gnosis-add-note-mcq () - "Add note(s) of type `MCQ' interactively to selected deck." + "Add note(s) of type `MCQ' interactively to selected deck. + +Create a note type MCQ for specified deck, that consists of: +STEM: The question or problem statement +OPTIONS: Options for the user to select +ANSWER: Answer is the NUMBER of the correct answer of OPTIONS. +EXTRA: Information to display after user-input +TAGS: Used to organize notes + +Refer to `gnosis-add-note--mcq' for more." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `MCQ' to `%s' deck? " deck)) (gnosis-add-note--mcq :deck deck @@ -360,11 +373,26 @@ choice in the `CHOICES' list. Each note must correspond to one `DECK'. (cl-defun gnosis-add-note--basic (&key deck question hint answer extra (image nil) tags (suspend 0) (second-image nil)) - "Add Basic type note." + "Add Basic type note. + +DECK: Deck name for note. +QUESTION: Quesiton to display for note. +ANSWER: Answer for QUESTION, which user will be prompted to type +HINT: Hint to display during review, before user-input. +EXTRA: Extra information to display after user-input/giving an answer. +IMAGE: Image to display before user-input. +TAGS: Tags used to organize notes +SUSPEND: Binary value of 0 & 1, when 1 note will be ignored." (gnosis-add-note-fields deck "basic" question hint answer extra tags suspend image second-image)) (defun gnosis-add-note-basic () - "Add note(s) of type `Basic' interactively to selected deck." + "Add note(s) of type `Basic' interactively to selected deck. + +Basic note type is a flashcard-like note, where user first sees a +\"main\" part, which is usually a question, and he is prompted to +input the answer. + +Refer to `gnosis-add-note--basic' for more." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `basic' to `%s' deck? " deck)) (gnosis-add-note--basic :deck deck @@ -377,7 +405,7 @@ choice in the `CHOICES' list. Each note must correspond to one `DECK'. (cl-defun gnosis-add-note--double (&key deck question hint answer extra (image nil) tags (suspend 0) (second-image nil)) "Add Double type note. -Essentially, a note that creates 2 basic notes. The second one +Essentially, a \"note\" that generates 2 basic notes. The second one reverses question/answer. DECK: Deck name for note. @@ -387,12 +415,17 @@ HINT: Hint to display during review, before user-input. EXTRA: Extra information to display after user-input/giving an answer. IMAGE: Image to display before user-input. TAGS: Tags used to organize notes -SUSPEND: When t, note will be ignored for reviews." +SUSPEND: Binary value of 0 & 1, when 1 note will be ignored." (gnosis-add-note-fields deck "basic" question hint answer extra tags suspend image second-image) (gnosis-add-note-fields deck "basic" answer hint question extra tags suspend image second-image)) (defun gnosis-add-note-double () - "Add note(s) of type double interactively to selected deck." + "Add note(s) of type double interactively to selected deck. + +Essentially, a \"note\" that generates 2 basic notes. The second one +reverses question/answer. + +Refer to `gnosis-add-note--double' for more." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `double' to `%s' deck? " deck)) (gnosis-add-note--double :deck deck @@ -407,16 +440,65 @@ SUSPEND: When t, note will be ignored for reviews." (cl-defun gnosis-add-note--cloze (&key deck note hint tags (suspend 0) extra (image nil) (second-image nil)) "Add cloze type note. -`EXTRA' are extra information displayed after an answer is given. -`TAGS' are used to organize questions. -`SUSPEND' is a binary value, where 1 is for suspend." +DECK: Deck name for note. +NOTE: Note with clozes, format for clozes is as follows: + This is a {c1:cloze} note type. + This is a {{c1::cloze}} note type. + +Anki like syntax is supported with double brackes and colon, as well +as single brackets({}) and colon(:), or even a mix. + +For each cX: tag, there will be gerenated a cloze note type. +Example: + {c1:Preformed enterotoxins} from + {c2:Staphylococcus aureus} causes {c3:rapid} onset + food poisoning + +Generates 3 cloze note types. Where the \"main\" part of the note is the full +note, with the cloze(s) extracted & used as the \"answer\". + +One cloze note may have multiple clozes +Example: + {c1:Streptococcus agalactiae (GBS)} and {c1:Listeria + monocytogenes} are CAMP test positive + +HINT: Hint to display during review, before user-input. + NOTE! In gnosis-db, hint is referred to as `options', same column options used in mcq. +IMAGE: Image to display before user-input. +TAGS: Tags used to organize notes +SUSPEND: When t, note will be ignored. +EXTRA: Extra information displayed after user-input. +SECOND-IMAGE: Image to display after user-input." (let ((notags-note (gnosis-cloze-remove-tags note)) (clozes (gnosis-cloze-extract-answers note))) (cl-loop for cloze in clozes do (gnosis-add-note-fields deck "cloze" notags-note hint cloze extra tags suspend image second-image)))) (defun gnosis-add-note-cloze () - "Add note(s) of type cloze interactively to selected deck." + "Add note(s) of type cloze interactively to selected deck. + +Note with clozes, format for clozes is as follows: + This is a {c1:cloze} note type. + This is a {{c1::cloze}} note type. + +Anki like syntax is supported with double brackes and colon, as well +as single brackets({}) and colon(:), or even a mix. + +One cloze note may have multiple clozes +Example: + {c1:Streptococcus agalactiae (GBS)} and {c1:Listeria + monocytogenes} are CAMP test positive + +For each cX: tag, there will be gerenated a cloze note type. +Example: + {c1:Preformed enterotoxins} from + {c2:Staphylococcus aureus} causes {c3:rapid} onset + food poisoning + +Generates 3 cloze note types. Where the \"main\" part of the note is +the full note, with the cloze(s) extracted & used as the \"answer\". + +See `gnosis-add-note--cloze' for more reference." (let ((deck (gnosis--get-deck-name))) (while (y-or-n-p (format "Add note of type `cloze' to `%s' deck? " deck)) (gnosis-add-note--cloze :deck deck @@ -439,6 +521,19 @@ SUSPEND: When t, note will be ignored for reviews." ("Double" (gnosis-add-note-double)) (_ (message "No such type.")))) +(defun gnosis-export-deck (deck filename) + "Export DECK as FILENAME. + +Export all notes for DECK, in a file as FILENAME." + (interactive (list (gnosis--get-deck-id) + (read-string "Name for exported file: "))) + (let ((notes (gnosis-select '[type main options answer tags] 'notes `(= deck-id ,deck))) + (default-directory gnosis-dir)) + (with-temp-file (concat filename ".el") + (insert "(" (concat "gnosis-define-deck " "'" filename "\n")) + (insert (pp-to-string notes) "\n") + (insert ")" )))) + (defun gnosis-mcq-answer (id) "Choose the correct answer, from mcq choices for question ID." (let ((choices (gnosis-get 'options 'notes `(= id ,id))) @@ -565,7 +660,7 @@ Returns a list of unique tags." ;; Review ;;;;;;;;;; (defun gnosis-review--algorithm (id success) - "Get next review date & ef for note with value of id ID. + "Return next review date & ef for note with value of id ID. SUCCESS is a binary value, 1 = success, 0 = failure. Returns a list of the form ((yyyy mm dd) ef)." @@ -602,7 +697,7 @@ Select notes where: :test 'equal))) (defun gnosis-review--get-offset (id) - "Get offset for note with value of id ID." + "Return offset for note with value of id ID." (let ((last-rev (gnosis-get 'last-rev 'review-log `(= id ,id)))) (gnosis-algorithm-date-diff last-rev))) @@ -614,7 +709,7 @@ such as the easiness factor (ef)." (/ (round (* num 100.00)) 100.00)) (defun gnosis-review-new-ef (id success) - "Get new ef for note with value of id ID. + "Return new ef for note with value of id ID. SUCCESS is a binary value, 1 = success, 0 = failure. Returns a list of the form (ef-increase ef-decrease ef)." @@ -777,9 +872,6 @@ NOTE-NUM: The number of notes reviewed in the session." ("Notes with tag(s)" (gnosis-review--session (gnosis-select-by-tag (gnosis-tag-prompt nil t))))))) ;;; Database Schemas -;; Enable foreign_keys -;; TODO: Redo when eval - (defvar gnosis-db-schema-decks '([(id integer :primary-key :autoincrement) (name text :not-null)])) -- cgit v1.2.3