Module: AnkiConnect::Client::Cards

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

Overview

Methods to query, modify, suspend, and manage individual flashcards.

Instance Method Summary collapse

Instance Method Details

#answer_cards(answers) ⇒ Array<Boolean>

Answers cards programmatically.

Parameters:

  • answers (Array<Hash>) —

    Array of { card_id:, ease: } (1=Again, 2=Hard, 3=Good, 4=Easy)

Returns:

  • (Array<Boolean>) —

    Array indicating if each card exists



153
154
155
156
157
158
159
160
161
162
 
# File 'lib/anki_connect/cards.rb', line 153

def answer_cards(answers)
  normalized = answers.map do |answer|
    answer = normalize_keys(answer, ANSWER_KEYS, name: 'answer')
    missing_keys = ANSWER_KEYS.values.reject { |key| answer.key?(key) }
    raise ArgumentError, "missing answer keys: #{missing_keys.join(', ')}" unless missing_keys.empty?

    answer
  end
  request(:answerCards, answers: normalized)
end

#card_due?(card_id) ⇒ Boolean

Checks whether one card is due for review.

Parameters:

  • card_id (Integer) —

    Card ID

Returns:

  • (Boolean) —

    Due status



80
81
82
 
# File 'lib/anki_connect/cards.rb', line 80

def card_due?(card_id)
  request(:areDue, cards: [card_id]).first
end

#card_due_statuses(card_ids) ⇒ Array<Boolean>

Gets due status for each card, preserving input order.

Parameters:

  • card_ids (Array<Integer>) —

    Card IDs

Returns:

  • (Array<Boolean>) —

    Due statuses



88
89
90
 
# File 'lib/anki_connect/cards.rb', line 88

def card_due_statuses(card_ids)
  request(:areDue, cards: card_ids)
end

#card_intervals(card_ids, complete: false) ⇒ Array<Integer>+

Gets intervals for cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

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

    If true, returns all intervals

Returns:

  • (Array<Integer>, Array<Array<Integer>>) —

    Intervals



97
98
99
 
# File 'lib/anki_connect/cards.rb', line 97

def card_intervals(card_ids, complete: false)
  request(:getIntervals, cards: card_ids, complete: complete)
end

#card_modification_times(card_ids) ⇒ Array<Hash>

Gets modification times for cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (Array<Hash>) —

    Array of objects with cardId and mod



121
122
123
 
# File 'lib/anki_connect/cards.rb', line 121

def card_modification_times(card_ids)
  request(:cardsModTime, cards: card_ids)
end

#card_suspended?(card_id) ⇒ Boolean

Checks whether one card is suspended.

Parameters:

  • card_id (Integer) —

    Card ID

Returns:

  • (Boolean) —

    Suspension status



64
65
66
 
# File 'lib/anki_connect/cards.rb', line 64

def card_suspended?(card_id)
  request(:suspended, card: card_id)
end

#card_suspension_statuses(card_ids) ⇒ Array<Boolean, nil>

Gets suspension status for each card, preserving input order.

Parameters:

  • card_ids (Array<Integer>) —

    Card IDs

Returns:

  • (Array<Boolean, nil>) —

    Statuses; nil for missing cards



72
73
74
 
# File 'lib/anki_connect/cards.rb', line 72

def card_suspension_statuses(card_ids)
  request(:areSuspended, cards: card_ids)
end

#cards(card_ids) ⇒ Array<Hash>

Gets detailed information about cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (Array<Hash>) —

    Array of card objects



129
130
131
 
# File 'lib/anki_connect/cards.rb', line 129

def cards(card_ids)
  request(:cardsInfo, cards: card_ids)
end

#ease_factors(card_ids) ⇒ Array<Integer, nil>

Gets ease factors for cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (Array<Integer, nil>) —

    Ease factors; nil for missing cards



17
18
19
 
# File 'lib/anki_connect/cards.rb', line 17

def ease_factors(card_ids)
  request(:getEaseFactors, cards: card_ids)
end

#forget_cards(card_ids) ⇒ nil

Resets cards to "new" status.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (nil) 


137
138
139
 
# File 'lib/anki_connect/cards.rb', line 137

def forget_cards(card_ids)
  request(:forgetCards, cards: card_ids)
end

#note_ids_for_cards(card_ids) ⇒ Array<Integer>

Gets unique parent note IDs for cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (Array<Integer>) —

    Unordered, unique note IDs



113
114
115
 
# File 'lib/anki_connect/cards.rb', line 113

def note_ids_for_cards(card_ids)
  request(:cardsToNotes, cards: card_ids)
end

#relearn_cards(card_ids) ⇒ nil

Makes cards enter "relearning" state.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (nil) 


145
146
147
 
# File 'lib/anki_connect/cards.rb', line 145

def relearn_cards(card_ids)
  request(:relearnCards, cards: card_ids)
end

#search_cards(query) ⇒ Array<Integer>

Searches for cards matching a query.

Parameters:

  • query (String) —

    Anki search query string

Returns:

  • (Array<Integer>) —

    Array of card IDs



105
106
107
 
# File 'lib/anki_connect/cards.rb', line 105

def search_cards(query)
  request(:findCards, query: query)
end

#set_card_values(card_id, fields, warning_check: false) ⇒ Array, Boolean

Sets raw database values for a single card. This low-level operation can corrupt scheduling data when used incorrectly.

Parameters:

  • card_id (Integer) —

    Card ID

  • fields (Hash) —

    Database field names to new values

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

    Must be true for certain risky keys

Returns:

  • (Array, Boolean) —

    Upstream result for the single card update



39
40
41
42
 
# File 'lib/anki_connect/cards.rb', line 39

def set_card_values(card_id, fields, warning_check: false)
  request(:setSpecificValueOfCard, card: card_id, keys: fields.keys, newValues: fields.values,
                                   warning_check: warning_check)
end

#set_due_date(card_ids, days) ⇒ Boolean

Sets due date for cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

  • days (String, Integer) —

    Due date (0=today, 1!=tomorrow, 3-7=random range)

Returns:

  • (Boolean) —

    true on success



169
170
171
 
# File 'lib/anki_connect/cards.rb', line 169

def set_due_date(card_ids, days)
  request(:setDueDate, cards: card_ids, days: days)
end

#set_ease_factors(card_ids, factors) ⇒ Array<Boolean>

Sets ease factors for cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

  • factors (Array<Integer>) —

    Array of ease factor values

Returns:

  • (Array<Boolean>) —

    Array indicating success for each card

Raises:

  • (ArgumentError) 


26
27
28
29
30
 
# File 'lib/anki_connect/cards.rb', line 26

def set_ease_factors(card_ids, factors)
  raise ArgumentError, 'card_ids and factors must have the same length' unless card_ids.length == factors.length

  request(:setEaseFactors, cards: card_ids, easeFactors: factors)
end

#suspend_cards(card_ids) ⇒ Boolean

Suspends cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (Boolean) —

    true if at least one card wasn't already suspended



48
49
50
 
# File 'lib/anki_connect/cards.rb', line 48

def suspend_cards(card_ids)
  request(:suspend, cards: card_ids)
end

#unsuspend_cards(card_ids) ⇒ nil

Unsuspends cards.

Parameters:

  • card_ids (Array<Integer>) —

    Array of card IDs

Returns:

  • (nil) —

    Current AnkiConnect does not return the underlying result



56
57
58
 
# File 'lib/anki_connect/cards.rb', line 56

def unsuspend_cards(card_ids)
  request(:unsuspend, cards: card_ids)
end