to_string_helper 1.1.1

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

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
   

   copied to clipboard
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();
     }
   }
   

   copied to clipboard
3. Output

   Bike{wheels=2, false}
   

   copied to clipboard

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
   

   copied to clipboard
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 {/*...*/}
  

  copied to clipboard
• 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 {/*...*/}
  

  copied to clipboard

3. 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.
4. 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;
  }
  

  copied to clipboard
• 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);
    }
  }
  

  copied to clipboard

5. Output

   Bike{wheels=2, hasEngine=false}
   

   copied to clipboard

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;
      }
      

      copied to clipboard
  • 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;
      }
      

      copied to clipboard
  • 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';
  }
  

  copied to clipboard

• Include/exclude field types

  • Example using globalInclude

    @ToString(
      globalInclude: Include(
        nullValue: true,
        nonStatic: true,
        static: false,
        public: true,
        private: false,
      ),
    )
    class Bike {/*...*/}
    

    copied to clipboard
  • Example using inclusion

    @ToString(
      inclusion: {
        Bike: Include(
          nullValue: true,
          nonStatic: true,
          static: false,
          public: true,
          private: false,
        ),
      },
    )
    class Bike {/*...*/}
    

    copied to clipboard

• 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}
  }
  

  copied to clipboard

• 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 {/*...*/}
  

  copied to clipboard

  @ToString(
    globalInclude: Include(),
    inclusion: {Bike: Include()},
    nullString: 'null',
    separator: ', ',
    truncate: 0,
    unnamedValue: false,
  )
  class Bike {/*...*/}
  

  copied to clipboard

• 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:

• Example - without code generator
• Example - with code generator