Calgo - Developer Guide

The specified feature is facilitated by a ReportGenerator object. If you are interested in how ReportGenerator fits into the architecture of Calgo, refer to this section.

To learn how the report command works, the most important method that you need to know is the generateReport() method from the ReportGenerator class.

Refer to the sequence diagram below to understand the top-level execution of the generateReport() operation after the user enters a valid report command.

From the above diagram, creating a report for the consumption patterns on 27th of March 2020 involves the following steps:

Step 1: User inputs report d/2020-03-27 to generate the insights report based on food consumption of the abovementioned date.

Step 2: This input is saved as a String and passed into the LogicManager.

Step 3: The String input is parsed by CalgoParser, which removes the "d/" Prefix and sends the date input to ReportCommandParser.

Step 4: Once the ReportCommandParser checks that the given date is valid, it creates a ReportCommand object and returns it to LogicManager.

Step 5: LogicManager then executes the ReportCommand.

Step 6: From Model, ReportCommand retrieves the required objects to construct an instance of ReportGenerator.

Step 7: With the relevant objects retrieved from Steps 6, ReportCommand constructs a ReportGenerator object.

Step 8: Using the ReportGenerator object, ReportCommand invokes the crucial method generateInsights(), which prints neatly organised sections of analysed data based on the DailyFoodLog of the input date. For the section that gives insights related to the user’s favourite Food, the past seven days of DailyFoodLog objects are analysed.

Step 9: This newly generated report is saved in the data/reports folder. If the report is successfully generated, the CommandResult is true. Otherwise, it is false. This CommandResult object is finally returned to LogicManager, to signify the end of the command and GUI shows a result message to the user.

Many of the design considerations made for report command are similar to that of the export command. You can check out the similar design considerations over here.

In addition to those design considerations, the following consideration is specific to the functionality of the report command.

The following activity diagram summarizes what happens when user executes a report d/DATE command with a correctly formatted date:

You can check out this code snippet to see how the ReportCommand object determines if there are no Food entries present in the given date:

In addition to the GoalCommandParser, the goal command relies heavily on the DailyGoal class, which is part of the Model component. Refer to the Model component diagram here.

To address the issue where a user does not want to set up a daily calorie goal, Calgo places a DUMMY_VALUE of 0 calories, as shown in the code snippet below, from DailyGoal class. To cater to a wide range of users, it also has a broad range of acceptable values, ranging from 1 to 99999. However, to guide users towards a healthy lifestyle, the App does display a warning message whenever a user sets a goal below the MINIMUM_HEALTHY_CALORIES.

Refer to the sequence diagram below to understand how a goal command is executed. .Sequence Diagram for goal command: updating daily calorie goal to 2000 calories.

The following steps explain the sequence diagram:

Step 1: User inputs goal 2000 to update his or her goal to 2000 calories.

Step 2: This input is saved as a String and passed into the LogicManager.

Step 3: The String input is parsed by CalgoParser, which sends the goal value input to GoalCommandParser.

Step 4: Once the GoalCommandParser checks that the given value is valid, it converts the input to an Integer and creates a GoalCommand object and returns it to LogicManager.

Step 5: LogicManager then executes the GoalCommand, which in turn invokes updateDailyGoal method of Model.

Step 6: In Model, the updateDailyGoal method is a static method that generates a new DailyGoal object with the corresponding input. This DailyGoal object is returned to Model , which replaces the existing DailyGoal attribute of the ModelManager with the newly generated DailyGoal object.

In essence, the goal command is a fun feature that is used to motivate the user and generate specific insights if the user were to invoke the report command after setting a daily calorie goal.

Refer to the Activity Diagram below for a visual summary of the logic behind the execution of the goal command.

To search via a particular Food attribute, we use a FindCommandParser to create the corresponding Predicate<Food> based on which Food attribute the Prefix entered represents. This predicate is then used to construct a new FindCommand object, which changes the GUI display when executed.

The class diagram below shows the relevant Predicate<Food> classes used in the construction of FindCommand objects.

As seen in the above class diagram, each Predicate<Food> is indeed representative of either Name, Calorie, Protein, Carbohydrate, Fat, or Tag. Moreover, it should be noted that each of these predicates test against a Food object, and therefore have a dependency on Food.

The sequence diagram below demonstrates how the find command works, for both categorical and substring search:

From the above, it is clear that both categorical search and substring search of the find command have similar steps:

Step 1: LogicManager executes the user input, using CalgoParser to realise this is a find command, and a new FindCommandParser object is then created.

Step 2: The FindCommandParser object parses the user-entered arguments that come with the Prefix, creating a Predicate<Food> object based on which Food attribute the Prefix represents.

Step 3: This Predicate<Food> object is then used to construct a new FindCommand object, returned to LogicManager.

Step 4: LogicManager calls the execute method of the FindCommand created, which filters for Food objects that evaluate the predicate previously created to be true. It then returns a new CommandResult object reflecting the status of the execution. These changes are eventually reflected in the GUI.

The find command therefore searches through the existing FoodRecord and then displays the relevant search results in the GUI’s Food Record. To once again show all Food entries in the display, we use the list command.

In constrast to FindCommand, the ListCommand constructor takes in no arguments and simply uses the predicate Model.PREDICATE_SHOW_ALL_FOODS to always show all Food entries in its execute method. This is described by the sequence diagram below:

How the list command works:

Step 1: LogicManager executes the user input, using CalgoParser to realise this is a list command, and a new ListCommand object is created.

Step 2: LogicManager then calls the execute method of this ListCommand, which uses Model.PREDICATE_SHOW_ALL_FOODS to evaluate to true for all Food objects in the FoodRecord.

Step 3: LogicManager then returns a new CommandResult object to reflect the status of the execution, in the GUI. The GUI’s Food Record reflects the above changes to show all Food entries once again.

In essence, this section focuses on searching which is implemented via find and list commands.

The find command performs a categorical search if a value from a nutritional category (Calorie, Protein, Carbohydrate, Fat) is specified. Otherwise, a substring search is performed to find Food objects that contain the entered substring in their Name or in one of their Tag s. These rely on the Predicate<Food> object used in constructing the FindCommand, which depend on the Prefix entered by the user.

Meanwhile, the list command simply uses the predicate already defined in Model to display all Food objects.

The above can be summarised in the activity diagram below:

The UniqueFoodList is able to sort Food objects because the Food class implements the Comparable<Food> interface. This allows us to specify the lexicographical order for sorting Food objects via their Name, using the following compareTo method in the Food class:

How the sorting process works:

It should be noted that sorting is only performed by the addFood and setFoods method of the UniqueFoodList, which calls the sortInternalList method. Not to be confused, the setFood method, which is used when a Food object is edited, does not perform any sorting.

The sequence diagram below shows how the lexicographical ordering is performed when Calgo starts up:

Based on the above diagram, when Calgo starts:

Step 1: We initialise the ModelManager object. For this, we use previously stored user data if available (by reading in from the source json files). Otherwise, we use the default Calgo Food entries.

Step 2: Before we can finish constructing a new ModelManager object, we require the creation of a new FoodRecord object which in turn requires the creation of a new UniqueFoodList object.

Step 3: Once UniqueFoodList is constructed, we introduce the initialising data into it using the setFoods method. This calls the sortInternalList method, which sorts the newly added Food objects in the ObservableList<Food> contained in UniqueFoodList, according to the specified lexicographical order (defined in the Food class).

Moving on, the sequence diagram below (which is a reference frame omitting irrelevant update command details) describes the lexicographical sorting process when Food objects are added (not edited) using the update command:

Here, the diagram describes what happens after parsing the user input and creating an UpdateCommand object. Since the Food entered by the user is an entirely new Food object without a Name-equivalent Food existing in the UniqueFoodList:

Step 1: We call the respective addFood and add methods as seen in the diagram, eventually adding the Food object into the UniqueFoodList and arriving at its sortInternalList method call.

Step 2: The sortInternalList method then sorts the Food objects in the ObservableList<Food> contained in UniqueFoodList, according to the specified lexicographical order defined in the Food class.

Any re-ordering will eventually be reflected in the GUI, facilitated by the following (in the case of an update command) or otherwise something similar:

The UniqueFoodList facilitates the lexicographical ordering of Food objects and hence how their respective entries appear in the GUI Food Record. This can be summarised in the activity diagram below:

Most of the work in generating the file is done by the generateExport method of ExportGenerator. You can access the class to view its methods for writing the header and footer components, which are relatively easily to understand.

However, the methods for writing the file body is likely where some explaining is required. Here, the formatting of the table body is determined by the following:

NAME_COLUMN_SIZE represents the allowed space for the Name. If a Food object has a Name which is too long, the Name will be truncated and continued on the following lines. Meanwhile, VALUE_COLUMN_SIZE represents the allowed space for each nutritional value of Calorie, Protein, Carbohydrate, and Fat in the table. These are guaranteed to be within a length of 5 characters when parsing, and should not exceed the given space.

The nutritional values will always be shown in the first line of their respective Food object after its (possibly truncated) Name. This is facilitated by the printBody method of ExportGenerator, which calls its printBodyComponent method and subsequently its generateFinalisedEntryString method, which performs the truncation and amendment of the Name as necessary.

Moving on, the sequence diagram below demonstrates how the export command works to create the user copy of the current FoodRecord:

From the above, creating FoodRecord.txt involves the following steps:

Step 1: LogicManager executes the user input, using CalgoParser to realise this is a export command, and a new ExportCommand object is created.

Step 2: LogicManager then calls the execute method of this ExportCommand object. This results in a call to the Model to get the current FoodRecord, which is used to construct a new ExportGenerator object. The ExportGenerator is responsible for creating the FoodRecord.txt file and writing to it.

Step 3: ExportCommand then calls the generateExport method of ExportGenerator, writing the required parts to the file. This returns a boolean indicating whether the file creation and writing are successful.

Step 4: A new CommandResult object indicating the result of the execution is then constructed and reflected in the GUI.

In short, this section addresses how users are able to obtain an editable copy of the current FoodRecord using the export command.

The export command largely relies on the ExportGenerator class, which facilitates creating the file and writing to it.

The above can be summarised in the activity diagram below:

In this section, I will be walking you through the implementation of the ConsumptionRecord, what happens on App startup, and what happens when a consumption related command is called. I will be talking about the nom command more specifically. This is because vomit and stomach work very similarly, and you will see that it’s easy to understand once you have read through this section.

In Calgo, you will find that the GUI ConsumptionRecord use a uniqueDateToLogMap to map each LocalDate to a DailyFoodLog. As you can guess, LocalDate keys are unique.
Each DailyFoodLog is related to a LocalDate object and contains 2 LinkedHashMap, one to map Food consumed to their portion, another to map Food to an ArrayList of Integer, which represents the ratings given to that Food item consumed on that day.

On App startup, initModelManager of MainApp class is invoked. This will cause storage to read consumption record data from a .json file which stores App data. The .json file stores JsonAdaptedDailyFoodLog, which is similar to DailyFoodLog in every way, but deals with JsonAdaptedFood class instead of Food. Notice that there are a chain of toModelType commands called as we dive deeper into the method call stack. toModelType is actually the method to return a working counterpart of JsonSerializable and JsonAdapted classes that will be delivered to the model of Calgo.

Here is what happens when different classes call toModelType:

Below shows the high level view of the initialization process:

Now that the ConsumptionRecord has been initialized, the App can start interacting with the user.

Whenever the user enters a nom command into the GUI, a sequence of events occur. Here is a a step-by-step guide to what happens in such a scenario:

Step 1: UI component MainWindow receives the input as a String. That String is then passed into LogicManager, which calls the parseCommand of CalgoParser. Suppose the String is "nom n/Apple d/2020-04-12 portion/2 r/7" CalgoParser detects that this is a nom command. CalgoParser then delegates this job by creating a new NomCommandParser object which will parse this String.

Step 2: NomCommandParser gets relevant values from Prefixes of input String, and then checks with the ModelManager. It specifically checks if there exists a DailyFoodLog with the same LocalDate as what was parsed so that it can use existing information if they are already present. From all these information, a DailyFoodLog object representing the result of consuming a Food is created, and supplied to create NomCommand. The diagram below shows how this happens:

Step 3: NomCommand updates the ModelManager with the DailyFoodLog obtained during its execution by LogicManager. Such information cascades down the layers of abstraction until it reaches ConsumptionRecord, which updates its underlying 'uniqueDateToLogMap' aforementioned here.

Step 4: NomCommand then informs the ModelManager to update its FilteredList, which gets information from the updated ConsumptionRecord. Since the FilteredList is a wrapper of ObservableList, its update will inform the UI components that utilise JavaFx of changes. This results in the GUI automatically updating to reflect the changes.

Step 5: A new commandResult object is created an passed back to MainWindow, and displayed in Result Display.

Step 6: Finally, the changes in ConsumptionRecord are saved to StorageManager.

This section is a summary on all the above discussed. I would do so with the aid of a few activity diagrams so that you are clear about the flow of the processes covered.

The 2 diagrams below serves as (rakes), which shows more details.

The modification of the FoodRecord is facilitated by UniqueFoodList, which is responsible for storing all the Food entries in the FoodRecord. Additional abstractions were used by Model and Logic for any operations that results in a modification of the UniqueFoodList.

Both commands require an additional operation, hasFood, in FoodRecord to be implemented. hasFood checks if there is an existing Food in FoodRecord by checking if there is any Food in the FoodRecord with the same Name. Two Food entries is deemed to be of the same Name if their lowercase variant is the same.

This operation was exposed in the Model interface as hasFood, allowing UpdateCommand and DeleteCommand this functionality.

In summary, this section explains how commands related to modifying the FoodRecord is implemented.

The update command is a smart command that either updates an existing Food entry in the FoodRecord with new nutritional information, or updates a new Food item into the FoodRecord The following activity diagram summarises what happens when a user enters a valid update command:

The delete command allows the user to remove a Food entry from the FoodRecord by specifying it’s Name as an parameter. The following activity diagram summarises what happens when a user enters a valid 'delete' command:

To be able to process user’s input in real-time, we set a listener in the CommandBox to listen for the input of any of the three commands: update, delete or nom This feature is then facilitated by different objects, mainly MainWindow and UniqueFoodList. MainWindow interacts with LogicManager 's method of getSimilarFood which exposes the FoodRecord, allowing a filtered list of similar Food entries in the UniqueFoodList to be returned back to the user.

A predicate, FoodRecordContainsFoodNamePredicate is also essential in this implementation in ensuring that the correct similar Food items can be filtered from the UniqueFoodList back to the LogicManager to be displayed by the GUI. The test method of this predicate which is responsible for the above is shown:

Both of the boolean used for this predicate is essential. For instance, if "Laksa is already present" in the FoodRecord:

The following sequence diagram will explain how the different objects interact to achieve the Real-time Suggestion Feature.

Based on the above diagram, when a user has already entered any of the CommandWord: update, delete or nom, and also the Prefix n/:

Step 1: CommandBox calls the MainWindow method of getSuggestions with the parameter as the entire String of user input in the CommandBox.

Step 2: MainWindow then parses the user inputted String and calls LogicManager method of getSimilarFood with the parameter foodName which is the entire String after the Prefix n/

Step 3: The Model then does the necessary work by calling methods getFoodRecord and getFoodList. This results in the current UniqueFoodList being returned

Step 4: The UniqueFoodList is then filtered with the Predicate<Food>, FoodRecordContainsFoodNamePredicate which returns a List<Food> of Food objects that have similar Name fields to the user input.

Step 5: Finally, the filtered List<Food> is then parsed into a String for the user by the MainWindow and then displayed in the GUI’s Result Display.

CommandBox listens for any of the three commands as mentioned, allowing LogicManager and FoodRecord to facilitate the suggestions of similar Food entries from the UniqueFoodList to display in the GUI’s Result Display. This can be summarised in the activity diagram below:

To generate a command guide using the help command, a HelpCommand object generates the relevant command guides based on the provided command word in the input.

The sequence diagram below demonstrates how the help command works, should a command word of "nom" be provided.

Step 1: LogicManager executes the user input, using CalgoParser to realise it is a help command, and thus creates HelpCommand

Step 2: HelpCommand constructor generates the necessary mapping of command name to the corresponding command guide.

Step 3: LogicManager calls the execute method on the HelpCommand object, which produces the String containing the relevant command guides. A CommandResult object is produced reflecting the response to the help command.

Step 4: The CommandResult is eventually passed to the MainWindow class, which then displays the command guide in a separate window, using the HelpWindow class.

help will produce a popup, displaying a guide on the App’s available commands' purposes and usage format.

GraphPanel in the Ui component. It contains a LineChart of String date against Number calories, and is populated with data from an XYChart.series. The data is in turn obtained from the Logic component, which provides only the past seven days' of DailyFoodLog. The implementation of the GraphPanel class will be further explained.

GraphPanel class implements the following operations:

Calgo will display the past seven days' graph automatically, and likewise update automatically. It does so by having the MainWindow class call getGraph on startup and after execution of commands.

The sequence diagram below demonstrates how the Graph feature works.

Sequence Diagram for Graph feature.

Step 1: MainWindow requests for an instance of GraphPanel.

If no instance exists, a new GraphPanel is created. Otherwise one is retrieved. This ensures that GraphPanel is a singleton.

Step 2: MainWindow calls GraphPanel again to generate the graph and add it to the GraphPanelPlaceholder inside MainWindow.

Step 3: Inside GraphPanel, a wrapper method makeGraph calls three methods in a row:

First, initialiseTreeMap, which has Logic call the getPastWeekLogs method onto GraphPanel, generating a TreeMap of String date mapped to Double calories using the past seven days' DailyFoodLog. Second, initialiseGraph method is called to generate the graph itself. Third, updateSeries method is called to ensure the data populating the graph is up to date.

After which, the GraphPanel adds the graph to MainWindow.

In summary, this section addresses how the graph obtains information on the past seven DailyFoodLog, and correspondingly produces a visual graph output onto Calgo’s Main Window GUI component viewable by the user.

The graph requires the LogicManager class to obtain the information, and the MainWindow class to facilitate display to the user.