cable 0.1.0+1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 50

cable

An extensible and simple logging framework.
Build Status Pub Package Version Latest Dartdocs

The cable package provides a re-usable interface for logging and defining custom logging destinations, such as file I/O, remote web services, and more.

Installation

Add cable as under dependencies in your pubspec.yaml file:

dependencies:
  cable: ^0.1.0

And that's it! See usage for details.

Usage

Getting started

Out of the box cable provides two top-level methods, log and logLazy.

For simple string messages, use log:

void main() {
  log('Hello World!');
}

And for more complex messages that will need to be computed, use logLazy:

void main() {
  logLazy(() => 'The 100th digit of PI is ${computePiDigits(100)}');
}

Depending on the severity level, the closure for logLazy may not be invoked.

Both of these methods are intended to be for simpler use cases, with drawbacks:

  • They just print string-like objects to console.
  • The default severity is Severity.debug (all messages).
  • They don't (immediately) support custom formatting, destinations, severity.

HINT: Define a default Severity using Dart declaration variables.

In the VM, set CABLE_DEFAULT_SEVERITY to 4, or Severity.warning.

$ dart bin/app.dart -dCABLE_DEFAULT_SEVERITY=4

Read more about Dart declaration variables.

Creating a logger

A Logger class can be created and used for dependency injection:

void main() {
  final logger = new Logger();
  final service = new Service(logger: logger);
  // ...
}

You can also set the severity threshold:

void main() {
  final logger = new Logger(
    severity: Severity.warning,
  );
}

Or define a simple string formatter:

void main() {
  final logger = new Logger(
    // Writes string logs in the format of {name}: {message}.
    formatter: (record) => '${record.origin}: ${record.payload}',
  );
}

By default, a Logger just prints to the console. You can also configure one:

Custom destination(s)

NOTE: This package intentionally is sparse on opinions or specific destinations in order to reduce your transitive dependencies to an absolute minimum. We encourage you to write and contribute to cable_* packages that provide interesting destinations/endpoints for cable!

void main() {
  final logger = new Logger(
   destinations: [
     // Any class that implements Sink<Record>
   ],
 );
}

Several built-in classes are available cross platform:

void main() {
  final logger = new Logger(
   destinations: [
     // Does nothing.
     LogSink.nullSink,
     
     // Prints to console.
     LogSink.printSink,
     
     // Use any Sink<String> instance, such as a `StreamController`.
     new LogSink.writeToSink(someEventController),
     
     // Use any StringSink instance, such as a `StringBuffer`.
     new LogSink.writeToBuffer(stringBuffer),
   ],
  );
}

It's also easy to create your own plugin packages!

class FileSink implements Sink<Record> {
  @override
  void add(Record data) { /* Write to a file. */ }

  @override
  void close() { /* Close the file stream. */ }
}

void main() {
  final logger = new Logger(
    destinations: [new FileSink(/*...*/)],
  );
}

Override Functions

It's possible to replace log and logLazy to forward to your own configured Logger instance at runtime - use scope:

void runLogged(Logger logger) {
  logger.scope(() => startApplication());
}

Using zones, any calls to log or logLazy inside of context of startApplication() will now use your custom logger class, not the default top-level function behavior.

Contributing

We welcome a diverse set of contributions, including, but not limited to:

For the stability of the API and existing users, consider opening an issue first before implementing a large new feature or breaking an API. For smaller changes (like documentation, minor bug fixes), just send a pull request.

Testing

All pull requests are validated against travis, and must pass. The build_runner package lives in a mono repository with other build packages, and all of the following checks must pass for each package.

Ensure code passes all our analyzer checks:

$ dartanalyzer .

Ensure all code is formatted with the latest dev-channel SDK.

$ dartfmt -w .

Run all of our unit tests:

$ pub run test

0.1.0+1

  • Allows the Dart SDK >=1.25.0-dev so it can be used in Flutter.

0.1.0

  • Initial release.

1. Depend on it

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


dependencies:
  cable: "^0.1.0+1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

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

3. Import it

Now in your Dart code, you can use:


import 'package:cable/cable.dart';
        
Version Uploaded Documentation Archive
0.1.0+1 Oct 21, 2017 Go to the documentation of cable 0.1.0+1 Download cable 0.1.0+1 archive
0.1.0 Oct 20, 2017 Go to the documentation of cable 0.1.0 Download cable 0.1.0 archive

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • completed on Feb 3, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
0 / 100
Health:
Code health derived from static analysis. [more]
100 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
50

Platforms

Detected platforms: Flutter, web, other

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

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use cable.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.25.0-dev <2.0.0
meta ^1.1.0 1.1.2
Dev dependencies
test ^0.12.0