Merge #564

564: feat: fixed for the issue (#557) r=myConsciousness a=myConsciousness

# 1. Description

<!-- Provide a description of what this PR is doing.
If you're modifying existing behavior, describe the existing behavior, how this PR is changing it,
and what motivated the change. If this is a breaking change, specify explicitly which APIs have been
changed. -->

## 1.1. Checklist

<!-- Before you create this PR confirm that it meets all requirements listed below by checking the
relevant checkboxes (`[x]`). This will ensure a smooth and quick review process. -->

- [x] The title of my PR starts with a [Conventional Commit] prefix (`fix:`, `feat:`, `docs:` etc).
- [x] I have read the [Contributor Guide] and followed the process outlined for submitting PRs.
- [x] I have updated/added tests for ALL new/updated/fixed functionality.
- [x] I have updated/added relevant documentation in `docs` and added dartdoc comments with `///`.
- [x] I have updated/added relevant examples in `examples`.

## 1.2. Breaking Change

<!-- Does your PR require users to manually update their apps to accommodate your change?

If the PR is a breaking change this should be indicated with suffix "!"  (for example, `feat!:`, `fix!:`). See [Conventional Commit] for details.
-->

- [ ] Yes, this is a breaking change.
- [x] No, this is _not_ a breaking change.

## 1.3. Related Issues

<!-- Provide a list of issues related to this PR from the [issue database].
Indicate which of these issues are resolved or fixed by this PR, i.e. Fixes #xxxx* !-->

<!-- Links -->

[issue database]: https://github.com/twitter-dart/twitter-api-v2/issues
[contributor guide]: https://github.com/twitter-dart/twitter-api-v2/blob/main/CONTRIBUTING.md
[style guide]: https://github.com/twitter-dart/twitter-api-v2/blob/main/STYLEGUIDE.md
[conventional commit]: https://conventionalcommits.org


Co-authored-by: myConsciousness <[email protected]>

CHANGELOG.md

@@ -3,6 +3,9 @@
 ## 4.4.2
 
 - Improved internal process for checking rate limit. ([#562](https://github.com/twitter-dart/twitter-api-v2/issues/562))
+- Supported `entity:` filtering rule operator. You can use this operator with following methods. ([#557](https://github.com/twitter-dart/twitter-api-v2/issues/557))
+  - `matchEntity`
+  - `notMatchEntity`
 
 ## v4.4.1
 

lib/src/service/tweets/filtering/operation/standalone_operation.dart

@@ -12,6 +12,7 @@ import '../operator/standalone/bounding_box.dart';
 import '../operator/standalone/cashtag.dart';
 import '../operator/standalone/conversation.dart';
 import '../operator/standalone/country.dart';
+import '../operator/standalone/entity.dart';
 import '../operator/standalone/hashtag.dart';
 import '../operator/standalone/keyword.dart';
 import '../operator/standalone/place.dart';
@@ -87,6 +88,12 @@ class StandaloneOperation {
   RetweetedBy createNegatedRetweetedBy(final String user) =>
       RetweetedBy.negated(user);
 
+  /// Returns the new instance of [Entity] based on [value].
+  Entity createEntity(final String value) => Entity(value);
+
+  /// Returns the new instance of negated [Entity] based on [value].
+  Entity createNegatedEntity(final String value) => Entity.negated(value);
+
   /// Returns the new instance of [Conversation] based on [tweetId].
   Conversation createConversation(final String tweetId) =>
       Conversation(tweetId);

lib/src/service/tweets/filtering/operator/standalone/entity.dart

@@ -0,0 +1,34 @@
+// Copyright 2022 Kato Shinya. All rights reserved.
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided the conditions.
+
+// Project imports:
+import '../operator.dart';
+import '../validation_result.dart';
+
+class Entity extends Operator {
+  /// Returns the new instance of [Entity].
+  const Entity(
+    this.value, {
+    bool negated = false,
+  }) : super(negated);
+
+  factory Entity.negated(final String value) => Entity(value, negated: true);
+
+  /// The value
+  final String value;
+
+  @override
+  ValidationResult validate() {
+    if (value.isEmpty) {
+      return ValidationResult.failed(
+        'The entity must not be an empty string.',
+      );
+    }
+
+    return ValidationResult.succeeded();
+  }
+
+  @override
+  String format() => 'entity:"$value"';
+}

lib/src/service/tweets/filtering/syntax/standalone_syntax.dart

@@ -264,6 +264,33 @@ abstract class StandaloneSyntax extends GroupSyntax {
         _standaloneOperation.createNegatedRetweetedBy(user),
       );
 
+  /// Matches Tweets with a specific entity string value.
+  ///
+  /// To learn more about this operator, please visit
+  /// [page on annotations](https://developer.twitter.com/en/docs/twitter-api/annotations/overview).
+  ///
+  /// You can only pass a single entity per this operator.
+  ///
+  /// ## Parameters
+  ///
+  /// - [value]: Entity value to be matched.
+  ///
+  /// ## Type
+  ///
+  /// - [Standalone](https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/integrate/build-a-rule#types)
+  ///
+  /// ## Availability
+  ///
+  /// - Essential
+  LogicalChannel matchEntity(final String value) => _buffer.appendOperator(
+        _standaloneOperation.createEntity(value),
+      );
+
+  /// The negated representation of [matchEntity].
+  LogicalChannel notMatchEntity(final String value) => _buffer.appendOperator(
+        _standaloneOperation.createNegatedEntity(value),
+      );
+
   /// Matches Tweets that share a common conversation ID. A conversation ID
   /// is set to the Tweet ID of a Tweet that started a conversation.
   ///

test/src/service/tweets/filtering/filtering_rule_test.dart

@@ -126,6 +126,20 @@ void main() {
       expect(actual.build(), '-retweets_of:test');
     });
 
+    test('.matchEntity', () {
+      final actual = FilteringRule.of().matchEntity('test aaa');
+
+      expect(actual, isA<LogicalChannel>());
+      expect(actual.build(), 'entity:"test aaa"');
+    });
+
+    test('.notMatchEntity', () {
+      final actual = FilteringRule.of().notMatchEntity('test aaa');
+
+      expect(actual, isA<LogicalChannel>());
+      expect(actual.build(), '-entity:"test aaa"');
+    });
+
     test('.matchConversation', () {
       final actual = FilteringRule.of().matchConversation('1234');
 

test/src/service/tweets/filtering/operator/standalone/entity_test.dart

@@ -0,0 +1,40 @@
+// Copyright 2022 Kato Shinya. All rights reserved.
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided the conditions.
+
+// Package imports:
+import 'package:test/test.dart';
+import 'package:twitter_api_v2/src/service/tweets/filtering/operator/standalone/entity.dart';
+
+void main() {
+  group('.toString', () {
+    test('with string value', () {
+      final actual = Entity('test aaa');
+
+      expect(actual.toString(), 'entity:"test aaa"');
+    });
+
+    test('when negated', () {
+      final actual = Entity.negated('test aaa');
+
+      expect(actual.toString(), '-entity:"test aaa"');
+    });
+
+    test('when value is empty', () {
+      final actual = Entity('');
+
+      expect(
+        () => actual.toString(),
+        throwsA(
+          allOf(
+            isA<ArgumentError>(),
+            predicate(
+              (dynamic e) =>
+                  e.message == 'The entity must not be an empty string.',
+            ),
+          ),
+        ),
+      );
+    });
+  });
+}