public_suffix 1.2.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 77

public_suffix #

pub package Build Status

A domain parser based on the Public Suffix List

public_suffix is a dart library for identifying the public suffixes (or TLDs), root domains and registrable parts of URLs.

Main features #

  • Identify suffix, root domain, registrable domain (root + suffix) and subdomain from URLs.
  • Provide your own list of suffix rules to keep up to date with the rules you need.
  • Get results from matching with only ICANN/IANA rules or also include private ones.
    • For example, a private rule can see the full github.io as suffix while ICANN only recognises the io part.
  • Parse punycode encoded URLs and get both encoded and decoded results.
  • Check if URLs are subdomains, have valid domain parts, or end with known suffixes.

Usage #

  1. Import public_suffix.dart.
  2. Initialise 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 #

import 'package:public_suffix/public_suffix.dart';

main() {
  // Load a list of suffix rules from publicsuffix.org.
  String suffixListString = 'load the list into this string';
  SuffixRules.initFromString(suffixListString);
	  
  // Parse a URL.
  PublicSuffix parsedUrl =
      PublicSuffix.fromString('https://www.komposten.github.io');
	  
  // Obtain information using the many getters, for example:
  print(parsedUrl.suffix);      // github.io
  print(parsedUrl.root);        // komposten
  print(parsedUrl.domain);      // komposten.github.io
  print(parsedUrl.icannDomain); // github.io

  // 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():
    //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:
    //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.
  • isSubdomain: Checks if a given URL has a subdomain part.
  • isKnownSuffix: Checks if a given suffix (e.g. co.uk) is listed in the suffix rule list.
  • hasValidDomain: Checks if a given URL contains a registrable domain part.

Most of these create PublicSuffix objects internally. If you are already working with PublicSuffix objects, there are similar methods you can call directly on those to avoid creating new ones.

License #

public_suffix is licensed under the MIT license. See LICENSE for the full license text.

1.2.1 #

  • Improved the suffix list format documentation in SuffixRules and the SuffixRulesHelpers.
  • 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.
  • Added isSubdomainOf, hasKnownSuffix and hasValidDomain to PublicSuffix.
  • Added DomainUtils with the following static functions:
    • isSubdomainOf
    • isSubdomain
    • isKnownSuffix
    • hasValidDomain
  • Added PublicSuffix.fromString as a convenience method for PublicSuffix(Uri.parse(string)).
  • Updated docs and parameter names to say URL instead of URI, which is more correct (PublicSuffix.sourceUri is unchanged to avoid breaking changes).

1.1.0 #

  • Added primary library public_suffix.dart, which can be used without dart:io and dart:html (but still requires to be initialised with a suffix list).

1.0.0 #

  • Load suffix rule lists from strings or URIs.
  • Parse URLs against suffix lists to obtain:
    • public suffix (e.g. co.uk)
    • root domain (e.g. google)
    • registrable domain (e.g. google.co.uk)
  • Obtain results with and without private (i.e. non-ICANN/IANA) suffix rules.
  • Obtain punycode encoded and decoded results (if a punycoded URL is parsed).

example/main.dart

import 'package:public_suffix/public_suffix_io.dart';

Future<void> main() async {
  // Load a list of suffix rules from publicsuffix.org.
  await SuffixRulesHelper.initFromUri(
      Uri.parse('https://publicsuffix.org/list/public_suffix_list.dat'));

  // Parse a URL.
  PublicSuffix parsedUrl =
      PublicSuffix.fromString('https://www.komposten.github.io');

  // Results when matching against both ICANN/IANA and private suffixes.
  print(parsedUrl.suffix); // github.io
  print(parsedUrl.root); // komposten
  print(parsedUrl.domain); // komposten.github.io

  // Results when matching against only ICANN/IANA suffixes.
  print(parsedUrl.icannSuffix); // io
  print(parsedUrl.icannRoot); // github
  print(parsedUrl.icannDomain); // github.io

  // Punycode decoded results.
  parsedUrl = PublicSuffix.fromString('https://www.xn--6qq79v.cn');
  print(parsedUrl.domain); // xn--6qq79v.cn
  print(parsedUrl.punyDecoded.domain); // 你好.cn

  // Dispose the list to unload it from memory if you wish.
  // This is probably not needed since the list is relatively small.
  SuffixRules.dispose();
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  public_suffix: ^1.2.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:public_suffix/public_suffix.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
53
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
77
Learn more about scoring.

We analyzed this package on Oct 11, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:public_suffix/public_suffix.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
punycode ^0.1.0 0.1.0
Dev dependencies
pedantic ^1.7.0
test ^1.6.0