to_string_helper 1.0.4 to_string_helper: ^1.0.4 copied to clipboard
Flexibly configure output of toString method (with or without code generation).
to_string_helper #
Flexibly configure output of toString
method (with or without code generation).
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) #
- Add dependency to your
pubspec.yaml
dependencies: to_string_helper: ^1.0.0
- Configure your class
import 'package:to_string_helper/to_string_helper.dart'; @ToString() class Bike { final hasEngine = false; final wheels = 2; return ToStringHelper(this) .add('wheels', wheels) // named value .addValue(hasEngine) // unnamed value .toString(); }
- Output
Bike{wheels=2, false}
Example (with code generator) #
- Add dependencies to your
pubspec.yaml
dependencies: to_string_helper: ^1.0.0 dev_dependencies: build_runner: ^1.0.0 to_string_helper_generator: ^1.0.0
- Configure your class
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 {/*...*/}
- Generate code (see build_runner)
pub run build_runner build
: run a single build and exit.pub run build_runner watch
: continuously run builds as you edit files.
- Use the generated code to produce output of
toString
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); } }
- 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: '; ')
- Default is a comma follow with a space:
null
value- Default:
@ToString(nullString: 'null')
- Change output of null value to
NULL
:@ToString(nullString: 'NULL')
- Default:
- Named and unnamed value
- Named value:
Bike{wheels=2}
. - Unnamed value:
Bike{2}
. - Default:
@ToString(unnamedValue: false)
. - If
unnamedValue
istrue
, 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; }
- Named value:
- 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; }
- Default:
- Pretty print (TODO)
- Separator
-
Exclude a specific field
@ToString() class Bike { @ToStringField(exclude: true) final wheels = 2; }
-
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 {/*...*/}
- Example using
-
Include/exclude inherited fields from super classes
By default, only declared fields in the annotated class are included in 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
andglobalInclude
work?- It checks
inclusion
map to determine which class should be scanned for the output. If the current annotated class is not found ininclusion
map, it adds automatically entry{Bike: Include()}
to the map. - If
globalInclude
is not specified,Include()
instance is created and used automatically. Include
ininclusion
map andglobalInclude
is merged. Below is an example how the attributenullValue
is merged.- If
inclusion[Bike].nullValue
isnull
, checkglobalInclude.nullValue
. - If
globalInclude.nullValue
isnull
, fallback to defaultInclude
attribute value.
- If
- Default
Include
attribute values:nullValue
:true
nonStatic
:true
static
:false
public
:true
private
:false
- It checks