By: Team CS2103T-F13-3      Since: Sep 2019      Licence: MIT

1. Introduction

MoneyGoWhere is a personal finance application targeted to students at the National University of Singapore (NUS). It allows students to keep track of all their spending and their related information such as date, cost and tags. Users can also set budget goals, view statistics, set reminders for bills, view exchange rates, use different currencies, and import and export their data. With an easy-to-use Graphical User Interface (GUI) and employment of Command Line Interface (CLI), users can easily navigate through the application, contributing to its user-friendliness and efficiency.

What are you waiting for? Start tracking your finances now!

2. How To Use This Guide

The following section details and previews a few legends and formatting that will be used throughout the user guide. These legends are used to represent special information such as tips.

Important information that should be noted.
Tips that can help you better navigate the application.

test: Command to be executed

Useful information for a deeper understanding of the command.

Without further ado, let’s head over to Section 3, “Quick Start” to get started!

3. Quick Start

These steps will guide you in installing MoneyGoWhere on your computer.

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

  2. Download the latest MoneyGoWhere.jar here.

  3. Copy the file to the folder you want to use as the home folder for MoneyGoWhere.

  4. Double-click the file to start the app. The GUI should appear in a few seconds as seen in Figure 1. MoneyGoWhere comes preloaded with sample data to allow you to explore and familiarise with the application.

    ui annotate
    Figure 1. User Interface of MoneyGoWhere

  5. Type the command in the command box and press Enter to execute it.
    e.g. typing help will display the help information.

  6. Some example commands you can try:

    • list : lists all spending

    • addn/apple c/2.50 d/yesterday t/fruits r/expensive apple : adds a spending Apple to MoneyGoWhere.

    • delete3 : deletes the 3rd spending shown in the current list

    • exit : exits the app

  7. When you are ready to get started on tracking your own finances, do type clear in the command box and press Enter. This removes all the sample data from the application.

This is the end of the Quick Start tutorial. You can refer to Section 4, “Features” for more details about each command.

Your data is saved in the data/ folder by default. You are advised not to modify any of the system created files within the folder, else MoneyGoWhere may not perform as expected.

4. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in add n/NAME, NAME is a parameter which can be used as add n/apple.

  • Items in square brackets are optional e.g n/NAME [t/TAG] can be used as n/apple t/fruit or as n/apple.

  • Items with …​ after them can be used multiple times including zero times e.g. add n/NAME [t/TAG]…​ can be used as t/vegetable, t/fruit etc.

  • Parameters can be in any order e.g. if the command specifies add n/NAME c/COST, add c/COST n/NAME is also acceptable.

  • If a command accepts a single parameter and multiple parameters are provided, by default, the last parameter is chosen. e.g. if there is only one n/NAME accepted and the input is n/One n/Two, n/Two will be selected.

4.1. Viewing help : help

Shows a list of available commands and their usages.

Format: help

Optionally, you can press F1 or click help which can be found on the menu bar at the top left hand corner of the application.

The following image shows how the help bar can be accessed:

help
Figure 2. Accessing Help from Menu Bar

Help can be accessed from the menu bar by clicking on the Help button.

4.2. Flexible date formats

Whenever a particular command requires a DATE field, you can choose either of the following formats in the table below.

Table 1. Date format table
Date Type Formats

Formal Date

1978-01-28
1984/04/02
1/02/1980 (1st February 1980)
26/2/2019

Relaxed Date

The 31st of April in the year 2008
21 Nov 1997
Jan 21,'97
jan 1st
february twenty-eight

Relative Dates

next thursday/ last wednesday
today/ tomorrow/ yesterday
next week/ next month / next year
3 days from now
three weeks ago

Date Alternatives

next wed or thurs
oct 3rd or 4th

Prefixes

day after/ the day before
the monday after/ the monday before
2 fridays before/ 4 tuesdays after

Listed above are the date formats that can be used.

You do not need to specify which date format you would like to use as MoneyGoWhere will be able to differentiate it from the input received. However, if today is Wednesday and wednesday is entered, it will be considered next’s week Wednesday.
MoneyGoWhere will also automatically check whether a given date is valid. Should you accidentally provide an invalid date such as 31/02/2019, it will be rejected as there are only 28 days in February 2019. MoneyGoWhere may automatically try to correct dates best possible date.

4.3. Going through your command history

Similar to a typical command line interface (CLI), the user may press the up and down key to go through the previous user input history, and display it in the command box. Pressing the up key would go back to the earlier user input command. Whereas pressing the down key would move towards the most recent user input key.

If the user is at the most recent, or the earliest user inputted command, then press the up and down key respectively, no text will be displayed.

4.4. Adding a spending : add

Adds a spending to the list when you incur a new spending. Key information such as its name, cost, date, tags (if any) and remarks (if any) are stored.

Format: add n/NAME c/COST d/DATE [t/TAG]…​ [r/REMARKS]

A spending can have any number of t/TAG keywords (including 0). Each TAG is limited to 64 characters. If a spending date is in the future, it can only be up to the end of this month. Also, if you are using a different currency, the cost entered may have precision errors as it will be converted to SGD.

Examples:

  • add n/apple c/2.50 d/yesterday t/fruits r/Expensive apple

  • add n/chicken breast c/1.80 d/today t/meat

  • add n/coffee c/1.20 d/today

  • add n/milo c/1.50 d/tomorrow r/I love milo

  • add n/gold class movie ticket d/15/1/2019 c/13.00 r/important t/entertainment

Expected Output:

A new spending is added based on the specified input.

4.5. Editing a spending : edit

Edits a spending at a specified index in the list.

Format: edit INDEX [n/NAME] [c/COST] [d/DATE] [t/TAG]…​ [r/REMARKS]

  • Edits the spending at the specified INDEX. The index refers to the index number shown in the displayed spending list. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the spending will be removed i.e adding of tags is not cumulative.

  • Tags can have up to 15 characters.

  • You can remove all the spending’s tags by typing t/ without specifying any tags after it.

  • If a spending date is in the future, it can only be up to end of this month.

  • Spending entries that are added using a different currency will have output displayed in SGD.

  • If you are using a different currency, the cost entered may have precision errors as it will be converted to SGD.

In v1.4, this command does not support adding or removing a particular tag from a specific spending. Removing and adding of tags will be available from v2.0 onwards.

Examples:

  • edit 1 c/100
    Updates the cost of the first spending to 100.

  • edit 2 n/chicken rice
    Updates the name of the third spending to chicken rice.

  • edit 5 c/500 n/flight tickets
    Updates both the cost of the fifth spending to 500 and its name to flight tickets.

  • edit 10 t/vegetable
    Overwrites existing tags of the tenth spending to vegetable.

Expected Output:

The specified spending is edited.

4.6. Deleting a spending : delete

Deletes a spending at a specified index in the list.

Format: delete INDEX

  • Deletes the spending at the specified INDEX.

  • The index refers to the index number shown in the displayed spending list.

  • The index must be a positive integer 1, 2, 3, …​

Example:

  • delete 2
    Deletes the second spending in the list based on the current list shown.

Expected Output:

The specified spending is deleted.

4.7. Listing all spending : list

Displays a list of all spending and their information such as name, date, cost, tag and remark.
Format: list

By default, list of all spending is sorted by descending order of date, descending order of cost, ascending order of name and finally ascending order of remark.
This command is implicitly invoked upon application start up, and can be used to reset the view after find or sort.

Expected Output:

All spending entries are listed.

4.8. Finding a spending : find

Searches for spending based on given keywords, cost range, date range, remarks or tags. You may refine the search results by entering more keywords.

Format: find [n/NAME_KEYWORDS] [c/COST_MIN] [c/COST_MAX] [d/DATE_START] [d/DATE_END] [r/REMARK_KEYWORDS] [t/TAG]…​

  • At least one search field must be present and the search is case-insensitive. For example, apple and Apple will output the same search results.

  • The order of the keywords do not matter for name and remarks. For example, ticket concert will match concert ticket and only full words will be matched. For example, app will not match apple.

  • Spending matching at least one keyword will be returned. For example, Phone will return New Phone, Phone Bill.

  • When searching for multiple tags, any tag listed will be matched along with the previous criteria. For example, if the search keyword was d/yesterday d/today t/food t/entertainment, spending entries within yesterday and today that have either tags food or entertainment will be matched.

DATE_START must be earlier or the same as DATE_END, and COST_MIN must be smaller or the same as COST_MAX.
Date range can be input in the following ways:
d/DATE_START d/DATE_END
d/DATE_START to DATE_END
d/DATE_START - DATE_END
Cost range can be input in the following ways:
c/COST_MIN c/COST_MAX
c/COST_MIN-COST_MAX
c/COST_MIN - COST_MAX

Examples:

  • find n/Java book c/100.20-150.00 d/01/09/2019 - 30/09/2019
    Returns a list of spending with matching the keywords Java or book within the cost range 100.20 to 150.00 and date range within 01/09/2019 to 30/09/2019.

  • find d/yesterday d/today t/food t/leisure
    Returns a list of spending within yesterday and today that have food or leisure tags.

Expected Output:

Spending entries which match the search criteria are listed.

4.9. Sorting spending entries : sort

Sorts all spending based on a given order to view information more clearly.

Format: sort [PREFIX/SORT_ORDER]…​

  • At least one of the optional fields must be provided.

  • Valid prefixes are: Cost (c), Date (d), Name (n), Remarks (r).

  • Valid sort orders are: ASC, DESC.

  • If the given sort order is c/ASC n/DESC, Cost will be sorted in ascending order, followed by name in descending order.

  • Sorting names or remarks in Ascending order will sort uppercase letters first, followed by lowercase letters.

Examples:

  • sort d/ASC c/DESC
    Sorts current spending displayed by Date in ascending order. If they are the same, sort by Cost in descending order.

  • sort n/DESC
    Sorts current spending displayed by Name in descending order.

Expected Output:

An example is shown below.

SortPreviewUG
Figure 3. Output of sort n/ASC d/DESC

Spending entries are sorted in alphabetical order where uppercase letters appear first, and a message is displayed based on the example in Figure 3, “Output of sort n/ASC d/DESC”.

4.10. Setting the currency : currency

Sets the currency used to display spending entries.
Format: currency [CURRENCYCODE]

  • If CURRENCYCODE is not specified, the currency in use is displayed.

  • CURRENCYCODE can be SGD, USD, EUR, IDR, MYR, INR, MMK.

Example:

  • currency USD
    Sets the currency displayed for spending entries to USD.

Expected Output:

The currency displayed is changed and spending entries are updated.

4.11. Viewing exchange rates : exchangerate

Displays currently stored exchange rates.
Format: exchangerate [AMOUNT] [CURRENCYCODE]

  • If AMOUNT and CURRENCYCODE are specified, the indicated values are converted to SGD.

  • CURRENCYCODE can be USD, EUR, IDR, MYR, INR, MMK.

  • Entering SGD as CURRENCYCODE will display an error since the entered value is already in SGD.

Due to network limitations, exchange rates are fixed and locally stored. Exchange rates may also vary across different websites.
v1.4 does not have networking support for exchange rates. This will be available from v2.0 onwards.

Example:

  • exchangerate
    Shows all exchange rates.

  • exchangerate 5 USD
    Converts 5 USD to SGD based on current exchange rates.

Expected Output:

All available exchange rates are shown, or a conversion of an input currency is provided if it was specified.

4.12. Setting monthly budget : budget

Sets a budget for the current month in the currency set.
Format: budget MONTHLY_BUDGET

  • The monthly budget must be a valid number.

  • The monthly budget amount cannot exceed 1,000,000,000 Singapore Dollars.

  • The monthly budget amount can only have at most 2 digits after the decimal point, regardless if it is trailing zeroes.

    • Examples of valid budget amount:

      • 20

      • 100.01

    • Examples of invalid budget amount:

      • 100.00000

      • 0.0001

Using the budget command will overwrite the currently set budget.

Example:

  • budget 5000
    Sets a budget of $5000 for this month

Expected Output:

The budget for the current month is changed to the set amount.

4.13. Showing current budget : showbudget

Shows the current monthly budget, total spending and remaining budget in Singapore Dollars.
Format: showbudget

Expected Output:

The budget for the current month along with the total spending in the month as well as remaining budget is shown.

4.14. Generating statistics : stats

Organises the spending based on tags. A pie chart is generated, with each sector representing the total amount of money spent on a tag. This enables users to be more informed of their spending habits as they are now aware of where they have spent most of their money on. An example is shown below.

stats
Figure 4. Output of stats d/21/10/2019 d/25/10/2019

Format: stats d/DATE_START d/DATE_END

  • Generates statistics for all spending that fall between and including the DATE_START and DATE_END specified by the user.

  • If no DATE_START and DATE_END parameters are specified, the statistics generated will be based on the whole list of spending.

  • Only spending that have at least a tag will be considered.

  • Only the top few tags which incurred a more significant amount of money will be displayed.

Spending with multiple tags will be counted more than once in total as the statistics seek to show the user which tag they have spent the most money on.
DATE_START must be earlier or the same as DATE_END.
Date range can be input in the following ways:
d/DATE_START d/DATE_END
d/DATE_START to DATE_END
d/DATE_START - DATE_END
The statistics panel will update every time the spending list displayed changes. For example, when a new spending with a tag is added, the statistics panel will update the pie chart to show the statistics for all spending, including the new spending.
The statistics panel will update with the currency set.

Examples:

  • stats: Generates statistics for all spending.

  • stats d/20/10/2019 d/25/10/2019: Generates statistics for spending between and including 20/10/2019 and 25/10/2019.

Expected Output:

Statistics is shown.

4.15. Generating a graph : graph

Organises the spending based on date. A line graph is generated, with each point representing the total amount of money spent on a particular date. This enables users to analyze trends in their spending amount over a particular period of time. An example is shown below.

graph
Figure 5. Output of graph d/21/10/2019 d/25/10/2019

Format: graph d/DATE_START d/DATE_END

  • Generates a graph for all spending that fall between and including the DATE_START and DATE_END specified by the user.

  • If no DATE_START and DATE_END parameters are specified, the statistics generated will be based on the whole list of spending.

  • Only dates that have at least a spending will be recorded in the graph.

DATE_START must be earlier or the same as DATE_END.
Date range can be input in the following ways:
d/DATE_START d/DATE_END
d/DATE_START to DATE_END
d/DATE_START - DATE_END
Hovering the mouse over a point displays the date and total amount of money spent (to the nearest dollar) on that date.
The graph panel will update every time the spending list displayed changes. For example, when a new spending is added, the graph panel will update and generate a graph for all spending, including the new spending.
The graph panel will update with the currency set.

Examples:

  • graph: Generates a graph for all spending.

  • graph d/20/10/2019 d/25/10/2019: Generates a graph for spending between and including 20/10/2019 and 25/10/2019.

Expected Output:

A graph is shown.

4.16. Adding a reminder: reminder add

Adds a reminder to the reminder list when you enters a new reminder. Key information such as deadline and message are recorded.

Format: reminder add d/DATE m/MESSAGE

  • Your reminders are sorted based on how close they are to their respective deadline.

  • The closer it is to the deadline, the higher position it takes in the reminder list.

Please ensure that the date of the deadline must be in the future before the end of next year. In other words, MoneyGoWhere will accept dates starting from today until the end of next year as deadlines.

Examples:

  • reminder add d/30/08/2020 m/Pay school fees

  • reminder add d/3 days from now m/Pay phone bill

Expected Output:

A new reminder is added according to the information provided.

4.17. Deleting a reminder: reminder delete

Deletes a reminder at the specified INDEX.

Format: reminder delete INDEX

  • Deletes the reminder at the specified INDEX.

  • The index refers to the index number shown in the displayed reminder list.

  • The index must be a positive integer 1, 2, 3, …​

Example:

  • reminder delete 2
    Deletes the second reminder in the list based on the current results shown.

Expected Output:

The specified reminder is deleted.

4.18. Importing data : import

The purpose of this command is to let you import external spending data from a Csv file.

When you want to import your existing spending data which is recorded in a Csv file, you could type a simple command, in the format of import p/FILE_PATH, and press enter. Your new spending entries will be added to the existing spending entries without replacing them.

The Graph, Statistics and Budget panels will also be updated accordingly once the import is successful.

Only spending data will be imported. This excludes Reminder and Budget data.

However, importing of Reminder and Budget data is coming in our version 2.0!

Format: import p/FILE_PATH

Examples:

  • import p/data.csv

  • import p/C:\Users\User\Documents\spending.csv

  • import p/./data.csv

4.18.1. Retrieving File Path

You could retrieve your file path by following these steps, depending on which Operating System you are on:

exampleFilePathWindows
Figure 6. Retrieving File Path in Windows

For Windows:

  1. Open your File Explorer.

  2. Navigate to the folder where you save your Csv file.

  3. Click on the address bar of your File Explorer window.

  4. You should be able to see something similar to the figure above.

exampleFilePathMac
Figure 7. Retrieving File Path in Mac

For Mac:

  1. Open your Finder window.

  2. Navigate to the folder where you sove your Csv file.

  3. Right-click on your Csv file and select Get Info.

  4. You should be able to see a window open up showing something similar to the figure above.

4.18.2. Csv File Constraints

ExampleValidCsv
Figure 8. A Valid Csv File.

Before importing your Csv file, you have to make sure that your Csv file have a header row with the following values:

  • name

  • date

  • remark

  • cost

  • tagged

You should end up with a Csv file similar to the figure above.

Multiple tags should be separated by a semi-colon.

Example:

juicy;nice

Alternatively, tags could be wrapped in double quotes and separated by commas.

Example:

"juicy,nice"

Expected Output:

Data from the Csv file is imported, keeping existing spending entries.

4.19. Exporting data : export

The purpose of this command is to let you export your spending data to a moneygowhere.csv file at a folder that you like. You could refer to Retrieving File Path.

Only spending data will be exported into moneygowhere.csv file. This excludes Reminder and Budget data

However, exporting of Reminder and Budget data is coming in our version 2.0!

Format: export p/FOLDER_PATH

Examples:

  • export p/Documents

  • export p/Finance

  • export p/C:\Users\user\Documents\MoneyGoWhere

4.20. Undoing previous command : undo [Coming in v2.0]

Restores the list of spending to the state before the previous undoable command was executed.

Format: undo

Undoable commands: commands that modifies any of the spending (add, delete and edit).

Examples:

  • delete 1
    list
    undo (reverses the delete 1 command)

  • list
    stats
    undo (command fails as there are no undoable commands executed previously)

  • delete 1
    add n/textbook c/100
    undo (reverses the add n/textbook c/100 command)
    undo (reverses the delete 1 command)

Expected Output:

The last performed action is undone.

4.21. Redoing the previously undone command : redo [Coming in v2.0]

Reverses the most recent undo command.

Format: redo

Examples:

  • delete 1
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)

  • list
    redo (command fails as there are no undo commands executed previously)

  • delete 1
    add n/textbook c/100
    undo (reverses the add n/textbook c/100 command)
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)
    redo (reapplies the add n/textbook c/100 command)

Expected Output:

The most recent undo command is reversed.

4.22. Clear all data : clear

You can clear all your saved data from this application using this command.
Format: clear

This command clears all stored reminders and spending from the application, and sets the budget to a default value of $1000.

Expected Output:

All data stored in MoneyGoWhere is cleared and the budget is set to $1000.

4.23. Exiting the program : exit

Exits the program.
Format: exit

Expected Output:

Program exits.

5. Glossary

  • Budget: The maximum amount of money set by the user to spend.

    • Safe: The user has spent less or equal to his budget set.

    • Deficit: The user has spent more than his budget set.

  • Cost: Money spent by the user.

  • Spending: An expense incurred by the user.

6. Command Summary

Listed below is a summary of all available commands.

Table 2. Command Summary table
Feature Command

Help

help

Add

add n/NAME c/COST [d/DATE] [t/TAG]…​ [r/REMARKS]
e.g. add n/apple c/2.50 d/yesterday t/fruits r/expensive apple

Edit

edit INDEX [n/NAME] [c/COST] [t/TAG]…​ [r/REMARKS]
e.g. edit 1 n/apple c/2.50 d/yesterday t/fruits r/expensive apple

Delete

delete INDEX
e.g. delete 123

List

list

Find

find [n/NAME] [c/COST_RANGE] [d/DATE_RANGE] [r/REMARK] [t/TAG]
e.g. find n/apple orange c/1.00-200.00 d/19/09/2019 - 20/09/2019 r/healthy food t/fruit food

Sort

sort [PREFIX/SORT_ORDER]…​
e.g. sort d/DESC c/ASC

Currency

currency [CURRENCYCODE]
e.g. currency USD

Exchange rate

exchangerate [AMOUNT] [CURRENCYCODE]
e.g. exchangerate, exchangerate 5 USD

Budget

budget MONTHLY_BUDGET
e.g. budget 18000

Show Budget

showbudget
e.g. showbudget

Generate statistics

stats d/DATE_START d/DATE_END
e.g. stats d/01/01/2019 d/07/01/2019

Graph

graph d/DATE_START d/DATE_END
e.g. graph d/01/01/2019 d/07/01/2019

Import data

import p/FILE_PATH
e.g. import p/C:\Users\User\Documents\importfile.csv

Export data

export p/FILE_PATH
e.g. export p/C:\Users\User\Documents\importfile.csv

Add reminder

reminder add d/DATE m/MESSAGE
e.g. reminder n/30/08/2020 m/Pay school fee

Delete reminder

reminder delete INDEX
e.g. reminder delete 2

Undo

undo

Redo

redo

Clear

clear

Exit

exit

The command summary above displays all commands available in MoneyGoWhere.