tp

User Guide

Introduction

Wiagi is a simple command line application that helps students who are beginning their financial independence journey by offering a wide range of essential tools and features such as budgeting, saving, and investment analysis.

Quick Start

  1. Ensure that you have Java 17 or above installed.
  2. Download the latest version of Wiagi from here.
  3. Copy the file to the folder you want to use as the home folder.
  4. Open a command terminal, navigate to the folder you have placed the jar file in, and use the java -jar WIAGI.jar command to run the application.
  5. You will be prompted to set a password and budget. Enter the password you set to log in.

Features

Notes about the command format:

Login

Creation of new user:

First time users will be prompted to create a new password. Users are to type in their preferred password. Subsequent logins will not require this step.
The password will be whitespace-sensitive and case-sensitive.

TO NOTE
The program does not provide a forget password feature to recover password as of the current iteration. Please take note of the password you entered. Failure to recall password requires a hard reset of the program by exiting the program and deleting the password data file.

Expected display for first time users:

	____________________________________________________________
	Hi! You seem to be new, are you ready?!
	Please enter your new account password:

To help users manage their finances well, users are also prompted to enter their daily, monthly and yearly budgets. Users should enter valid amounts for each budget type

Example valid inputs:

Example invalid inputs:

Expected display:

	Hello! So happy you took this first step of financial management.
	Let's first set your budgets!
	Please enter a daily budget you have in mind:

	____________________________________________________________
	Next, please enter a monthly budget you have in mind:

	____________________________________________________________
	Last one! Please enter a yearly budget you have in mind:

Expected output after successfully creating new user: 

    ____________________________________________________________
    ____________________________________________________________
    Hello from
    __        __  ___      /\       ____   ___
    \ \      / / |_ _|    /  \     / ___| |_ _|
     \ \ /\ / /   | |    / /\ \   | |  _   | |
      \ V  V /    | |   / ____ \  | |_| |  | |
       \_/\_/    |___| /_/    \_\  \____| |___|
    ____________________________________________________________
    ____________________________________________________________
    Please Enter Login Credentials:

*Note that this is also the startup page for returning existing users.

Existing user:

Upon entering the correct password, user will be able to access their financials.
Expected output for correct password:

    ____________________________________________________________
    Login Success!
    ____________________________________________________________

Users will be repeatedly prompted for their password if they enter the wrong password
Expected output for wrong password:

    ____________________________________________________________
    Incorrect password! Login Failed :<
    ____________________________________________________________
    Please Enter Login Credentials:

Adding an entry

Adding a spending:

Adds an entry into user spending list. Entry will be displayed at the latest index.
Run the list spending command to display the list with the new entry.
Amount entered must be greater than 0 when rounded to 2 decimal places.

Format: add spending {$AMOUNT} {$DESCRIPTION} [/$DATE/] [*$TAG*] [~$FREQUENCY~]

Example inputs:

Expected output:

	____________________________________________________________
	Entry successfully added!
	____________________________________________________________

If a recurring entry is added with the date before today, user will be prompted to enter whether he/she would like to add all the recurring entries between the date of entry and the current date. (Y/N is case-insensitive). 

	____________________________________________________________
	Entry successfully added!
	Do you want to backlog recurrence entries from 2023-01-23 to 
	2024-11-07 if any? [Y/N]

If Y is entered, the output will be as follows:

	____________________________________________________________
	All entries to recur are added!
	____________________________________________________________

If N is entered, the output will be as follows:

	____________________________________________________________
	Ok! The entry will not be backlogged
	____________________________________________________________

If user overspends after all spending (ie. new entry and recurring entries) are added, a alert message will be displayed. The following is an example output, your output may differ in values and lines:

    !!! You have overspent your daily by: 1000 !!!
    !!! You have overspent your monthly by: 1000 !!!
    !!! You have overspent your yearly by: 1000 !!!

Note: Recurring entries will only recur till current date, today, thus if an entry dated to the future is added, no recurring entries will be added

Adding an income:

Adds an entry into user income list. Entry will be displayed at the latest index.
Run the list income command to display the list with the new entry.

Format: add income {$AMOUNT} {$DESCRIPTION} [/$DATE/] [*$TAG*] [~$FREQUENCY~]

Example input:

Expected output:

	____________________________________________________________
	Entry successfully added!
	____________________________________________________________

If a recurring entry is added with the date before today, user will be prompted to enter whether he/she would like to add all the recurring entries between the date of entry and the current date. (Y/N is case-insensitive). 

	____________________________________________________________
	Entry successfully added!
	Do you want to backlog recurrence entries from 2023-01-23 to 2024-11-07 if 
	any? [Y/N]

If Y is entered, the output will be as follows:

	____________________________________________________________
	All entries to recur are added!
	____________________________________________________________

If N is entered, the output will be as follows:

	____________________________________________________________
	Ok! The entry will not be backlogged
	____________________________________________________________

Note: Recurring entries will only recur till current date, today, thus if an entry dated to the future is added, no recurring entries will be added.

Listing all entries:

Lists all the entries in the user’s spending or income list.
Format: list

Example input:
list

Example output:

	____________________________________________________________
	Spendings
	1. macdonalds - 10 - 2024-10-10 - Tag: food
	2. techno - 10 - 2024-10-17 - Tag: food
	3. flights - 10 - 2024-11-01 - Tag: travel
	4. girlfriends - 10 - 2024-11-17 - Tag: personal
	Total spendings: 40
	Incomes
	1. dividends - 10 - 2024-10-17 - Tag: investment
	2. mcd - 100 - 2024-11-11 - Tag: personal
	Total incomes: 110
	____________________________________________________________

Listing spendings:

Lists entries in the user’s spending list.

Format: list spending

The user will then be prompted to select a time range from the following options:

  1. All
  2. This week
  3. Last week and this week
  4. This month

Only entries that are dated within the selected time range will be displayed.

For instance, if the command is run on 15 November 2024 (Friday),

If option 1 (all) is chosen, the user will then be asked if all spending statistics should be displayed (Y/N is case-insensitive).

Example Input and Output

Input: list spending 

    ____________________________________________________________
    List spending entries for:
    [1] All
    [2] This week
    [3] Last week and this week
    [4] This month

    ____________________________________________________________
    Spendings
    1. macdonalds - 10 - 2024-10-10 - food
    2. techno - 10 - 2024-10-17 - food
    3. flights - 10 - 2024-11-01 - travel
    4. girlfriends - 10 - 2024-11-17 - personal
    Total spendings: 40
        Daily spendings: 0
        Daily Budget: 1
        Daily budget left: 1
        Monthly spendings: 20
        Monthly Budget: 1
        Monthly budget left: -19
        Yearly spendings: 40
        Yearly Budget: 1
        Yearly budget left: -39
    ____________________________________________________________

    ____________________________________________________________
    Spendings
    1. macdonalds - 10 - 2024-10-10 - Tag: food
    2. techno - 10 - 2024-10-17 - Tag: food
    3. flights - 10 - 2024-11-01 - Tag: travel
    4. girlfriends - 10 - 2024-11-17 - Tag: personal
    Total spendings: 40
    ____________________________________________________________

	____________________________________________________________
	Showing spending entries from 2024-11-01 to 2024-11-30
	3. flights - 10 - 2024-11-01 - Tag: travel
	4. girlfriends - 10 - 2024-11-17 - Tag: personal
	Total: 20
	____________________________________________________________

	____________________________________________________________
	Showing spending entries from 2024-11-18 to 2024-11-24
	No entries within selected time range
	Total: 0
	____________________________________________________________

Listing incomes:

Lists entries in the user’s income list.

Format: list income

The user will then be prompted to select a time range from the following options:

  1. All
  2. This week
  3. Last week and this week
  4. This month

Only entries that are within the time range will be displayed. The time range system is the same as that of listing spendings.

Example Input and Output

Input: list income

    ____________________________________________________________
    List income entries for:
    [1] All
    [2] This week
    [3] Last week and this week
    [4] This month

Listing all tags:

Lists all the tags in the user’s list.

Format: list tags

Example input:
list tags

Example output:

    ____________________________________________________________
    Tags
    1. FastFood
    2. food
    3. investment
    4. personal
    5. travel
    ____________________________________________________________

Listing all of specific tag:

Lists all the entries in the user’s list with the specified tag. Tags are case-insensitive (e.g. Food is treated the same as food)

Format: list tags {$TAG}

Example input:
list tags food

Example output:

    ____________________________________________________________
    Tag: food
    Spendings
    1. techno - 10 - 2024-10-17 - food
    4. macdonalds - 10 - 2024-10-10 - food
    ____________________________________________________________

Deleting an entry

Deleting an income:

Deletes the specified income from the list. The income to delete is specified by its index in the list.
Run the list income command to check the index of the income.

Format: delete income {$INDEX}

Example input:
delete income 1

Example output:

    ____________________________________________________________
    Successfully deleted!
    ____________________________________________________________

Deleting a spending:

Deletes the specified spending from the list. The spending to delete is specified by its index in the list.
Run the list spending command to check the index of the spending.

Format: delete spending {$INDEX}

Example input:
delete spending 1

Example output:

    ____________________________________________________________
    Successfully deleted!
    ____________________________________________________________

Getting user instructions

The help command allows the user to see a quick summary of the commands.

Format: help

Example input:
help

Example output:

Notes about the command format:
Words in {$UPPER_CASE} are the parameters to be supplied by the user.
e.g., in add spending {$AMOUNT} {$DESCRIPTION}, {$AMOUNT} and {$DESCRIPTION}
are parameters which can be used as add spending 4 dinner.
Items in square brackets are optional.
e.g. add spending {$AMOUNT} {$DESCRIPTION} [/$DATE/] can be used as
add spending 4 lunch or add spending 4 lunch /2024-10-20/.

Adding Entries:
	add income {$AMOUNT} {$DESCRIPTION} [/$DATE/] [*$TAG*] [~$FREQUENCY~]
	add spending {$AMOUNT} {$DESCRIPTION} [/$DATE/] [*$TAG*] [~$FREQUENCY~]
	e.g., add income 5000 Salary /2024-03-15/ *work* ~monthly~
	e.g., add spending 50 Lunch /2024-03-15/ *food*

Listing Entries:
	list - shows all entries
	list income - shows all income entries
	list spending - shows all spending entries
	list tags {$TAG} - shows entries with specific tag

Editing Entries:
	edit {$CATEGORY} {$INDEX} {$FIELD} {$NEW_VALUE}
	-note that {$FIELD} only works for amount, description, date and tags
	e.g., edit spending 1 amount 100
	e.g., edit income 2 description Bonus

Deleting Entries:
	delete {$CATEGORY} {$INDEX}
	e.g., delete spending 1

Setting Budget:
	budget {$PERIOD} {$AMOUNT}
	e.g., budget daily 50
	e.g., budget monthly 1500

Other Commands:
	help - shows this help message
	bye - exits the application

Setting a Budget

The budget command allows you to set a daily, monthly, or yearly budget for your spendings. Amount entered must be greater than 0 and less than or equal to 100 million when rounded to 2 decimal places.
For budget types, daily budget <= monthly budget <= yearly budget

Format: budget {$PERIOD} {$AMOUNT}

The input criteria for the amount is the same as the amount entered for creation of new user.

Example input:
budget daily 50

Example output:

    ____________________________________________________________
    Successfully set daily budget of: 50
    ____________________________________________________________

Editing an Entry

The edit command allows you to edit the amount, description, tag or date of an existing income or spending entry.
Amount entered, if applicable, must be greater than 0 when rounded to 2 decimal places.

Format: edit {$CATEGORY} {$INDEX} {$FIELD} {$NEW_VALUE}

Example input:
edit spending 1 amount 100
edit spending 1 description macdonalds
edit spending 1 tag food
edit spending 1 date 2024-10-10

Example output:

    ____________________________________________________________
    Edit Successful!
    ____________________________________________________________

Note: Editing a recurring entry does not trigger backlogging and overspend message will also be printed if budget has been exceeded after editing

Finding an Entry

The find command allows you to find entries of a specific amount and date or within a range. It also allows you to find entries with specific keyword(s) in the description.

Format: find {$CATEGORY} {$FIELD} {$FIND_VALUE} [to $ANOTHER_FIND_VALUE]

Example input:

Example output:
If there is no matches:

    ____________________________________________________________
    No entries found match the criteria.
    ____________________________________________________________

If there are matches:

    ____________________________________________________________
    Here are the matching results:
    1. macdonalds - 10 - 2024-10-10
    ____________________________________________________________

Exiting the program

The bye command allows you to exit the program safely.

Format: bye

Example input:
bye

Example output:

    ____________________________________________________________
    Bye. Hope to see you again soon!
    ____________________________________________________________

Saving the data

All data previously inputted into the programme will be automatically saved upon the user exiting via the bye command. There is no need to save manually.

Editing the data file

WARNING
This section is dedicated to advanced users who are confident in updating the data file manually. Failure to do so correctly can lead to data corruption and having possibly all previous information wiped out. Entry numbers detected as corrupted will be displayed to user upon start up. The user may choose to copy out the lines, rectify, and manually input them back after closing the program properly.

User data is stored into 3 text files, namely

Format of data storage for password:

For security purposes the method of storage will not be discussed. DO NOT alter this file, simply exit the program and delete the file if you have forgotten you password and create a new password upon being prompt when start up. Note that this will cause a hard reset to the application and erase all data.

Format of data storage for income and spending:

Data are stored with | used as delimiter. Each line in the text file represents one entry.
Format: [$AMOUNT]|[$DESCRIPTION]|[$DATE_OF_ENTRY]|[TAG_NAME]|[RECURRENCE_FREQUENCY]|[LAST_RECURRENCE]|[DAY_OF_RECURRENCE]

For spendings.txt, the first line of entry stores the budgets of the user.
Format: [$DAILY_BUDGET]|[$MONTLY_BUDGET]|[$YEARLY_BUDGET]

Important data representation to note:

We recommend not to edit [$LAST_RECURRENCE]. However, if you wish to, for adding recurring entries, [$LAST_RECURRENCE] should match [$DATE_OF_ENTRY] and for editing recurring entries, [$LAST_RECURRENCE] should be the last possible recurred date before current date. If the entry is not recurring, [$LAST_RECURRENCE] should be “null”.

FAQ

Q: How do I transfer my data to another computer?

     A: Simply transfer incomes.txt, spendings.txt and password.txt files to the folder that the program is at.

Q: Why are the indices of the entries not in consecutive order when I list or find entries?

     A: Each index reflects the actual index of the item in the entire list so that you can edit or delete the entry easily.

Q: What happens if I edit the date of a recurring entry to an earlier date?

     A: The date of the entry will be changed, but no additional entries will be created between the new date and the current date.

Q: What happens if I add a recurring entry with an earlier date?

     A: You will have the option to select whether you would like to add the additional entries between the date of entry and the current date.

Q: What happens if I forget my password?

     A: Delete the password.txt file in the folder where the program is located. Upon starting the program, you will be prompted to create a new password. Users have to press Ctrl+C (or Command+C for Mac users) to exit the program before they are able to delete the file. Do note that the spendings.txt and incomes.txt files will be reset and all data will be lost. If you have a backup of the spendings.txt and incomes.txt files, you can replace the new files with the backup files to restore your data.

Command Summary

Command Format Examples
Adding Income add income {$AMOUNT} {$DESCRIPTION} [/$DATE/] [*$TAG*] [~$FREQUENCY~] add income 10000 commission /2023-01-23/ *bonus* ~monthly~
Spending add spending {$AMOUNT} {$DESCRIPTION} [/$DATE/] [*$TAG*] [~$FREQUENCY~] add spending 100 telegram premium /2023-01-23/ *personal expense* ~monthly~
Listing entries All spendings list spending list spending
All incomes list income list income
All tags list tags list tags
All of a specific tag list tags {$TAG} list tags food
Deleting entries Income delete income {$INDEX} delete income 1
Spending delete spending {$INDEX} delete spending 1
Setting budget Daily budget daily {$AMOUNT} budget daily 30
Monthly budget monthly {$AMOUNT} budget monthly 1000
Yearly budget yearly {$AMOUNT} budget yearly 12000
Finding entries Income find income {$FIELD} {$FIND_VALUE} [to $ANOTHER_FIND_VALUE] find income description salary
Spending find spending {$FIELD} {$FIND_VALUE} [to $ANOTHER_FIND_VALUE] find spending amount 10 to 100
Get all Commands help help
Exit Program bye bye