to_string_helper 1.1.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 70

to_string_helper #

Flexibly configure output of toString method (with or without code generation) (with or without mixin).

You can choose either to use code generator or not.

If you want to generate code, you also need the package to_string_helper_generator. Otherwise, you only need this package.

Example (without code generator) #

  1. Add dependency to your pubspec.yaml
    dependencies:
        to_string_helper: ^1.1.0
    
  2. Configure your class
    import 'package:to_string_helper/to_string_helper.dart';
    
    @ToString()
    class Bike {
      final hasEngine = false;
      final wheels = 2;
    
      @override
      String toString() {
        return ToStringHelper(this)
          .add('wheels', wheels) // named value
          .addValue(hasEngine) // unnamed value
          .toString();
      }
    }
    
  3. Output
    Bike{wheels=2, false}
    

Example (with code generator) #

  1. Add dependencies to your pubspec.yaml
    dependencies:
        to_string_helper: ^1.1.0
    dev_dependencies:
        build_runner: ^1.0.0
        to_string_helper_generator: ^1.1.0
    
  2. Configure your class
  • With mixin
     import 'package:to_string_helper/to_string_helper.dart';
    
     // assume current file is bike.dart, the generated code should be in bike.g.dart
     part 'bike.g.dart';
    
     @ToStringMixin()
     class Bike {/*...*/}
    
  • Without mixin
     import 'package:to_string_helper/to_string_helper.dart';
    
     // assume current file is bike.dart, the generated code should be in bike.g.dart
     part 'bike.g.dart';
    
     @ToString()
     class Bike {/*...*/}
    
  1. Generate code (see build_runner)
    • pub run build_runner build or flutter packages run build_runner build: run a single build and exit.
    • pub run build_runner watch or flutter packages run build_runner watch: continuously run builds as you edit files.
  2. Use the generated code to produce output of toString
  • With mixin
     import 'package:to_string_helper/to_string_helper.dart';
    
     part 'bike.g.dart';
    
     // Name of the generated mixin is in format _$<ClassName>ToString
     @ToStringMixin()
     class Bike with _$BikeToString {
       final hasEngine = false;
       final wheels = 2;
     }
    
  • Without mixin
     import 'package:to_string_helper/to_string_helper.dart';
    
     part 'bike.g.dart';
    
     @ToString()
     class Bike {
       final hasEngine = false;
       final wheels = 2;
    
       @override
       String toString() {
         // Name of the generated method is in format _$<className>ToString()
         return _$bikeToString(this);
       }
     }
    
  1. Output
    Bike{wheels=2, hasEngine=false}
    

Configuration for code generator #

  • Formatting output

    • Separator
      • Default is a comma follow with a space: @ToString(separator: ', ')
      • Change to use semicolon as separator: @ToString(separator: '; ')
    • null value
      • Default: @ToString(nullString: 'null')
      • Change output of null value to NULL: @ToString(nullString: 'NULL')
    • Named and unnamed value
      • Named value: Bike{wheels=2}.
      • Unnamed value: Bike{2}.
      • Default: @ToString(unnamedValue: false).
      • If unnamedValue is true, unnamed value should be used. Otherwise, use named value.
      • Overwrite the global configuration for a specific field:
        @ToString(unnamedValue: false)
        class Bike {
          @ToStringField(unnamedValue: true)
          final wheels = 2;
        }
        
    • Truncate if too long
      • Default: @ToString(truncate: 0). Zero or negative value means no truncate.
      • Configure globally to truncate if the output of fields longer than 100 characters: @ToString(truncate: 100)
      • Overwrite the global configuration for a specific field to truncate if output of the field is longer than 50 characters:
        @ToString(truncate: 100)
        class Bike {
          @ToStringField(truncate: 50)
          final wheels = 2;
        }
        
    • Pretty print (TODO)
  • Force include/exclude a specific field regardless configuration in @ToString()

    @ToString()
    class Bike {
      // force to exclude field wheels
      @ToStringField(exclude: true)
      final wheels = 2;
    
      // force to include field _engine
      @ToStringField()
      final _engine = 'No Engine';
    }
    
  • Include/exclude field types

    • Example using globalInclude
      @ToString(
        globalInclude: Include(
          nullValue: true,
          nonStatic: true,
          static: false,
          public: true,
          private: false,
        ),
      )
      class Bike {/*...*/}
      
    • Example using inclusion
      @ToString(
        inclusion: {
          Bike: Include(
            nullValue: true,
            nonStatic: true,
            static: false,
            public: true,
            private: false,
          ),
        },
      )
      class Bike {/*...*/}
      
  • Include/exclude inherited fields from super classes

    By default, only declared fields in the annotated class are included in the output.

    To include non-override inherited fields, you must declare it in @ToString().

    Example:

    class Bike {
      final wheels = 2;
      final hasEngine = false;
      final note = 'Bike';
    }
    
    @ToString()
    class EBike1 extends Bike {
      @override
      final hasEngine = true;
      String color = 'red';
    
      @override
      String toString() {
        return _$eBike1ToString(this);
      }
    }
    
    @ToString(inclusion: {Bike: Include()})
    class EBike2 extends Bike {
      @override
      final hasEngine = true;
      String color = 'black';
    
      @override
      String toString() {
        return _$eBike2ToString(this);
      }
    }
    
    void main() {
      print(EBike1()); // EBike1{hasEngine=true, color=red}
      print(EBike2()); // EBike2{hasEngine=true, color=black, wheels=2, note=Bike}
    }
    
  • How do inclusion map and globalInclude work?

    • inclusion map determines which class should be scanned for the output. If the current annotated class, ex. EBike1 in the example above, is not found in inclusion map, entry {EBike1: Include()} is added automatically to the map.
    • If globalInclude is not specified, Include() instance is created and used automatically.
    • Include in inclusion map and globalInclude are then merged. Below is an example how the attribute nullValue is merged.
      • If inclusion[Bike].nullValue == null, use globalInclude.nullValue.
      • If globalInclude.nullValue == null, use the fallback value (see default configuration).

Default configuration #

  • Configuration of @ToString and @ToStringMixin is exactly identical. @ToStringMixin generates the same code as @ToString and additionally a mixin class.

  • The 2 examples below are treated equally:

    @ToString()
    class Bike {/*...*/}
    
    @ToString(
      globalInclude: Include(),
      inclusion: {Bike: Include()},
      nullString: 'null',
      separator: ', ',
      truncate: 0,
      unnamedValue: false,
    )
    class Bike {/*...*/}
    
  • inclusion: {Bike: Include(static: true)} means inheriting all attributes from globalInclude, except Include.static.

  • globalInclude: Include(static: true) means using fallback values for all attributes, except Include.static.

  • Fallback values of Include():

    • nullValue: true
    • nonStatic: true
    • static: false
    • public: true
    • private: false
  • @ToStringField(), @ToStringField(exclude: false) or @ToStringField(exclude: null) are treated equally. It means, force to include the field regardless of configuration in @ToString().

  • @ToStringField(exclude: true): force to exclude the field regardless of configuration in @ToString().

  • ToStringField.includeNullValue == null means inheriting Include.nullValue from @ToString() after merging globalInclude and inclusion.

  • ToStringField.truncate == null means inheriting ToString.truncate.

  • ToStringField.unnamedValue == null means inheriting ToString.unnamedValue.

More examples: #

1.1.1 #

  • Update examples in documentation

1.1.0 #

  • Added annotation @ToStringMixin.

1.0.5 #

  • Improved documentation.

1.0.4 #

  • Documented implemented features.

1.0.3 #

  • Added helper class ToStringHelper. This class allows to be used without code generation.
  • Added annotations @ToString and @ToStringField, which allow to configure the generated code for toString() method.

example/example.md

Simple example (without code generator) #

  • pubspec.yaml

    dependencies:
      to_string_helper: ^1.1.0
    
  • bike.dart

    import 'package:to_string_helper/to_string_helper.dart';
    
    class Bike {
      final hasEngine = false;
      final wheels = 2;
    
      @override
      String toString() {
        return ToStringHelper(this)
          .add('wheels', wheels) // named value
          .addValue(hasEngine) // unnamed value
          .toString();
      }
    }
    
  • Output

    Bike{wheels=2, false}
    

Simple example (with code generator) #

  • Require package to_string_helper_generator
  • pubspec.yaml
    dependencies:
      to_string_helper: ^1.1.0
    
    dev_dependencies:
      build_runner: ^1.0.0
      to_string_helper_generator: ^1.1.0
    
  • bike.dart with mixin
    import 'package:to_string_helper/to_string_helper.dart';
    
    part 'bike.g.dart';
    
    // Name of the generated mixin is in format _$<ClassName>ToString
    @ToStringMixin()
    class Bike with _$BikeToString {
      final hasEngine = false;
    
      @ToStringField(exclude: true)
      final wheels = 2;
    }
    
  • bike.dart without mixin
    import 'package:to_string_helper/to_string_helper.dart';
    
    part 'bike.g.dart';
    
    @ToString()
    class Bike {
      final hasEngine = false;
    
      @ToStringField(exclude: true)
      final wheels = 2;
    
      @override
      String toString() {
        // Name of the generated method is in format _$<className>ToString()
        return _$bikeToString(this);
      }
    }
    
  • Generate code (see build_runner)
    • pub run build_runner build or flutter packages run build_runner build: run a single build and exit.
    • pub run build_runner watch or flutter packages run build_runner watch: continuously run builds as you edit files.
  • Output
    Bike{hasEngine=false}
    

Use this package as a library

1. Depend on it

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


dependencies:
  to_string_helper: ^1.1.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:to_string_helper/to_string_helper.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
39
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]
70
Learn more about scoring.

We analyzed this package on Jul 2, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0