🔀 Merge pull request #3 from Komposten/release-1.2.1

Release 1.2.1

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.2.1
+- Improved the suffix list format documentation in `SuffixRules` and the `SuffixRulesHelper`s.
+- Improved documentation of `DomainUtils`.
+- Fixed `DomainUtils.isKnownSuffix` not throwing if `SuffixRules` hasn't been initialised.
+- Removed the `test_coverage` dev dependency (doesn't work for browser tests).
+- Updated README.md to better explain how to initialise `SuffixRules`.
+
 ## 1.2.0
 - Added a hash map-based `ruleMap` to `SuffixRules` to speed up the performance when matching rules.
 - Added `subdomain` and `icannSubdomain` to `PublicSuffix`.

README.md

@@ -15,24 +15,19 @@ public_suffix is a dart library for identifying the public suffixes (or TLDs), r
 - Check if URLs are subdomains, have valid domain parts, or end with known suffixes.
 
 ## Usage
-1) Import public_suffix:
-    - `public_suffix.dart`: If you prefer loading suffix lists on your own.
-    - `public_suffix_io.dart`: For helper methods to load suffix lists from URIs using `dart:io`.
-    - `public_suffix_browser.dart`:  For helper methods to load suffix lists from URIs using `dart:html`.
-2) Initialise `SuffixRules` from a string or uri containing suffix rules.
-3) Create a new instance of `PublicSuffix` to parse a URL.
-4) Access the different components through the `PublicSuffix` object.
-
-**Note:** Don't overload publicsuffix.org's servers by repeatedly retrieving the suffix list from them. Cache a copy somewhere instead, and update that copy only when the master copy is updated.
+1) Import `public_suffix.dart`.
+2) [Initialise `SuffixRules`](#initialising-suffixrules) from a suffix rule list.
+3) Create instances of `PublicSuffix` to parse URLs.
+4) Access the different URL components through the `PublicSuffix` objects.
 
 ### Short example
 ```dart
-import 'package:public_suffix/public_suffix_io.dart';
+import 'package:public_suffix/public_suffix.dart';
 
-main(List<String> arguments) async {
+main() {
   // Load a list of suffix rules from publicsuffix.org.
-  await SuffixRulesHelper.initFromUri(
-      Uri.parse('https://publicsuffix.org/list/public_suffix_list.dat'));
+  String suffixListString = 'load the list into this string';
+  SuffixRules.initFromString(suffixListString);
 	  
   // Parse a URL.
   PublicSuffix parsedUrl =
@@ -44,13 +39,40 @@ main(List<String> arguments) async {
   print(parsedUrl.domain);      // komposten.github.io
   print(parsedUrl.icannDomain); // github.io
 
-  // public_suffix also supports punycoded URLs.
+  // public_suffix also supports punycoded URLs:
   parsedUrl = PublicSuffix.fromString('https://www.xn--6qq79v.cn');
   print(parsedUrl.domain);             // xn--6qq79v.cn
   print(parsedUrl.punyDecoded.domain); // 你好.cn
 }
 ```
 
+### Initialising SuffixRules
+public_suffix requires a list of suffix rules to work. There is no list bundled by default as these lists are updated frequently.
+Instead you'll have to load a list on your own and pass that list to `SuffixRules`. There are two ways of doing this:
+1) Load the list using your own code and pass it to `SuffixRules.initFromString()`:
+   ```dart
+   //Example using Flutter
+   import 'package:flutter/services.dart';
+   import 'package:public_suffix/public_suffix.dart';
+   
+   main() {
+       var suffixList = rootBundle.loadString('assets/public_suffix_list.dat');
+       SuffixRules.initFromString(suffixList);
+   }
+   ```
+2) Import either the `dart:io` or the `dart:html`-based helper and load the list from a URI:
+   ```dart
+   //Example using dart:io; for dart:html use public_suffix_browser.dart instead.
+   import 'package:public_suffix/public_suffix_io.dart';
+   
+   main() async {
+     Uri uri = Uri.parse('https://publicsuffix.org/list/public_suffix_list.dat');
+     await SuffixRulesHelper.initFromUri(listUri);
+   }
+   ```
+
+**Note:** Don't overload publicsuffix.org's servers by repeatedly retrieving the suffix list from them. Cache a copy somewhere instead, and update that copy only when the master copy is updated.
+
 ## Utility functions
 Several utility functions can be found in the `DomainUtils` class (imported from `public_suffix.dart`). These currently include:
 - `isSubdomainOf`: Checks if a given URL is a subdomain of another domain.

lib/src/browser/suffix_rules_helper.dart

@@ -22,6 +22,8 @@ class SuffixRulesHelper {
 
   /// Initialises [SuffixRules] using a suffix list resource obtained from a URI.
   ///
+  /// See [SuffixRules.initFromString] for the expected format of the suffix list.
+  ///
   /// [HttpRequest.request] is used to retrieve the resource, and the optional
   /// parameters can be used to tweak this request. If more fine-grained control
   /// over the request is needed, consider obtaining the suffix list using custom

lib/src/io/suffix_rules_helper.dart

@@ -23,6 +23,8 @@ class SuffixRulesHelper {
 
   /// Initialises [SuffixRules] using a suffix list resource obtained from a URI.
   ///
+  /// See [SuffixRules.initFromString] for the expected format of the suffix list.
+  ///
   /// If [uri] is a `file:///` URI, the file is loaded using
   /// [File.readAsString]. For other schemes, the resource is fetched using
   /// an http request created using a simple [HttpClient].

lib/src/suffix_rules.dart

@@ -37,8 +37,10 @@ class SuffixRules {
 
   /// Initialises the rule list.
   ///
-  /// [rules] is expected to contain the contents of a suffix list with one rule per line,
-  /// like the file at [publicsuffix.org](https://publicsuffix.org/list/public_suffix_list.dat).
+  /// [rules] is expected to contain the contents of a suffix list with one rule per line.
+  /// The list is expected to follow the same format as the list at [publicsuffix.org](https://publicsuffix.org/list/public_suffix_list.dat).
+  /// This includes the `BEGIN PRIVATE` tag/comment, which [process] uses to separate
+  /// ICANN/IANA rules from private rules.
   static void initFromString(String rules) {
     initFromList(rules.split(RegExp(r'[\r\n]+')));
   }

lib/src/utilities.dart

@@ -9,13 +9,21 @@
  */
 import 'package:public_suffix/public_suffix.dart';
 
+/// Various utility functions for domains and suffixes.
+///
+/// This class holds utility functions to perform certain checks on domains and
+/// suffixes without having to first create [PublicSuffix] objects. Most of these
+/// functions create [PublicSuffix] objects internally, so if you already have
+/// such objects consider using the equivalent methods within [PublicSuffix] instead.
 class DomainUtils {
   DomainUtils._();
 
   /// Checks if a URL is a subdomain of another.
   ///
   /// Both URLs are parsed to [PublicSuffix] objects, which are then compared
   /// using [PublicSuffix.isSubdomainOf()].
+  ///
+  /// Throws a [StateError] if [SuffixRules] has not been initialised.
   static bool isSubdomainOf(Uri potentialSub, Uri root, {bool icann = false}) {
     var parsedUrl = PublicSuffix(potentialSub);
     var parsedRoot = PublicSuffix(root);
@@ -29,6 +37,8 @@ class DomainUtils {
   /// the [subdomain] property of the object is [null].
   ///
   /// If [icann] is [true], [icannSubdomain] is checked instead.
+  ///
+  /// Throws a [StateError] if [SuffixRules] has not been initialised.
   static bool isSubdomain(Uri potentialSub, {bool icann = false}) {
     if (icann) {
       return PublicSuffix(potentialSub).icannSubdomain != null;
@@ -40,7 +50,13 @@ class DomainUtils {
   /// Checks if [suffix] is a known url suffix.
   ///
   /// For example, `co.uk` is known but `example` is not.
+  ///
+  /// Throws a [StateError] if [SuffixRules] has not been initialised.
   static bool isKnownSuffix(String suffix) {
+    if (!SuffixRules.hasInitialised()) {
+      throw StateError('PublicSuffixList has not been initialised!');
+    }
+
     var split = suffix.split('.');
     var rules = SuffixRules.ruleMap[split.last] ?? <String>[];
     var isKnown = false;
@@ -61,6 +77,8 @@ class DomainUtils {
   /// If [icann] is [true] the check will be based on only the ICANN/IANA rules.
   /// If [acceptDefaultRule] is [false] URLs with suffixes only matching the
   /// default rule (`*`) will be seen as invalid.
+  ///
+  /// Throws a [StateError] if [SuffixRules] has not been initialised.
   static bool hasValidDomain(Uri domain,
       {bool icann = false, bool acceptDefaultRule = true}) {
     return PublicSuffix(domain)

pubspec.yaml

@@ -1,6 +1,6 @@
 name: public_suffix
 description: A domain parser based on the Public Suffix List, for identifying the root and suffix/TLD of URLs.
-version: 1.2.0
+version: 1.2.1
 homepage: https://www.github.com/komposten/
 repository: https://www.github.com/komposten/public_suffix
 issue_tracker: https://www.github.com/komposten/public_suffix/issues
@@ -15,4 +15,3 @@ dependencies:
 dev_dependencies:
   pedantic: ^1.7.0
   test: ^1.6.0
-  test_coverage: 0.2.3