Skip to content

Commit 60f5776

Browse files
committed
🔧🗑️ Deprecate UIDPlusData, with config to upgrade
This config attribute causes the parser to use the new AppendUIDData and CopyUIDData classes instead of CopyUIDData. AppendUIDData and CopyUIDData are _mostly_ backward-compatible with UIDPlusData. Most applications should be able to upgrade with no changes. UIDPlusData will be removed in +v0.6+.
1 parent 8f41dea commit 60f5776

File tree

4 files changed

+88
-4
lines changed

4 files changed

+88
-4
lines changed

lib/net/imap/config.rb

+29
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,32 @@ def self.[](config)
287287
#
288288
# Alias for responses_without_block
289289

290+
# Whether ResponseParser should use the deprecated UIDPlusData or
291+
# CopyUIDData for +COPYUID+ response codes, and UIDPlusData or
292+
# AppendUIDData for +APPENDUID+ response codes.
293+
#
294+
# AppendUIDData and CopyUIDData are _mostly_ backward-compatible with
295+
# UIDPlusData. Most applications should be able to upgrade with little
296+
# or no changes.
297+
#
298+
# <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
299+
#
300+
# <em>(Config option added in +v0.4.19+ and +v0.5.6+.)</em>
301+
#
302+
# <em>UIDPlusData will be removed in +v0.6+ and this config setting will
303+
# be ignored.</em>
304+
#
305+
# ==== Valid options
306+
#
307+
# [+true+ <em>(original default)</em>]
308+
# ResponseParser only uses UIDPlusData.
309+
#
310+
# [+false+ <em>(planned default for +v0.6+)</em>]
311+
# ResponseParser _only_ uses AppendUIDData and CopyUIDData.
312+
attr_accessor :parser_use_deprecated_uidplus_data, type: [
313+
true, false
314+
]
315+
290316
# Creates a new config object and initialize its attribute with +attrs+.
291317
#
292318
# If +parent+ is not given, the global config is used by default.
@@ -367,6 +393,7 @@ def defaults_hash
367393
sasl_ir: true,
368394
enforce_logindisabled: true,
369395
responses_without_block: :warn,
396+
parser_use_deprecated_uidplus_data: true,
370397
).freeze
371398

372399
@global = default.new
@@ -378,6 +405,7 @@ def defaults_hash
378405
sasl_ir: false,
379406
responses_without_block: :silence_deprecation_warning,
380407
enforce_logindisabled: false,
408+
parser_use_deprecated_uidplus_data: true,
381409
).freeze
382410
version_defaults[0.0] = Config[0]
383411
version_defaults[0.1] = Config[0]
@@ -392,6 +420,7 @@ def defaults_hash
392420

393421
version_defaults[0.6] = Config[0.5].dup.update(
394422
responses_without_block: :frozen_dup,
423+
parser_use_deprecated_uidplus_data: false,
395424
).freeze
396425
version_defaults[:next] = Config[0.6]
397426
version_defaults[:future] = Config[:next]

lib/net/imap/response_parser.rb

+8-4
Original file line numberDiff line numberDiff line change
@@ -2001,11 +2001,10 @@ def charset__list
20012001
#
20022002
# n.b, uniqueid ⊂ uid-set. To avoid inconsistent return types, we always
20032003
# match uid_set even if that returns a single-member array.
2004-
#
20052004
def resp_code_apnd__data
20062005
validity = number; SP!
20072006
dst_uids = uid_set # uniqueid ⊂ uid-set
2008-
UIDPlus(validity, nil, dst_uids)
2007+
AppendUID(validity, dst_uids)
20092008
end
20102009

20112010
# already matched: "COPYUID"
@@ -2015,10 +2014,15 @@ def resp_code_copy__data
20152014
validity = number; SP!
20162015
src_uids = uid_set; SP!
20172016
dst_uids = uid_set
2018-
UIDPlus(validity, src_uids, dst_uids)
2017+
CopyUID(validity, src_uids, dst_uids)
20192018
end
20202019

2021-
def UIDPlus(validity, src_uids, dst_uids)
2020+
def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end
2021+
def CopyUID(...) DeprecatedUIDPlus(...) || CopyUIDData.new(...) end
2022+
2023+
# TODO: remove this code in the v0.6.0 release
2024+
def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids)
2025+
return unless config.parser_use_deprecated_uidplus_data
20222026
src_uids &&= src_uids.each_ordered_number.to_a
20232027
dst_uids = dst_uids.each_ordered_number.to_a
20242028
UIDPlusData.new(validity, src_uids, dst_uids)

lib/net/imap/uidplus_data.rb

+14
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
module Net
44
class IMAP < Protocol
55

6+
# *NOTE:* <em>UIDPlusData is deprecated and will be removed in the +0.6.0+
7+
# release.</em> To use AppendUIDData and CopyUIDData before +0.6.0+, set
8+
# Config#parser_use_deprecated_uidplus_data to +false+.
9+
#
610
# UIDPlusData represents the ResponseCode#data that accompanies the
711
# +APPENDUID+ and +COPYUID+ {response codes}[rdoc-ref:ResponseCode].
812
#
@@ -60,6 +64,11 @@ def uid_mapping
6064
end
6165
end
6266

67+
# >>>
68+
# *NOTE:* <em>AppendUIDData will replace UIDPlusData for +APPENDUID+ in the
69+
# +0.6.0+ release.</em> To use AppendUIDData before +0.6.0+, set
70+
# Config#parser_use_deprecated_uidplus_data to +false+.
71+
#
6372
# AppendUIDData represents the ResponseCode#data that accompanies the
6473
# +APPENDUID+ {response code}[rdoc-ref:ResponseCode].
6574
#
@@ -99,6 +108,11 @@ def size
99108
end
100109
end
101110

111+
# >>>
112+
# *NOTE:* <em>CopyUIDData will replace UIDPlusData for +COPYUID+ in the
113+
# +0.6.0+ release.</em> To use CopyUIDData before +0.6.0+, set
114+
# Config#parser_use_deprecated_uidplus_data to +false+.
115+
#
102116
# CopyUIDData represents the ResponseCode#data that accompanies the
103117
# +COPYUID+ {response code}[rdoc-ref:ResponseCode].
104118
#

test/net/imap/test_imap_response_parser.rb

+37
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,24 @@ def test_fetch_binary_and_binary_size
211211
end
212212
end
213213

214+
test "APPENDUID with parser_use_deprecated_uidplus_data = true" do
215+
parser = Net::IMAP::ResponseParser.new(config: {
216+
parser_use_deprecated_uidplus_data: true,
217+
})
218+
response = parser.parse("A004 OK [APPENDUID 1 101:200] Done\r\n")
219+
uidplus = response.data.code.data
220+
assert_instance_of Net::IMAP::UIDPlusData, uidplus
221+
assert_equal 100, uidplus.assigned_uids.size
222+
end
223+
224+
test "APPENDUID with parser_use_deprecated_uidplus_data = false" do
225+
parser = Net::IMAP::ResponseParser.new(config: {
226+
parser_use_deprecated_uidplus_data: false,
227+
})
228+
response = parser.parse("A004 OK [APPENDUID 1 10] Done\r\n")
229+
assert_instance_of Net::IMAP::AppendUIDData, response.data.code.data
230+
end
231+
214232
test "COPYUID with backwards ranges" do
215233
parser = Net::IMAP::ResponseParser.new
216234
response = parser.parse(
@@ -241,4 +259,23 @@ def test_fetch_binary_and_binary_size
241259
end
242260
end
243261

262+
test "COPYUID with parser_use_deprecated_uidplus_data = true" do
263+
parser = Net::IMAP::ResponseParser.new(config: {
264+
parser_use_deprecated_uidplus_data: true,
265+
})
266+
response = parser.parse("A004 OK [copyUID 1 101:200 1:100] Done\r\n")
267+
uidplus = response.data.code.data
268+
assert_instance_of Net::IMAP::UIDPlusData, uidplus
269+
assert_equal 100, uidplus.assigned_uids.size
270+
assert_equal 100, uidplus.source_uids.size
271+
end
272+
273+
test "COPYUID with parser_use_deprecated_uidplus_data = false" do
274+
parser = Net::IMAP::ResponseParser.new(config: {
275+
parser_use_deprecated_uidplus_data: false,
276+
})
277+
response = parser.parse("A004 OK [COPYUID 1 101 1] Done\r\n")
278+
assert_instance_of Net::IMAP::CopyUIDData, response.data.code.data
279+
end
280+
244281
end

0 commit comments

Comments
 (0)