MooLah - Developer Guide

The undo and redo functionality is facilitated by ModelHistory, which is available as an instance-level member of Model. It keeps track of the model’s history by storing the changed fields of the model throughout execution, which will be represented as ModelChanges. Internally, ModelHistory stores the history by using two stacks of ModelChanges, namely, pastChanges and futureChanges.

With the addition of model history, Model can support these operations:

To support these capabilities, ModelChanges offers these methods as well:

Refer to the class diagram below for comprehensive list of the methods offered and the association of both classes:

ModelHistory only stores changes of models that were (or are going to be) executed by model-manipulating - or simply, undoable - commands. As some of the commands available are intuitively not undoable (e.g. help), every command is configured to extend either UndoableCommand or a non-undoable Command classes. With the division, Model#commit(String, Model) will only be called if the command to be executed is an instance of UndoableCommand.

Given below is an example usage scenario and how the undo and redo functionality behaves at each step.

Step 1. The user launches the application for the first time. The current ModelHistory is now empty.

Step 2. The user executes addexpense d/chicken rice p/2.50 c/food command to add an expense. The addexpense command, being an UndoableCommand, calls Model#commit(String, Model), which saves the state of the model just before the command executes to pastChanges, and futureChanges is cleared.

Step 3. The user executes deleteexpense-primary 1 to delete the first expense on the list. The deleteexpense-primary command, also an UndoableCommand, calls Model#commit(String, Model), inserting another entry to the pastChanges and clearing futureChanges again.

Step 4. The user now decides that deleting the expense was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#rollback(), which will retrieve the immediate previous change in history, adding the reverting change to the future history of the model, and applies the change to the model.

Step 5. The user then realizes the expense should be deleted after all, and wishes to redo the deletion by entering the redo command. The command will call Model#migrate(), which will get the immediate next change in history, adding the reverting change to the past history, and applies the change to the model.

The following sequence diagram shows how the undo command works:

Inversely, the redo command calls Model#migrate(), which retrieves the immediate next changes in history, adds the reverting change to the past history, and applies the changes to the model.

As explained earlier, additions of entry to ModelHistory will only be performed when the command being executed is an instance of UndoableCommand. The following diagram briefly describes how the execution of undoable commands will do so:

In implementing the undo and redo functionality, some design approaches and trade-offs have to be considered to account for feature efficiency in computation time and memory usage.

Each menu item is stored as a MenuItem object, which has a description and price. These items are then contained in Menu, within the list of accepted menu items. Whenever the user enters the addmenuexpense command with a menu-item description, MooLah will look up the list of expenses in Menu that matches the description, and if there is such menu item, it will add

See the class diagram below for available methods on Menu and MenuItem:

Given below is an example usage scenario and how the add menu-item expense feature is processed within MooLah:

Budgets form a partition of all expenses. That is, an Expense must belong to one and only one Budget, and all expenses from all Budget must add up to the total number in the general expense list. Each Expense keeps track of its own Budget through the budgetName attribute — this is possible because UniqueBudgetList disallows duplicate budget names. On the other hand, each Budget keeps track of a list of Expense added to this budget, as shown in the figure below.

There are five commands related to the addition, modification and removal of budgets, namely: AddBudgetCommand, EditBudgeCommand, DeleteBudgetByIndexCommand, DeleteBudgetByNameCommand, and ClearBudgetsCommand.

Here is the class diagram of AddBudgetCommand:

As shown in the figure above, AddBudgetCommand has 2 methods: (i) validate(model), which checks whether the command is legal (i.e. will not result in duplicate budgets being added to MooLah), and throws CommandException to notify user of the illegal input if any; (ii) execute(model), which runs this command in model and successfully adds a new Budget.

The following sequence diagram shows how the add budget operation works:

As shown in the figure above, when user inputs "addbudget …​", LogicManager executes the String, and MooLahParser creates the corresponding CommandParser which parses the input into an AddBudgetCommand. AddBudgetCommand then validates itself by checking if there is an identical Budget already existing in MooLah. If no duplicate budgets are found, it executes the command, adding the new Budget to MooLah. After that, AddBudgetCommand creates a CommandResult and passes it back to LogicManager. LogicManager then saves the updated MooLah as Json file, and returns the CommandResult to GUI to be displayed to user.

The implementation of other commands follows a similar flow as AddBudgetCommand, differing only in the parameters and corresponding methods in ModelManager. A noteworthy implementation in EditBudgetCommand is that it has a inner class EditBudgetDescriptor to record the updated attributes of the budget, which is then used in the method EditBudgetCommand#createEditedBudget(Budget, EditBudgetDescriptor) to create an edited Budget, maintaining non-updated attributes the same as the original Budget.

When a Budget is edited, the original budget’s expenses will be transferred to the updated budget through Budget#transferExpensesTo(Budget other). The transfer process does two things: (i) set the expenses’s budgetName to the new budget’s name; (ii) add the expenses to the new budget’s expense list. Similarly, when a Budget is deleted, all its expenses will be transferred to Default Budget through the same method.

At any time, there is one, and only one, primary budget in MooLah. All expenses added will go to this primary budget. If the user wants to track expenses under a different budget, he switches to the target budget first, before adding the expense. A newly created budget is automatically set to primary. MooLah creates a Default Budget upon first launching. If no budget is created by the user, expenses will be tracked under this Default Budget, which has a huge budget limit (10^21) and budgeting period (100 years).

The SwitchBudgetCommand takes in a budget name and switches primary budget to that budget. Given below is an example usage scenario of SwitchBudgetCommand:

Step 1. The user launches MooLah for the first time. The default budget will be created and set as the primary budget.

Step 2. The user adds an expense "bubble tea". Since the default budget is the primary one, this expense will go under default budget.

Step 3. The user creates a budget "School". Since "School" is newly added, it will be set as the primary budget.

Step 4. The user adds an expense "chicken rice". Since "School" is the primary budget, this expense will go under "School".

Step 5. The user now wants to add another expense "movie", but does not want it tracked under "School". As such, the user executes switchbudget d/default budget. The default budget is now the primary budget.

Step 6. The user adds the expense "movie", which is tracked under the current primary budget - default budget.

A budget is like a sliding window that moves along the time axis. The window has a fixed size determined by BudgetPeriod, an enum class with five values: DAY, WEEK, MONTH, YEAR, INFINITY (for Default Budget). Only expenses within the current window are shown in the app. Every time the budget refreshes, the window "slides" to the next period, starting with an empty screen that gradually gets populated with newly added expenses over time. This is achieved through the BudgetWindow class.

Here is the class diagram of BudgetWindow:

As shown in the figure above, BudgetWindow has 3 attributes: startDate, endDate, and period. The start and end dates are modifiable, but the period is fixed. This corresponds to the above-mentioned "sliding window" concept.

A budget keeps a list of all expenses ever been tracked by this budget, including historical ones. Additionally, it has a method Budget#getCurrentPeriodExpenses() that filters from this list expenses within the current budgeting period, which in turn get to be shown on MooLah’s GUI.

When users want to view expenses in a past period, they can do so by executing SwitchPeriodCommand. This command takes in a Timestamp and switches the budget window to a period anchored by that Timestamp. This is achieved by BudgetWindow#normalize(Timestamp anchor) method.

Given below is an example usage scenario of SwitchPeriodCommand:

Step 1. The user has a monthly budget "school" that recurs on the 5th of each month. Suppose the current date is 10 Nov. As a result, the current budgeting period will be 5 Nov - 4 Dec.

Step 2. The user wants to view expenses in September. As such, the user executes switchperiod t/20-09 (20-09 is interchangeable with any other dates within 5 Sep - 4 Oct). This command calls BudgetWindow#normalize, which shifts the window’s start and end dates to 5 Sep and 4 Oct respectively, while maintaining the fixed period — MONTH. As a result, the user sees expenses tracked under the budget during 5 Sep - 4 Oct.

The BudgetWindow#normalize method is also called upon adding a new Budget to MooLah. No matter how far the start date inputted by the user is from now, it will be normalized to the current period, such that expenses added subsequently will correctly be reflected in the budget panel.

Each budget, once added, will recur infinitely. This is achieved by Budget#refresh(), along with the Timekeeper class. Every 0.05 second, Timekeeper checks if the system time is at day break, and call Budget#refresh() if necessary. Subsequently, BudgetWindow#normalize is called; the anchor passed in is current time. As a result, the Budget is successfully normalized to the current period.

ListBudgetsCommand updates Model’s FilteredBudgetList with a Predicate to show all budgets. The command returns a CommandResult with view request to BudgetListPanel.PANEL_NAME. Subsequently, MainWindow#changePanel(PanelName) will switch the currently shown panel to BudgetListPanel. ListBudgetsCommand has the same effect as "view budget list".

There are three classes related to the UI display of budgets:

The progress bar in BudgetCard shows the proportion used against the budget limit. This is calculated by Budget#calculateProportionUsed(), which divides the sum of all current period expenses against the budget limit, returning a Percentage that wraps the result (rounded to the nearest integer).

Besides, the budget also gives popup notification when proportion used reaches 50%, 90%, and 100%. These 3 status correspond to Budget#isHalf(), Budget#isNear() and Budget#isExceeded(). Before each command in MooLah is executed, the initial values of these 3 booleans are recorded by LogicManager#recordInitialPrimaryBudgetStatus(), which returns a boolean array of size 3. At the end of each command, the final values of these 3 booleans are recorded again by LogicManager#recordFinalPrimaryBudgetStatus(). The two arrays are then passed into MainWindow#showWarningIfAny() for a comparision, and if any values have changed, MainWindow#showPopupMessage() will show the corresponding pop up notification to remind the user of the budget progress.

Budget objects are stored in Json format, through the JsonAdaptedBudget class. The Json file has the same properties as the budget, except: (i) it flattens the BudgetWindow field into start date, end date and period, for clearer display; (ii) it stores a list of UniqueIdentifier to expenses, instead of a list of JsonAdaptedExpense.

The following activity diagram summarizes what happens to budgets when the app launches and when a new expense is added:

Budgeting-related commands integrate well with Undo-Redo feature, by extending UndoableCommand. Undoable commands are those modifying data in MooLah, for example, AddBudgetCommand and EditBudgetCommand. On the other hand, commands that only result in GUI changes, such as ListBudgetsCommand, are not undoable.

A difficulty here is to make every undo (or redo) change immediately reflected on GUI. Since undo rollbacks models, this dictates that every change must result in a new Budget object being created and replacing the old one. Otherwise, even though the change is effective in the back end, it might not show in the front end because the Budget in two models points to the same object. This issue is handled by Budget#deepCopy(), which is widely called from UniqueBudgetList, in every method that modifies the existing budgets.

The Events feature allows users to add events that are supposed to occur on a future date.

On launch, MooLah will remind users of upcoming events. While the app is open, MooLah will also notify the user about any events that have transpired, and allow them to automatically add these events as expenses.

Like expenses, events hold two Descriptions (one for its details and one for the budget it belongs to), a Price, a Timestamp and a Category. The setBudget method of Event is used for the Event to remember which budget it was added to. This facilitates the potential conversion of the Event into an Expense through the convertToExpense method. This method is called when the user accepts the automated addition of an expense from the corresponding event, into the budget that the event was added into a while back. Since Event’s fields are a subset of that of Expense, all its fields are passed into the Expense constructor during the conversion, and a unique identifier is then generated to complete the creation of the expense, allowing it to be added to MooLah.

The Events feature supports the addevent, deleteevent, editevent and listevent command words.

As mentioned earlier, MooLah displays reminders of upcoming events during launch. The implementation is shown below:

To allow for precise timekeeping of expenses and events as well as accurate prompting of transpired events, MooLah tracks system time every 0.05 seconds using a Timer running on a parallel thread. Using another Timer, MooLah then checks for transpired events every 2 seconds; an event is then deemed to have transpired if its timestamp has gone past system time. The following sequence diagram shows how MooLah handles transpired events:

The statistics feature allows users to have an alternative view for the entries in MooLah. It is facilitated by the Statistics interface, which is part of the model package, and is implemented by 3 classes PieChartStatistics, TabularStatistics and TrendStatistics. Each of the implementing classes will be invoked when their respective parsers detect its corresponding command word, which is statsbasic, statscompare and statstrend. The prefix configurations vary greatly between them as well as the visual representation they create.

Given below is a class diagram to summarise the relationship between Statistics and its implementing classes.

The main entries that Statistics interacts with are Expense class and the Budget class. The entire statistics features only supports the generating of statistics from only the current budget and responds to the different methods called by the current Budget object. Every successful interaction will force a switch to the Statistics Panel, where each of their different visual representations will be generated.

The following activity diagram summarizes how statistics are shown from a current budget after possible user inputs to modify the attributes of the budget.

In the following sections, the implementation details of one of the more complicated command words will be discussed, as well as its design considerations.

The purpose of the statsbasic command word is to request MooLah to visualise the total expenditure across expenses of different categories as a percentage of the total expenditure of all expenses tracked under the budget where the command is called. The visual representation used here will be a PieChart.

Given below is an example usage scenario and how the statsbasic command word is handled by MooLah.

Step 1. The user enters the command statsbasic sd/01-10-2019 ed/01-11-2019 to visualise the total percentage of each category as a percentage of total expenditure across all categories, in the primary budget. The command is received by MooLahParser, which then creates a StatsCommandParser object, to subsequently help to parse the input by the user.

Step 2. The newly created StatsCommandParser calls parse("stats sd/01-10-2019 ed/01-11-2019"), which in turns calls ArgumentTokenizer#tokenize("sd/01-10-2019 ed/01-11-2019", PREFIX_START_DATE, PREFIX_END_DATE) to split the arguments into its preamble(the start date and end date). This returns an ArgumentMultimap object, argMultimap containing the split input.

Step 3. The StatsCommandParser object creates a StatsDescriptor object desc to hold the start date and end date that was specified by the user. Depending on the presence of start date and end date, desc will be filled in differently.

If the start date and end date is both specified by the user, the end date will be checked to not be before the start date. If the end date happens to be before the start date, a ParseException will be thrown

Step 4. The filled desc will be returned to the LogicManager where a new StatsCommand object, statsCommand will be created with desc

Step 5. The LogicManager calls StatsCommand#run(), where the StatsCommand will be validated before getting executed.

Step 6. During execution, StatsCommand calls ModelManager#getPrimaryBudget() to retrieve the primary budget to calculate statistics from. After which, StatsCommand will call createPieChartStatistics, which takes in desc and the primary budget.

Step 7. To construct the time interval required for statistics, information from desc is being processed. If there are unspecified inputs inside desc, the time interval will be constructed with some information from the primary budget.

Step 8. The PieChartStatistics object will be created with the constructed interval as well as the expenses the primary budget tracks. After which, StatsCommand will call the PieChartStatistics implementation of populateData() to fill up its other fields

Step 9. StatsCommand calls ModelManager#setStatistics(statistics) which updates the Statistics attribute in ModelManager.

Step 10. A CommandResult is then created and returned to LogicManager, which will then force a switch to the Statistics Panel where a Pie Chart will be generated.

The following sequence diagram shows how the statsbasic operation works:

Figure 1. Sequence Diagram for executing a StatsCommand

Figure 2. below illustrates the details from Steps 2 to 4.

Figure 2. Reference Diagram for creating a StatsCommand

Figure 3. below illustrates the details from Steps 6 to 9.

Figure 3. Reference Diagram for creating a StatsCommand

When designing the interaction of the command word statsbasic, decisions have to be made on the most suitable visual representation for statsbasic particular use case.

These user defined Aliases are saved in an AliasMappings object within UserPref as seen in the above diagram. Internally, the AliasMappings object stores an Alias in a Map<Strings, Alias> object. With the addition of AliasMappings object to UserPref, UserPref supports these additional operations:

Due to the constraints of this project, the application had to be designed such that the main interaction between the user and the application was the Command Line Interface. However, this required the user to be able to remember the commands as well as the syntax for these commands, or be forced to heavily refer to the user guide or to refer to the error messages.

The Easier Command-Line feature was implemented to remove the need to refer to the user guide just to find out the syntax needed to use a command, as well as to provide some quality-of-life features found in most Command Line Interfaces not present in the original Address Book 3. This feature consists of several features:

The Syntax highlighting feature was implemented to make it easier to differentiate the different arguments after typing as well as to implement some basic realtime input validation. This feature utilises RichTextFX’s StyleClassTextArea to apply different styles to different regions of the text, and regular expressions to determine how to to highlight user input.

As it would be quite resource intensive to recalculate the syntax highlighting every time the user types, the updated highlighting is only computed after a delay of 300 milliseconds after the user stops typing.

When the MainWindow is initialized and the inner UI parts are created, the commands which are supported by the syntax highlighting feature are configured. Each SyntaxHighlightingSupportedInput object contains a CommandWord to highlight prefixes the command supports. When it is created it creates a regex pattern such as below.

This pattern is used to find the command word in the user input, as well as the prefixes.

The Suggestion feature is the main part of this feature and provides users with suggestions of valid inputs they may need. There are three states of the suggestion feature

When the user chooses to disable the feature, the suggestion feature does not analyse the user input.

When the user chooses to enable it, if the user has only entered one or zero tokens (a string of characters without spaces), the suggestion menu will be populated with command words which begin with the user input. If the user has entered multiple tokens, and the command word (first token) if a valid command, the suggestion menu searches for the command’s supported prefixes and populates the menu with the prefixes the user has not entered yet.

This feature uses the ArgumentTokenizer from the Logic to determine what prefixes are present in the input and which ones have yet to be provided by the user.

This feature enables users to re-enter previous input without having to retype the entire input. It is a relatively simple feature which saves user input into a list and iterates through the list when the user presses the up or down arrow keys. When a user enters a new input, the position of the iterator is reset.

This feature allows allows different commands to use the same command word. As MooLah has around 30 commands with only the current features, it may becomes a problem that command words become very long in order to make it clear what the command does when there are multiple commands which do similar things in different context. This feature reduces the ambiguity of a command by enabling certain common command words to behave differently depending on which panel of the UI the user is viewing.