$aveNUS - User Guide

By: Team-F13-2 Since: Sep 2019 Licence: MIT

1. Introduction
2. Quick Start
3. Features
4. Frequently Asked Questions
5. Command Summary

1. Introduction

$aveNUS is a desktop financial planning app that allows NUS students to plan their meals according to the amount of budget they set aside per meal in NUS. With $aveNUS, you can more effectively manage your expenses, save your favourite meal options within NUS, edit meal options, and even receive recommendations for meals that suit your budget.

More importantly, $aveNUS is optimized for those who prefer to work on a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI).

Interested in our app? Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

Welcome to $aveNUS! If you are just starting out, this quick start will help you get $aveNUS up and running on your computer. It will equip you with the basics you need to know to utilise $aveNUS optimally.

2.1. Using the User Guide

code

Command that can be typed into the command box

Success execution of command

Tips that might be useful

Additional information that is good to know

Important pointers to take note

2.2. Pre-Requisites

Ensure you have Java 11 or above installed in your Computer.

You can download Java 11 from here.
Copy the file to the folder you want to use as the home folder for $aveNUS.
Double-click the file to start the app. The Graphical User Interface (GUI) should appear in a few seconds.
Dark Mode GUI of $aveNUS as shown in Figure 1 and Light Mode GUI shown in Figure 2

Figure 1. Dark Mode display for $aveNUS

Figure 2. Light Mode display for $aveNUS. Note that the panels are at the same locations as in Figure 3.

Type the command in the command box and press Enter to execute it.
e.g. typing help and pressing Enter will open the help window.
Some example commands you can try:
- First, add a food item into the menu by typing add n/Halal chicken rice p/3.00 d/chicken and rice c/Malay and press Enter
- The food item will be added to the food item panel appearing on the left of the window as shown below Figure 1 above.
- Type exit and click Enter and the desktop application should close.
- If everything above executes as stated, you can use $aveNUS to plan your expenditure in NUS now!

This application is optimized for screen resolution of 1400x900 pixels and higher. Anything lower than that and you might experienced some bugs.

Users might experience some truncated detail on smaller laptop screens. As such, we advice users to not input names with many characters, description, etc.

Ensure that your screen setting is set to a display size of 100%, as a higher setting might result in texts being cut off.

2.3. Using Commands

You can use the commands described in Section 3, “Features” by typing them into the command box and then hitting Enter.

You have to provide additional parameters for some commands, and the format of each command is provided in the command descriptions.

Provided below is a summary of the command format used in the $aveNUS User Guide:

UPPER_CASE words are the parameters supplied by you.
- For example, info COMMAND, COMMAND is a parameter to find out more information about COMMAND.
Items in square brackets are optional.
- For example, budget AMOUNT [DURATION] has an optional parameter DURATION, hence budget 100 10 or budget 100 are both valid commands.
Items with … after them can be used multiple times or not at all.
- For example, delete INDEX… works with commands such as delete 1, delete 1 2 and so on.

Refer to Section 3, “Features” for details of each command.

3. Features

This section highlights the commands that $aveNUS supports. These include information about the command’s function, format as well as example usages of the command.

3.1. General Commands

General commands are used to enhance the user’s experience when using the app and also provide some useful information to make the user more familiar with the app.

3.1.1. Viewing help: `help`

Displays the help window that allows users to view the list of commands available. It also allows users to open up the user guide by clicking the Guide button within the help window.

Format: help
Example: help

You will see the help the help window, diplaying the list of commands available.

3.1.2. Viewing previously typed commands: `history`

Shows the user’s previously typed commands in the Results Display.
The user can view up to 10 previously typed commands.

Format: history
Example: history

This command only allows you to see previously typed commands. Any commands done through the buttons on the menu pane will not be shown.

You will see a list of commands that you have previously typed in the Results Display.

Figure 3. Example of view of $aveNUS after user inputs history. History of previously typed command appears in the Results Display as shown.

A message stating that "You have not entered any commands." is displayed if you have not input any commands prior to the call to history.

The history command will only display previous commands with no duplicate commands.
Eg. typing history twice will only result in a display of history only ONCE in the Results Display.

3.1.3. Viewing information about a command: `info`

Displays the information of the command specified. A new window will be opened showing additional information about the specified command, usage example, and expected output of the command.

Format: info COMMAND
Example: info edit

$aveNUS can only display one information window at a time. Therefore, subsequent usage of the info command will only display the latest command specified.

You will see a window pop-up specifying the details of the command you wanted more information about.

Figure 4. Example of view of information window after user inputs info edit.

3.1.4. Changing the application’s theme: `theme`

Changes the look of the application depending on the desired theme.
List of themes available are light and dark

The default theme of the application is dark

You are able to subsequently set the same theme one after another but it would not result in any change in themes.
e.g. calling theme dark and then theme dark again will only result in one time change to dark theme.

Format: theme THEME
Example: theme dark

The application’s theme will now change to dark theme.

3.1.5. Exiting the application: `exit`

Exits the app.

Format: exit
Example: exit

Application closes.

3.2. Food Items

3.2.1. Add a food item: `add`

Adds a food item to the food list. Do note of the following:

You are only allowed to give one of NAME, DESCRIPTION, CATEGORY, LOCATION, RESTRICTIONS, PRICE and OPENING HOURS. Providing more than one of these FIELD will throw an error.
You are allowed to give one or more TAGS.
PRICE must be a number wth 0 or 2 decimal places, it cannot exceed more than 5000.00 and it should not contain leading zeros.
OPENING HOURS must be in HHMM HHMM format. The start time must be earlier than or equal to the end time.
NAME DESCRIPTION CATEGORY LOCATION and RESTRICTIONS must all be alphanumeric.
TAG is limited to 20 characters per tag, and only limited to one word per tag.

The list will scroll to the end when the food is added.
If autosort is turned on, it will not scroll to the end of the list.

NAME, PRICE and CATEGORY are mandatory fields.

The list of recommendations would be cleared if you use the this command. You can re-enable recommendations by using the recommend command again (see Section 3.7.1, “Getting a list of recommended food items: recommend”).

Format: add n/NAME p/PRICE c/CATEGORY [d/DESCRIPTION] [l/LOCATION] [o/OPENING HOURS] [r/RESTRICTIONS] [t/TAG]…
Example: add n/Chicken Rice d/Rice with Chicken p/2.50 c/Chinese l/NUS o/0800 2000 r/NI t/Chicken t/RiceL

You are not allowed to add in duplicate foods. Duplicate foods have the same name, category, description, location, restrictions and opening hours.

The food list will scroll to the bottom, where the new food item is added.

Figure 5. Example of new food added into the app

3.2.2. List all food items: `list`

List all the food items in the list.

Format: list

All the items in the food list will be shown.

Figure 6. Example of listing all food items

3.2.3. Edit a food item: `edit`

Edits a food item at a INDEX based on a specific FIELD or fields. INDEX must be a positive integer. At least one FIELD must be given. Do take note of the following:

You are only allowed to give one of NAME, DESCRIPTION, CATEGORY, LOCATION, RESTRICTIONS, PRICE and OPENING HOURS. Providing more than one of these FIELD will throw an error.
You are allowed to give one or more TAGS.
PRICE must be a number wth 0 or 2 decimal places, it cannot exceed more than 5000.00 and it should not contain leading zeros.
OPENING HOURS must be in HHMM HHMM format. The start time must be earlier than or equal to the end time.
NAME DESCRIPTION CATEGORY LOCATION and RESTRICTIONS must all be alphanumeric.
TAG is limited to 20 characters per tag, and only limited to one word per tag.

Format: edit INDEX n/NAME …
Example: edit 2 n/Fried Rice

The food item’s fields will be updated.

Figure 7. Example of edited food item

3.2.4. Finds food items based on keywords: `find`

Finds a food items based on specific keywords. Following which, the food items names containing the specific keywords will be shown in the food list.

Format: find KEYWORD …
Example: find Chicken Rice

The food items containing any of the specific keywords will be shown.

Figure 8. Example of finding food

3.2.5. Filters food items based on criteria: `filter`

Filters the food items based on the criteria specified. Take note of the following:

The VALUE of the PRICE must be a number wth 0 or 2 decimal places, and it cannot exceed more than 1000000.

Based on v1.4, you are only allowed to enter PRICE as a FIELD. Other fields will be available for use in v2.0 and above.

Format: filter FIELD QUANTIFIER VALUE
Example: filter PRICE LESS_THAN 4.00

The food items satisfying the conditions will be shown.

Figure 9. Example of filtering food successfully

3.2.6. Deletes a food item: `delete`

Deletes a food items based on the given INDEX. INDEX must be a positive integer.

You are allowed to have more than one INDEX.

Format: delete INDEX …
Example: delete 2

A confirmation message will appear, informing that the food item has been deleted.

Figure 10. Example of deleting food sucessfully

3.2.7. Clears wallet purchase history and food items: `clear`

Clears wallet, purchase history, savings account, likes, dislikes and aliases in the application.

Format: clear

Wallet, Purchase History, Savings History, Savings Account, likes, dislikes and aliases will all be cleared..

Figure 11. Example of calling clear in the app.

3.3. Sorting

Allows the user to sort the food items based on his liking. This is done so that the user is able to get the food which is most relevant to his or her preferences.

You must always provide pairs of FIELD and DIRECTION to execute the Sorting commands.

The various FIELD are as followed: NAME, DESCRIPTION, PRICE, CATEGORY, LOCATION, OPENING_HOURS and RESTRICTIONS.
The DIRECTION are as follows: ASC or DESC.

NAME, DESCRIPTION, CATEGORY, LOCATION and RESTRICTIONS are sorted in lexicographical order. For example, Chicken has a smaller lexicographical value than chicken due to case sensitivity.

OPENING_HOURS are sorted based on start time and end time. If one food’s start time is earlier than another food, then the food with the earlier start time will have a smaller comparison value.

Ordering of pairs matters! For example, specifying: PRICE ASC NAME DESC sorts the food items first based on price in ascending order. Following which, sorts the food items based on names in descending order.

3.3.1. Sorts food items based on fields: `sort`

Sorts all the food items by some specific FIELD.

You can have more than one pair of FIELD and DIRECTION.

Format: sort FIELD DIRECTION …
Example: sort PRICE ASC

The list of food items will be sorted by the fields you have entered.

Figure 12. Example of sorting the food items successfully

3.3.2. Make your own custom comparator: `makesort`

Create your own custom comparator, which will be stored within the storage of the application, using specific FIELD and DIRECTION.

Format: makesort FIELD DIRECTION …
Example: makesort PRICE ASC

Your custom comparator will be shown.

Figure 13. Example of success message when custom comparator successfully created.

3.3.3. Sort based on your custom comparator: `customsort`

Sort using your own custom comparator, which you have created with MakeSort.

Format: customsort

The list of food items will be sorted by the fields specified in your custom comparator.

Figure 14. Example of successful custom sort

3.3.4. Auto sorts list based on custom comparator: `autosort`

Turns on and off auto sorting, based on your own custom comparator, every time you make changes to the food list. There are only two states, ON or OFF.

Once you turn auto sorting on, customsort, sort and default will not work. They will only work if and only if you turn auto sorting off.

Format: autosort STATE
Example: autosort ON

A message will inform you if you have turned autosorting on or off.

Figure 15. Example of successful autosort.

3.3.5. Views the fields for the custom comparator: `viewsort`

Views the current Custom Sorter.

Format: viewsort

A message will inform you of the fields of your custom comparator.

Figure 16. Example of success message when user request to view the custom comparator

3.3.6. Sorts food items based on natural order: `default`

Sorts the food items based on their default ordering, where it is based on ascending category, name and then price.

Format: default

The list of food items will be sorted in its natural order.

Figure 17. Example of setting the food items in default order

3.4. Budgeting

Figure 18. Example User’s Wallet

Maximum budget amount is $1,000,000.
Maximum budget duration is 365 days (1 year).

3.4.1. Sets budget for a number of days: `budget`

Allows the user to set a budget for food expenses.

Format: budget AMOUNT [DURATION]
Example: budget 100.00 10

Note:
AMOUNT must be a non-negative integer or non-negative double with 2 decimal places.
DURATION is in days, and must be a non-negative integer.

3.4.2. Top up money into wallet: `topup`

Allows users to top up the money into their wallet.

Format: topup AMOUNT
Example: topup 10

Note:
AMOUNT must be a non-negative integer or a non-negative double with 2 decimal places.

If the top up was successful, you should be able to see the update to your wallet immediately.

3.5. Savings

Unlike your wallet which has a limit to the amount you can have, i.e. $1,000,000, your savings account has a limit that is imposed by the limitations of the user’s computer’s memory.

The savings account and the savings history is presented to the user in the display as shown in figure below.

Figure 19. GUI display of $aveNUS

3.5.1. Transfer money from user’s wallet into savings account: `save`

The user can save an amount of money from the user’s wallet, into his/her savings account.

Format: save AMOUNT
Example: save 10

Note:
AMOUNT must be a non-negative integer or a non-negative double with 2 decimal places.

Make sure you have money in your wallet before you save! You cannot save money without having money in your wallet.

You will see a success message and the amount of money you have saved in your savings account. You will be able to view your savings in the savings history tab. The savings will appear GREEN.

Figure 20. Example savings display when "Savings" is clicked as shown after savings are made.

Figure 21. Example success message that appears after keying a successful saving.

3.5.2. Withdraw money from user’s savings account into wallet: `withdraw`

The user can withdraw a sum from his/her savings account, and add it into his/her wallet.

Format: withdraw AMOUNT
Example: withdraw 10

Note:
AMOUNT must be a non-negative integer or a non-negative double with 2 decimal places.

You must have money in your savings account before you can withdraw from it.
Also, you cannot withdraw an amount that will result in your wallet having more than $1,000,000.

You will see a success message and the amount of money you have withdrawn from your savings account. You will be able to view your withdrawals in the savings history tab. The withdrawals will appear RED.

Figure 22. Example withdrawal display when "Savings" is clicked as shown after withdrawals are made.

Figure 23. Example success message that appears after keying a successful withdrawal. This appears below where the user typed.

3.5.3. Displaying only Savings or Withdrawals: `show`

The user can restrict his/her view of the savings history display, such that the savings history only displays his/her savings or withdrawals.

Format: show TO_DISPLAY
Example: show savings

Note:
TO_DISPLAY can only include the following parameters:

savings - Reveals only the user’s savings in GREEN
withdrawals - Reveals only the user’s withdrawals in RED
both - Revert back to the original display of all savings and withdrawals made by the user.

The restricted display will not be applied after another command is typed.
When new command is entered that is not show the savings history display is reverted back to display all savings and withdrawals.

3.5.4. Setting a savings target: `target` (Coming in v2.0)

Another feature that many students want is to set their personal savings target in which they can be constantly be reminded of whenever they open up the application. It can further encourage them to take up certain savings habits and cut down on certain unnecessary expenditures.

Format: target AMOUNT [r/REASON] [by/DATE]
Example: target 4000.00 r/For BTO by/06062019

Note:
AMOUNT cannot be a negative number. r/REASON and by/DATE are optional fields.

You will see a success message in the Results Display and your target shall be updated below your Savings Account display in the UI.

For example, executing target 4000.00 r/For BTO by/06062019, the following confirmation message shall appear: "Your savings target is set at: $4000.00 For BTO expiring 6th June 2019".

Only the date shall be entered, no time is required.

3.6. Purchasing

Figure 24. Example User’s PurchaseHistory

3.6.1. Buy a food item: `buy`

Allows users to log a food expense into the application.

Format: buy FOOD_INDEX
Example: buy 1

Note: FOOD_INDEX is with reference to the currently displayed food list

Make sure you have enough money in your wallet for the purchase.

If the purchase was successful, you should be able to see the update to your purchase history immediately.

3.7. Recommendations

Users can get a list of recommendations from the application, based on these factors:

The user’s likes and dislikes (see Section 3.7.3, “Adding likes and dislikes to the recommendation system: like or dislike”)
The user’s current budget and date to expiry of budget (see Section 3.4.1, “Sets budget for a number of days: budget”)
The user’s purchase history (see Section 3.6.1, “Buy a food item: buy”)

The factors affecting the calculation of the recommendation value is summarized in the tables below.

Table 1. Bonuses applied by the recommendation system
Condition 1	Condition 2	Bonus
Food tags match the user’s liked tags	1 or more tags	+0.05 and +0.03 per matching tag
	3 or more tags	+0.10 and +0.03 per matching tag
	5 or more tags	+0.25 and +0.03 per matching tag
Food category matches the user’s liked categories	N/A	+0.15
Food location matches the user’s liked locations	N/A	+0.10
Food tags match the user’s tags in purchase history	N/A	+0.01 per matching tag
Food category matches the user’s categories in purchase history	N/A	+0.02
Food location matches the user’s locations in purchase history	N/A	+0.03
Food purchase is found in user’s purchase history	2 or more purchases	+0.10
	5 or more purchases	+0.30
	10 or more purchases	+0.50

Table 2. Penalties applied by the recommendation system
Condition 1	Condition 2	Penalty
Food price is out of the user’s current budget	N/A	Removes the item from the recommendation results
Food tags match the user’s disliked tags	1 or more tags	-0.10 and -0.10 per matching tag
	2 or more tags	-0.30 and -0.10 per matching tag
	3 or more tags	-0.50 and -0.10 per matching tag
Food category matches the user’s disliked categories	N/A	-0.40
Food location matches the user’s disliked locations	N/A	-0.30
Food purchase is found in user’s purchase history	Within a time period of <2 days	Applies a decreasing penalty from -10 which diminishes to 0 after 2 days

Format: recommend

The list of recommendations will be shown, sorted by their recommendation value.

Figure 25. Example of the recommend command displaying a list of recommendations

To clear the recommendations, use the list or add or any sorting related command.

The recommended amount to spend per meal is calculated by budget / (daysToExpiry * 2) under the assumption that the user takes 2 meals per day, provided the budget and daysToExpiry is set by the user.

If you do not see any recommendations, make sure that you have a non-zero budget set using the budget command! See Section 3.4.1, “Sets budget for a number of days: budget” for more information.

3.7.2. Listing likes and dislikes in the recommendation system: `like` or `dislike`

To list the user’s likes and dislikes, use the command without providing any arguments.

Format: like or dislike

The list of liked or disliked categories, tags and locations will be shown.

Figure 26. Example success message that appears after listing likes or dislikes.

3.7.3. Adding likes and dislikes to the recommendation system: `like` or `dislike`

Users can specify their liked and disliked categories, tags and/or locations. The recommendation system will then be able to generate more accurate recommendations with the user’s preferences.

Users can provide multiple categories, tags and/or locations with each command. However, at least one category, tag or location must be provided with each command.

Users cannot add what they have already liked into your current dislikes, and vice versa. The user’s likes and dislikes will be also saved into the hard disk for their convenience.

To add likes:

Format: like [c/CATEGORY]… [t/TAG]… [l/LOCATION]…
Example: like c/chinese t/chicken t/rice l/frontier canteen

You will see a success message and your liked categories, tags and locations would be added.

Figure 27. Example success message that appears after adding likes.

To add dislikes:

Format: dislike [c/CATEGORY]… [t/TAG]… [l/LOCATION]…
Example: dislike c/italian t/pasta t/cheese l/the tea party

You will see a success message and your disliked categories, tags and locations would be added.

Figure 28. Example success message that appears after adding dislikes.

3.7.4. Removing likes and dislikes from the recommendation system: `removelike` or `removedislike`

Users are able to remove their previously added likes and dislikes (if they exist) from the system.

Users can provide multiple categories, tags and/or locations with each command. However, at least one category, tag or location to remove must be provided with each command.

The likes and dislikes must exist in the system before removing them.

To remove likes:

Format: removelike [c/CATEGORY]… [t/TAG]… [l/LOCATION]…
Example: removelike c/Japanese t/Spicy t/Healthy l/The Tea Party

You will see a success message and your liked categories, tags and locations would be removed.

Figure 29. Example success message that appears after removing likes.

To remove dislikes:

Format: removedislike [c/CATEGORY]… [t/TAG]… [l/LOCATION]…
Example: removedislike c/Chinese t/Cheap t/Healthy l/The Deck

You will see a success message and your disliked categories, tags and locations would be removed.

Figure 30. Example success message that appears after removing dislikes.

3.7.5. Clearing all likes and dislikes from the recommendation system: `removelike` or `removedislike`

To remove all likes or dislikes, use this command with the ALL flag.

This command is case-sensitive to prevent any accidental clearing of user’s likes or dislikes.

Only use this command if you are sure that you want to clear your likes and dislikes!

To remove all likes:

Format: removelike ALL

You will see a success message and your liked categories, tags and locations would be cleared.

Figure 31. Example success message that appears after clearing likes.

To remove all dislikes:

Format: removedislike ALL

You will see a success message and your disliked categories, tags and locations would be cleared.

Figure 32. Example success message that appears after clearing dislikes.

3.8. Alias

3.8.1. Editing the alias for a specific command: `alias`

Users are able to give an alias word for any given command in $aveNUS. You need to give one COMMANDWORD and one optional ALIASWORD. If no ALIASWORD is given, the ALIASWORD for the specific COMMANDWORD will be cleared.

Alias Words can only be alphanumeric.

Format: alias COMMANDWORD [ALIASWORD]
Example: alias sort shuffleAround

4. Frequently Asked Questions

Will the available food items only be localized around a certain location? What if I am staying in a remote area will I still be able to use this app?

As a user, you are able to add your own restaurants and food items into the app, hence allowing you to add restaurants in a remote location.

Am I able to share my expenses with other people?

Yes, you are able to obtain a complete list of your expenses as a text file for sharing.

Do I need to install anything to use the app?

You need to ensure that you have Java SE Development Kit version 11 or later to run the app.

Am I able to reset the app and remove all of my data?

Yes you can do this by using the clear command.

Does this app support another language?

Unfortunately, you are unable to change the app’s language.

5. Command Summary

Command

Description

Example Usage

add

Add food item.

add n/Chicken Rice d/Rice with Chicken p/2.50 c/Chinese l/NUS o/0800 2000 r/NIL

alias

Editing the alias word for any given command word in $aveNUS.

alias sort shuffleAround

autosort

Allows the user to sort every time the food list is changed. This is based on a created custom comparator.

autosort ON

budget

Allows the user to set a budget amount for food expenses for a certain number of days.

budget 100.00 10

buy

Allows users the log a food expense into the application.

buy 1

clear

Clears wallet, purchase history, savings account, wallet, likes, dislikes and aliases.

clear

customsort

Sorts items based on a created custom comparator.

customsort

default

Sorts the food items based on their natural ordering.

default

delete

Deletes a food items based on the given index.

delete 2

dislike

Specifies the user’s disliked categories, tags and locations.

dislike c/International t/Spicy l/The Deck l/The Terrace

edit

Edits a food item at a index based on a specific field or fields.

edit 2 n/Fried Rice

exit

Exits the app.

exit

filter

Filters the food items based on the criteria specified.

filter PRICE LESS_THAN 4.00

find

Finds food items based on specified keywords.

find Chicken Rice

help

Display possible uses of the application.

help

history

Displays the list of commands that has been typed by the user.

history

info

Displays the information of the command specified.

info edit

like

Specifies the user’s liked categories, tags and locations.

like c/Chinese c/Western t/Healthy l/Univeristy Town

list

List all saved food items.

list

makesort

Makes the custom comparator based on some specified fields and directions.

makesort PRICE ASC

recommend

Recommend a food item, based on the user’s budget.

recommend

removedislike

Remove dislikes from the user’s specified dislikes or clears the dislikes list.

removedislike c/Chinese t/Cheap t/Healthy l/The Deck

removelike

Remove likes from the user’s specified likes or clears the likes list.

removelike c/Japanese t/Spicy t/Healthy l/The Tea Party

save

Saves a specified amount of money from the user’s wallet into his savings account.

save 10

sort

Sort all the food items by some specified fields and directions.

sort PRICE ASC

show

Shows specifically the user’s savings/withdrawals as determined from the user’s input.

show savings

theme

Allows user to change the theme of the application.

theme dark

topup

Allows users to top up the money into their wallet.

topup 10

viewsort

Views the current Custom Sorter.

viewsort

withdraw

Withdraw a specified amount of money from the user’s savings account into his wallet.

withdraw 100