Module: AnkiConnect::Client::Notes

Included in:
AnkiConnect::Client
Defined in:
lib/anki_connect/notes.rb

Overview

Methods to create, update, query, and manage notes (which generate cards).

Instance Method Summary collapse

Instance Method Details

#add_note(deck_name:, model_name:, fields:, tags: [], media: nil, options: nil) ⇒ Integer?

Creates a new note.

Parameters:

  • deck_name (String) —

    Target deck

  • model_name (String) —

    Note type

  • fields (Hash) —

    Field names to values

  • tags (Array<String>) (defaults to: []) —

    Tags (optional)

  • media (Hash, nil) (defaults to: nil) —

    Media to add (audio:, video:, picture: arrays)

  • options (Hash, nil) (defaults to: nil) —

    Options (allowDuplicate, duplicateScope, etc.)

Returns:

  • (Integer, nil) —

    Note ID on success, nil on failure



16
17
18
19
20
21
 
# File 'lib/anki_connect/notes.rb', line 16

def add_note(deck_name:, model_name:, fields:, tags: [], media: nil, options: nil)
  note = { deckName: deck_name, modelName: model_name, fields: fields, tags: tags }
  note.merge!(media) if media
  note[:options] = options if options
  request(:addNote, note: note)
end

#add_notes(notes) ⇒ Array<Integer, nil>

Creates multiple notes.

Parameters:

  • notes (Array<Hash>) —

    Array of note hashes (same keys as add_note)

Returns:

  • (Array<Integer, nil>) —

    Array of note IDs (nil for failed notes)



27
28
29
 
# File 'lib/anki_connect/notes.rb', line 27

def add_notes(notes)
  request(:addNotes, notes: notes)
end

#add_tags(note_ids, tags) ⇒ nil

Adds tags to notes.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

  • tags (String, Array<String>) —

    Tag(s) to add

Returns:

  • (nil) 


83
84
85
 
# File 'lib/anki_connect/notes.rb', line 83

def add_tags(note_ids, tags)
  request(:addTags, notes: note_ids, tags: tags)
end

#all_tags ⇒ Array<String>

Gets all tags in collection.

Returns:

  • (Array<String>) —

    Array of all tag strings



99
100
101
 
# File 'lib/anki_connect/notes.rb', line 99

def all_tags
  request(:getTags)
end

#can_add_notes(notes, details: false) ⇒ Array<Boolean>, Array<Hash>

Checks if notes can be added.

Parameters:

  • notes (Array<Hash>) —

    Array of candidate note objects

  • details (Boolean) (defaults to: false) —

    If true, returns error details (default: false)

Returns:

  • (Array<Boolean>, Array<Hash>) —

    Array of booleans, or hashes with canAdd and error if details=true



36
37
38
39
40
41
42
 
# File 'lib/anki_connect/notes.rb', line 36

def can_add_notes(notes, details: false)
  if details
    request(:canAddNotesWithErrorDetail, notes: notes)
  else
    request(:canAddNotes, notes: notes)
  end
end

#change_note_model(id, model_name:, fields:, tags:) ⇒ nil

Changes a note’s model type.

Parameters:

  • id (Integer) —

    Note ID

  • model_name (String) —

    New model name

  • fields (Hash) —

    New field values

  • tags (Array<String>) —

    New tags

Returns:

  • (nil) 


66
67
68
 
# File 'lib/anki_connect/notes.rb', line 66

def change_note_model(id, model_name:, fields:, tags:)
  request(:updateNoteModel, note: { id: id, modelName: model_name, fields: fields, tags: tags })
end

#clear_unused_tags ⇒ nil

Removes unused tags from collection.

Returns:

  • (nil) 


106
107
108
 
# File 'lib/anki_connect/notes.rb', line 106

def clear_unused_tags
  request(:clearUnusedTags)
end

#delete_notes(note_ids) ⇒ nil

Deletes notes and all associated cards.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

Returns:

  • (nil) 


156
157
158
 
# File 'lib/anki_connect/notes.rb', line 156

def delete_notes(note_ids)
  request(:deleteNotes, notes: note_ids)
end

#get_note_tags(note_id) ⇒ Array<String>

Gets tags for a note.

Parameters:

  • note_id (Integer) —

    Note ID

Returns:

  • (Array<String>) —

    Array of tag strings



74
75
76
 
# File 'lib/anki_connect/notes.rb', line 74

def get_note_tags(note_id)
  request(:getNoteTags, note: note_id)
end

#get_notes(note_ids: nil, query: nil) ⇒ Array<Hash>

Gets detailed information about notes.

Parameters:

  • note_ids (Array<Integer>, nil) (defaults to: nil) —

    Array of note IDs

  • query (String, nil) (defaults to: nil) —

    Search query string

Returns:

  • (Array<Hash>) —

    Array of note objects



137
138
139
140
141
142
 
# File 'lib/anki_connect/notes.rb', line 137

def get_notes(note_ids: nil, query: nil)
  params = {}
  params[:notes] = note_ids if note_ids
  params[:query] = query if query
  request(:notesInfo, **params)
end

#get_notes_mod_time(note_ids) ⇒ Array<Hash>

Gets modification times for notes.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

Returns:

  • (Array<Hash>) —

    Array of objects with noteId and mod



148
149
150
 
# File 'lib/anki_connect/notes.rb', line 148

def get_notes_mod_time(note_ids)
  request(:notesModTime, notes: note_ids)
end

#remove_empty_notes ⇒ nil

Removes all empty notes.

Returns:

  • (nil) 


163
164
165
 
# File 'lib/anki_connect/notes.rb', line 163

def remove_empty_notes
  request(:removeEmptyNotes)
end

#remove_tags(note_ids, tags) ⇒ nil

Removes tags from notes.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

  • tags (String, Array<String>) —

    Tag(s) to remove

Returns:

  • (nil) 


92
93
94
 
# File 'lib/anki_connect/notes.rb', line 92

def remove_tags(note_ids, tags)
  request(:removeTags, notes: note_ids, tags: tags)
end

#replace_tag(from:, to:, note_ids: nil) ⇒ nil

Replaces a tag with another.

Parameters:

  • from (String) —

    Old tag

  • to (String) —

    New tag

  • note_ids (Array<Integer>, nil) (defaults to: nil) —

    Specific notes, or nil for all notes

Returns:

  • (nil) 


116
117
118
119
120
121
122
 
# File 'lib/anki_connect/notes.rb', line 116

def replace_tag(from:, to:, note_ids: nil)
  if note_ids
    request(:replaceTags, notes: note_ids, tag_to_replace: from, replace_with_tag: to)
  else
    request(:replaceTagsInAllNotes, tag_to_replace: from, replace_with_tag: to)
  end
end

#search_notes(query) ⇒ Array<Integer>

Searches for notes matching a query.

Parameters:

  • query (String) —

    Search query string

Returns:

  • (Array<Integer>) —

    Array of note IDs



128
129
130
 
# File 'lib/anki_connect/notes.rb', line 128

def search_notes(query)
  request(:findNotes, query: query)
end

#update_note(id, fields: nil, tags: nil, media: nil) ⇒ nil

Updates a note’s fields, tags, or media.

Parameters:

  • id (Integer) —

    Note ID

  • fields (Hash, nil) (defaults to: nil) —

    Field names to new values

  • tags (Array<String>, nil) (defaults to: nil) —

    New tags (replaces existing)

  • media (Hash, nil) (defaults to: nil) —

    Media to add (audio:, video:, picture: arrays)

Returns:

  • (nil) 


51
52
53
54
55
56
57
 
# File 'lib/anki_connect/notes.rb', line 51

def update_note(id, fields: nil, tags: nil, media: nil)
  note = { id: id }
  note[:fields] = fields if fields
  note[:tags] = tags if tags
  note.merge!(media) if media
  request(:updateNote, note: note)
end