From 7a29440689400dcb7e3ca0b63b94d7a58f985a04 Mon Sep 17 00:00:00 2001
From: Simon <simon.toivo@telhaug.no>
Date: Thu, 16 May 2024 11:47:37 +0200
Subject: [PATCH] Deprecate `add_rule!` and `add_rule_with_offsets!` for
 `append_rule!`

---
 CHANGELOG.md                    |  1 +
 lib/css_parser/parser.rb        | 33 +++++++++++++++++++++++++--------
 test/test_css_parser_loading.rb | 12 ------------
 test/test_css_parser_misc.rb    | 24 ++++++++++++++++++++++++
 4 files changed, 50 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16fa114..3c6c14c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ### Unreleased
 
+* Deprecate `add_rule!` (positional arguments)and `add_rule_with_offsets!` for `add_rule!` (keyword argument)
 * RuleSet initialize now takes keyword argument, positional arguments are still supported but deprecated
 * Removed OffsetAwareRuleSet, it's a RuleSet with optional attributes filename and offset
 
diff --git a/lib/css_parser/parser.rb b/lib/css_parser/parser.rb
index d8385f8..3f18515 100644
--- a/lib/css_parser/parser.rb
+++ b/lib/css_parser/parser.rb
@@ -164,32 +164,49 @@ def add_block!(block, options = {})
       parse_block_into_rule_sets!(block, options)
     end
 
-    # Add a CSS rule by setting the +selectors+, +declarations+ and +media_types+.
+    # Add a CSS rule by setting the +selectors+, +declarations+
+    # and +media_types+. Optional pass +filename+ , +offset+ for source
+    # reference too.
     #
     # +media_types+ can be a symbol or an array of symbols. default to :all
     # optional fields for source location for source location
     # +filename+ can be a string or uri pointing to the file or url location.
     # +offset+ should be Range object representing the start and end byte locations where the rule was found in the file.
+    def append_rule!(selectors: nil, block: nil, filename: nil, offset: nil, media_types: :all)
+      rule_set = RuleSet.new(
+        selectors: selectors, block: block,
+        offset: offset, filename: filename
+      )
 
-    def add_rule!(selectors, declarations, media_types = :all)
-      rule_set = RuleSet.new(selectors: selectors, block: declarations)
       add_rule_set!(rule_set, media_types)
     rescue ArgumentError => e
       raise e if @options[:rule_set_exceptions]
     end
 
+    # Add a CSS rule by setting the +selectors+, +declarations+ and +media_types+.
+    #
+    # +media_types+ can be a symbol or an array of symbols. default to :all
+    # optional fields for source location for source location
+    # +filename+ can be a string or uri pointing to the file or url location.
+    # +offset+ should be Range object representing the start and end byte locations where the rule was found in the file.
+
+    def add_rule!(selectors, declarations, media_types = :all)
+      warn '[DEPRECATION] `add_rule!` is deprecated. Please use `append_rule!` instead.', uplevel: 1
+
+      append_rule!(selectors: selectors, block: declarations, media_types: media_types)
+    end
+
     # Add a CSS rule by setting the +selectors+, +declarations+, +filename+, +offset+ and +media_types+.
     #
     # +filename+ can be a string or uri pointing to the file or url location.
     # +offset+ should be Range object representing the start and end byte locations where the rule was found in the file.
     # +media_types+ can be a symbol or an array of symbols.
     def add_rule_with_offsets!(selectors, declarations, filename, offset, media_types = :all)
-      rule_set = RuleSet.new(
-        selectors: selectors, block: declarations,
-        offset: offset, filename: filename
+      warn '[DEPRECATION] `add_rule_with_offsets!` is deprecated. Please use `append_rule!` instead.', uplevel: 1
+      append_rule!(
+        selectors: selectors, block: declarations, media_types: media_types,
+        filename: filename, offset: offset
       )
-
-      add_rule_set!(rule_set, media_types)
     end
 
     # Add a CssParser RuleSet object.
diff --git a/test/test_css_parser_loading.rb b/test/test_css_parser_loading.rb
index f1ee7c9..b8c8457 100644
--- a/test/test_css_parser_loading.rb
+++ b/test/test_css_parser_loading.rb
@@ -204,16 +204,4 @@ def test_toggling_not_found_exceptions
 
     cp_without_exceptions.load_uri!("#{@uri_base}/no-exist.xyz")
   end
-
-  def test_rule_set_argument_exceptions
-    cp_with_exceptions = Parser.new(rule_set_exceptions: true)
-
-    assert_raises ArgumentError, 'background-color value is empty' do
-      cp_with_exceptions.add_rule!('body', 'background-color: !important')
-    end
-
-    cp_without_exceptions = Parser.new(rule_set_exceptions: false)
-
-    cp_without_exceptions.add_rule!('body', 'background-color: !important')
-  end
 end
diff --git a/test/test_css_parser_misc.rb b/test/test_css_parser_misc.rb
index cd88118..bc7d17d 100644
--- a/test/test_css_parser_misc.rb
+++ b/test/test_css_parser_misc.rb
@@ -226,4 +226,28 @@ def test_enumerator_nonempty
       assert_equal 'color: black;', desc
     end
   end
+
+  def test_catching_argument_exceptions_for_add_rule
+    cp_with_exceptions = Parser.new(rule_set_exceptions: true)
+
+    assert_raises ArgumentError, 'background-color value is empty' do
+      cp_with_exceptions.add_rule!('body', 'background-color: !important')
+    end
+
+    cp_without_exceptions = Parser.new(rule_set_exceptions: false)
+
+    cp_without_exceptions.add_rule!('body', 'background-color: !important')
+  end
+
+  def test_catching_argument_exceptions_for_add_rule_with_offsets
+    cp_with_exceptions = Parser.new(capture_offsets: true, rule_set_exceptions: true)
+
+    assert_raises ArgumentError, 'background-color value is empty' do
+      cp_with_exceptions.add_rule_with_offsets!('body', 'background-color: !important', 'inline', 1)
+    end
+
+    cp_without_exceptions = Parser.new(capture_offsets: true, rule_set_exceptions: false)
+
+    cp_without_exceptions.add_rule_with_offsets!('body', 'background-color: !important', 'inline', 1)
+  end
 end