feat: All all formatters

lib/formatter.dart

@@ -0,0 +1,20 @@
+/// [DateTime] formatter.
+///
+/// This library provides a set of functions to format [DateTime] objects.
+library odroe.now.formatter;
+
+export 'src/formatter/formatter.dart';
+export 'src/formatter/token.dart';
+export 'src/formatter/tokenizer.dart';
+
+// Formatters
+export 'src/formatter/formatters/ampm_formatter.dart';
+export 'src/formatter/formatters/day_formatter.dart';
+export 'src/formatter/formatters/hour_formatter.dart';
+export 'src/formatter/formatters/millisecond_formatter.dart';
+export 'src/formatter/formatters/minute_formatter.dart';
+export 'src/formatter/formatters/month_formatter.dart';
+export 'src/formatter/formatters/quarter_formatter.dart';
+export 'src/formatter/formatters/second_formatter.dart';
+export 'src/formatter/formatters/timezone_formatter.dart';
+export 'src/formatter/formatters/year_formatter.dart';

lib/now.dart

@@ -4,3 +4,4 @@ library odroe.now;
 
 export 'src/duration.dart';
 export 'src/datetime.dart';
+export 'src/now.dart';

lib/src/datetime.dart

@@ -1,3 +1,5 @@
+import 'formatter/tokenizer.dart';
+
 /// [DateTime] extension for adding, subtracting.
 ///
 /// ## Add
@@ -83,3 +85,15 @@ extension DateTimeUtc on DateTime {
   /// Always return a UTC [DateTime].
   DateTime get utc => isUtc ? this : toUtc();
 }
+
+/// [DateTime] extension for formatting.
+///
+/// ## Format
+/// ```dart
+/// print(DateTime.now().format('yyyy-MM-dd')); // 2021-01-01
+/// ```
+extension DateTimeFormat on DateTime {
+  /// Format [DateTime] with the given [pattern].
+  String format(String pattern) =>
+      DateTimePatternTokenizer.parse(pattern).format(this);
+}

lib/src/formatter/formatter.dart

@@ -0,0 +1,39 @@
+/// [DateTime] formatter.
+///
+/// Custom formatter can be created by extending this class.
+/// The [format] method must be implemented.
+///
+/// Example:
+/// ```dart
+/// class CustomFormatter implements DateTimeFormatter {
+///     const CustomFormatter();
+///
+///     @override
+///     String format(DateTime date) {
+///       // Format the date and return the formatted string.
+///     }
+///
+///     @override
+///     String get specifier => 'custom';
+/// }
+/// ```
+abstract class DateTimeFormatter {
+  /// Format the given [date] and return the formatted string.
+  ///
+  /// The format specifiers are case-sensitive.
+  ///
+  /// The following table lists the available format specifiers:
+  ///
+  /// | Specifier | Meaning | Example |
+  /// |-----------|---------|---------|
+  /// | `YYYY` | Year with 4 digits | `2019` |
+  /// | `YY` | Year with 2 digits | `19` |
+  /// | `MMMM` | Month name | `January` |
+  /// | ... | ... | ... |
+  String format(DateTime date);
+
+  /// Defined the format specifier.
+  ///
+  /// **Note**: The format specifiers are case-sensitive.
+  String get specifier;
+}

lib/src/formatter/formatters/ampm_formatter.dart

@@ -0,0 +1,37 @@
+import '../formatter.dart';
+
+/// Upper cased AM/PM formatter.
+///
+/// ```dart
+/// final formatter = AmpmUpperCaseFormatter();
+///
+/// print(formatter.format(now())); // AM or PM
+/// ```
+class AmpmUpperCaseFormatter implements DateTimeFormatter {
+  /// Creates a new [AmpmUpperCaseFormatter] instance.
+  const AmpmUpperCaseFormatter();
+
+  @override
+  String format(DateTime date) => date.hour < 12 ? 'AM' : 'PM';
+
+  @override
+  String get specifier => 'A';
+}
+
+/// Lower cased am/pm formatter.
+///
+/// ```dart
+/// final formatter = AmpmLowerCaseFormatter();
+///
+/// print(formatter.format(now())); // am or pm
+/// ```
+class AmpmLowerCaseFormatter extends AmpmUpperCaseFormatter {
+  /// Creates a new [AmpmLowerCaseFormatter] instance.
+  const AmpmLowerCaseFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).toLowerCase();
+
+  @override
+  String get specifier => 'a';
+}

lib/src/formatter/formatters/day_formatter.dart

@@ -0,0 +1,84 @@
+import '../formatter.dart';
+
+/// Day of the month formatter, `[1...31]`.
+class DayOfMonthFormatter implements DateTimeFormatter {
+  /// Creates a new [DayOfMonthFormatter] instance.
+  const DayOfMonthFormatter();
+
+  @override
+  String format(DateTime date) => date.day.toString();
+
+  @override
+  String get specifier => 'D';
+}
+
+/// Day of the month formatter, `[01...31]`.
+class DayOfMonthTwoDigitsFormatter extends DayOfMonthFormatter {
+  /// Creates a new [DayOfMonthTwoDigitsFormatter] instance.
+  const DayOfMonthTwoDigitsFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).padLeft(2, '0');
+
+  @override
+  String get specifier => 'DD';
+}
+
+/// Day of the week formatter, `[1...7]`.
+class DayOfWeekFormatter implements DateTimeFormatter {
+  /// Creates a new [DayOfWeekFormatter] instance.
+  const DayOfWeekFormatter();
+
+  @override
+  String format(DateTime date) => date.weekday.toString();
+
+  @override
+  String get specifier => 'd';
+}
+
+/// Day of the week full name formatter.
+class DayOfWeekFullFormatter implements DateTimeFormatter {
+  /// Full day names.
+  static const days = [
+    'Monday',
+    'Tuesday',
+    'Wednesday',
+    'Thursday',
+    'Friday',
+    'Saturday',
+    'Sunday',
+  ];
+
+  /// Creates a new [DayOfWeekFullFormatter] instance.
+  const DayOfWeekFullFormatter();
+
+  @override
+  String format(DateTime date) => days.elementAt(date.weekday - 1);
+
+  @override
+  String get specifier => 'dddd';
+}
+
+/// Day of the week Short name formatter.
+class DayOfWeekShortFormatter extends DayOfWeekFullFormatter {
+  /// Creates a new [DayOfWeekShortFormatter] instance.
+  const DayOfWeekShortFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).substring(0, 3);
+
+  @override
+  String get specifier => 'ddd';
+}
+
+/// Day of the week min name formatter.
+class DayOfWeekMinFormatter extends DayOfWeekFullFormatter {
+  /// Creates a new [DayOfWeekMinFormatter] instance.
+  const DayOfWeekMinFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).substring(0, 2);
+
+  @override
+  String get specifier => 'dd';
+}

lib/src/formatter/formatters/hour_formatter.dart

@@ -0,0 +1,49 @@
+import '../formatter.dart';
+
+/// Hour of the day formatter, `[0...23]`.
+class HourOfDayFormatter implements DateTimeFormatter {
+  /// Creates a new [HourOfDayFormatter] instance.
+  const HourOfDayFormatter();
+
+  @override
+  String format(DateTime date) => date.hour.toString();
+
+  @override
+  String get specifier => 'H';
+}
+
+/// Hour of the two digits formatter, `[00...23]`.
+class HourOfDayTwoDigitsFormatter extends HourOfDayFormatter {
+  /// Creates a new [HourOfDayTwoDigitsFormatter] instance.
+  const HourOfDayTwoDigitsFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).padLeft(2, '0');
+
+  @override
+  String get specifier => 'HH';
+}
+
+/// 12-hour clock hour of the day formatter, `[1...12]`.
+class HourOfDay12Formatter implements DateTimeFormatter {
+  /// Creates a new [HourOfDay12Formatter] instance.
+  const HourOfDay12Formatter();
+
+  @override
+  String format(DateTime date) => (date.hour % 12).toString();
+
+  @override
+  String get specifier => 'h';
+}
+
+/// 12-hour clock hour of the two digits formatter, `[01...12]`.
+class HourOfDay12TwoDigitsFormatter extends HourOfDay12Formatter {
+  /// Creates a new [HourOfDay12TwoDigitsFormatter] instance.
+  const HourOfDay12TwoDigitsFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).padLeft(2, '0');
+
+  @override
+  String get specifier => 'hh';
+}

lib/src/formatter/formatters/millisecond_formatter.dart

@@ -0,0 +1,13 @@
+import '../formatter.dart';
+
+/// Millisecond of the second formatter, `[0...999]`.
+class MillisecondFormatter implements DateTimeFormatter {
+  /// Creates a new [MillisecondFormatter] instance.
+  const MillisecondFormatter();
+
+  @override
+  String format(DateTime date) => date.millisecond.toString();
+
+  @override
+  String get specifier => 'SSS';
+}

lib/src/formatter/formatters/minute_formatter.dart

@@ -0,0 +1,25 @@
+import '../formatter.dart';
+
+/// Minute of the hour formatter, `[0...59]`.
+class MinuteFormatter implements DateTimeFormatter {
+  /// Creates a new [MinuteFormatter] instance.
+  const MinuteFormatter();
+
+  @override
+  String format(DateTime date) => date.minute.toString();
+
+  @override
+  String get specifier => 'm';
+}
+
+/// Minute of the hour two digits formatter, `[00...59]`.
+class MinuteTwoDigitsFormatter extends MinuteFormatter {
+  /// Creates a new [MinuteTwoDigitsFormatter] instance.
+  const MinuteTwoDigitsFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).padLeft(2, '0');
+
+  @override
+  String get specifier => 'mm';
+}

lib/src/formatter/formatters/month_formatter.dart

@@ -0,0 +1,77 @@
+import '../formatter.dart';
+
+/// Month between `[1...12]` formatter.
+class MonthFormatter implements DateTimeFormatter {
+  /// Creates a new [MonthFormatter] instance.
+  const MonthFormatter();
+
+  @override
+  String format(DateTime date) => date.month.toString();
+
+  @override
+  String get specifier => 'M';
+}
+
+/// Month between `[01...12]` formatter.
+class MonthTwoDigitsFormatter extends MonthFormatter {
+  /// Creates a new [MonthTwoDigitsFormatter] instance.
+  const MonthTwoDigitsFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).padLeft(2, '0');
+
+  @override
+  String get specifier => 'MM';
+}
+
+/// Month full name formatter.
+///
+/// Example:
+/// ```dart
+/// final formatter = MonthFullFormatter();
+/// print(formatter.format(now())); // December
+/// ```
+class MonthFullFormatter implements DateTimeFormatter {
+  /// Full month names.
+  static const months = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+  ];
+
+  /// Creates a new [MonthFullFormatter] instance.
+  const MonthFullFormatter();
+
+  @override
+  String format(DateTime date) => months.elementAt(date.month - 1);
+
+  @override
+  String get specifier => 'MMMM';
+}
+
+/// Month abbreviated name formatter.
+///
+/// Example:
+/// ```dart
+/// final formatter = MonthAbbreviatedFormatter();
+/// print(formatter.format(now())); // Dec
+/// ```
+class MonthAbbreviatedFormatter extends MonthFullFormatter {
+  /// Creates a new [MonthAbbreviatedFormatter] instance.
+  const MonthAbbreviatedFormatter();
+
+  @override
+  String format(DateTime date) => super.format(date).substring(0, 3);
+
+  @override
+  String get specifier => 'MMM';
+}

lib/src/formatter/formatters/quarter_formatter.dart

@@ -0,0 +1,13 @@
+import '../formatter.dart';
+
+/// Quarter of the year formatter, `[1...4]`.
+class QuarterFormatter implements DateTimeFormatter {
+  /// Creates a new [QuarterFormatter] instance.
+  const QuarterFormatter();
+
+  @override
+  String format(DateTime date) => ((date.month - 1) ~/ 3 + 1).toString();
+
+  @override
+  String get specifier => 'Q';
+}