Dart UR Library

September 23, 2024 · View on GitHub

UR Implementation in Dart -- ported from the Python Reference Implementation

Introduction

URs ("Uniform Resources") are a method for encoding structured binary data for transport in URIs and QR Codes. They are described in BCR-2020-005.

There are also reference implementations in other languages:

Origin, Authors, Copyright & Licenses

This code is a Dart port of the original Python implementation by Foundation Devices. See Foundation Devices Python UR Library for the original version.

Installation

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

dependencies:
  ur:
    git:
      url: https://github.com/bukata-sa/bc-ur-dart.git
      ref: main  # or use a specific tag or commit hash

Then run dart pub get or flutter pub get if you're using Flutter.

Alternatively, if the package is published to pub.dev, you can use:

dependencies:
  ur: ^0.1.0

Usage

Import the library:
```
import 'package:ur/ur.dart';
```

Example usage from ur_test.dart

test('UR Encode json', () {
  var sourceJson = {
    "int": 123,
    "bool": true,
    "str": "hello",
    "list": [1, 2, 3],
    "map": {"a": 1, "b": 2},
    "null": null
  };
  var sourceBytes = utf8.encode(json.encode(sourceJson));
  var cborEncoder = CBOREncoder();
  cborEncoder.encodeBytes(sourceBytes);
  var ur = UR("bytes", cborEncoder.getBytes());
  var encoded = UREncoder.encode(ur);
  expect(
      encoded,
      equals(
          'ur:bytes/hdghkgcpinjtjycpfteheyeodwcpidjljljzcpftjyjpkpihdwcpjkjyjpcpftcpisihjzjzjlcpdwcpjzinjkjycpfthpehdweydweohldwcpjnhsjocpftkgcphscpftehdwcpidcpfteykidwcpjtkpjzjzcpftjtkpjzjzkidndrpmhe'));
});

test('UR Decode json', () {
  var source =
      'ur:bytes/hdghkgcpinjtjycpfteheyeodwcpidjljljzcpftjyjpkpihdwcpjkjyjpcpftcpisihjzjzjlcpdwcpjzinjkjycpfthpehdweydweohldwcpjnhsjocpftkgcphscpftehdwcpidcpfteykidwcpjtkpjzjzcpftjtkpjzjzkidndrpmhe';
  var ur = URDecoder.decode(source);
  var cborDecorder = CBORDecoder(ur.cbor);
  var (bytes, length) = cborDecorder.decodeBytes();
  var decoded = utf8.decode(bytes);
  expect(
      json.decode(decoded),
      equals({
        "int": 123,
        "bool": true,
        "str": "hello",
        "list": [1, 2, 3],
        "map": {"a": 1, "b": 2},
        "null": null
      }));
});

Development

To run tests:

dart test

Ensure that you add new unit tests for new or modified functionality.

Version History

0.1.0, [22.09.2024] - Initial release

Initial Dart port and testing release.