Merge pull request #20 from ilopX/add-official-example-memento-pattern

Add "Memento" pattern, conceptual example from book.

Author: neochief

CHANGELOG.md

@@ -1,15 +1,18 @@
+## 0.14.0
+- Add "Memento" conceptual pattern
+
 ## 0.13.0
-- Add "Observer" pattern from official book, rewritten from Java example.
+- Add "Observer" pattern from official book, rewritten from Java example
 
 ## 0.12.19
 - Refactoring: reformatting and minor changes
 
 ## 0.12.5
-- Put "Shapes" prototype pattern to "Shapes" folder.
-- The list of patterns has been updated. Added links to projects.
+- Put "Shapes" prototype pattern to "Shapes" folder
+- The list of patterns has been updated. Added links to projects
 
 ## 0.12.0
-- Add "Command" pattern from official book, rewritten from Java example.
+- Add "Command" pattern from official book, rewritten from Java example
 
 ## 0.11.0
 - Add "Chain of Responsibility" pattern from official book, rewritten from Java example
@@ -35,7 +38,7 @@
 - Add bridge pattern. Device remote control
 
 ## 0.5.5
-- Add example "graphics engine" and "square round conflict"  for adapter pattern
+- Add example "graphics engine" and "square round conflict"  for adapter patter
 - Add description to prototype pattern
 - Fix class diagram for text graph
 - Add description Builder pattern, text formats

README.md

@@ -15,7 +15,7 @@ It contains **Dart** examples for all classic **GoF** design patterns.
     - [ ] Interpreter
     - [ ] [**Iterator**](https://refactoring.guru/design-patterns/iterator)
     - [ ] [**Mediator**](https://refactoring.guru/design-patterns/mediator)
-    - [ ] [**Memento**](https://refactoring.guru/design-patterns/memento)
+    - [x] [**Memento**](https://refactoring.guru/design-patterns/memento) [[Conceptual](https://github.com/RefactoringGuru/design-patterns-dart/tree/master/patterns/memento/conceptual)]
     - [x] [**Observer**](https://refactoring.guru/design-patterns/observer) - [[Open-Close Editor Events](https://github.com/RefactoringGuru/design-patterns-dart/tree/master/patterns/observer/open_close_editor_events)]
     - [ ] [**State**](https://refactoring.guru/design-patterns/state)
     - [ ] [**Template Method**](https://refactoring.guru/design-patterns/template-method)

patterns/memento/conceptual/README.md

@@ -0,0 +1,39 @@
+# Memento pattern
+Memento is a behavioral design pattern that lets you save and restore the previous state of an 
+object without revealing the details of its implementation.
+
+Tutorial: [here](https://refactoring.guru/design-patterns/memento).
+
+## Conceptual Editor example 
+This example uses the Memento pattern alongside the Command pattern for storing snapshots of the 
+complex text editor’s state and restoring an earlier state from these snapshots when needed.
+
+More detailed explanation on [RefactoringGuru](https://refactoring.guru/design-patterns/memento?#pseudocode).
+
+### Diagram:
+![image](https://user-images.githubusercontent.com/8049534/151352367-c97db094-fc87-4eb2-9210-581914c57ced.png)
+
+### Client code:
+```dart
+void main() {
+  final editor = Editor('New Document');
+  final firstState = Command.makeBackup(editor);
+  editor.text += ' add text';
+  final secondState = Command.makeBackup(editor);
+
+  print('Current state: "${editor.text}"');
+
+  firstState.undo();
+  print('First state: "${editor.text}"');
+
+  secondState.undo();
+  print('Second state: "${editor.text}"');
+}
+```
+
+**Output:**
+```
+Current state: "New Document add text"
+First state: "New Document"
+Second state: "New Document add text"
+```

patterns/memento/conceptual/main.dart

@@ -0,0 +1,96 @@
+void main() {
+  final editor = Editor('New Document');
+  final firstState = Command.makeBackup(editor);
+  editor.text += ' add text';
+  final secondState = Command.makeBackup(editor);
+
+  print('Current state: "${editor.text}"');
+
+  firstState.undo();
+  print('First state: "${editor.text}"');
+
+  secondState.undo();
+  print('Second state: "${editor.text}"');
+}
+
+/// EN: The originator holds some important data that may change over
+/// time. It also defines a method for saving its state inside a
+/// memento and another method for restoring the state from it.
+///
+/// RU: Класс создателя должен иметь специальный метод, который.
+/// сохраняет состояние создателя в новом объекте-снимке.
+class Editor {
+  var text = '';
+  var curX = 0;
+  var curY = 0;
+  var selectionWidth = 0;
+
+  Editor(this.text);
+
+  /// EN: Saves the current state inside a memento.
+  Snapshot createSnapshot() {
+    /// EN: Memento is an immutable object; that's why the
+    /// originator passes its state to the memento's
+    /// constructor parameters.
+    ///
+    /// RU: Снимок — неизменяемый объект, поэтому Создатель
+    /// передаёт все своё состояние через параметры
+    /// конструктора.
+    return Snapshot(this, text, curX, curY, selectionWidth);
+  }
+}
+
+/// EN: The memento class stores the past state of the editor.
+///
+/// RU: Снимок хранит прошлое состояние редактора.
+class Snapshot {
+  final Editor _editor;
+  final String _text;
+  final int _curX;
+  final int _curY;
+  final int _selectionWidth;
+
+  Snapshot(
+    this._editor,
+    this._text,
+    this._curX,
+    this._curY,
+    this._selectionWidth,
+  );
+
+  /// EN: At some point, a previous state of the editor can be
+  /// restored using a memento object.
+  ///
+  /// RU: В нужный момент владелец снимка может восстановить
+  /// состояние редактора.
+  void restore() {
+    _editor
+      ..text = _text
+      ..curX = _curX
+      ..curY = _curY
+      ..selectionWidth = _selectionWidth;
+  }
+}
+
+/// EN: A command object can act as a caretaker. In that case, the
+/// command gets a memento just before it changes the
+/// originator's state. When undo is requested, it restores the
+/// originator's state from a memento.
+///
+/// RU: Опекуном может выступать класс команд (см. паттерн Команда).
+/// В этом случае команда сохраняет снимок состояния объекта-
+/// получателя, перед тем как передать ему своё действие. А в
+/// случае отмены команда вернёт объект в прежнее состояние.
+class Command {
+  Snapshot _backup;
+
+  Command._(this._backup);
+
+  factory Command.makeBackup(Editor editor) {
+    return Command._(editor.createSnapshot());
+  }
+
+  void undo() {
+    _backup.restore();
+  }
+}

pubspec.yaml

@@ -1,6 +1,6 @@
 name: design_patterns_dart
 description: Dart examples for all classic GoF design patterns.
-version: 0.13.0
+version: 0.14.0
 homepage: https://refactoring.guru/design-patterns
 repository: https://github.com/RefactoringGuru/design-patterns-dart
 issue_tracker: https://github.com/RefactoringGuru/design-patterns-dart/issue