tp

User Guide

Table of Contents

• User Guide
  • Table of Contents
  • Introduction
  • Getting Started
  • Features
    • Adding an entry: /add
      • Supported Categories
    • Deleting an entry: /delete
    • Edit an entry: /edit
    • View an entry: /view
    • Filter options
    • Show help menu: /help
    • Exit Program: /bye
  • Command Summary
  • Frequently Asked Questions

Introduction

PocketPal is an expense tracking command line application that allows users to record their expenses in different categories. Subsequently, users can monitor their expenses within a specified timeframe, or price range. They may also monitor expenses in certain categories. This makes it easier for users to plan their budgets and make better financial decisions.

Getting Started

1. Ensure that you have Java 11 and above installed (Installation Guide)
2. Download our latest release of PocketPal.jar here
3. Run the application with java -jar PocketPal.jar (Running JAR Guide)
4. You should see the following welcome screen

   Welcome to
   _____           _        _   _____      _
   |  __ \         | |      | | |  __ \    | |
   | |__) |__   ___| | _____| |_| |__) |_ _| |
   |  ___/ _ \ / __| |/ / _ \ __|  ___/ _` | |
   | |  | (_) | (__|   <  __/ |_| |  | (_| | |
   |_|   \___/ \___|_|\_\___|\__|_|   \__,_|_|
   
   How may I help you?
   ________________________________________________
   Enter a command or /help to see the list of commands available.
   > 
   

5. To enter an entry, you may use /add, or enter /help to view the help menu.

The table below provides a summary of all the currently supported features in PocketPal. More detailed explanations on the usage of the commands are provided as well.

Features

This user guide adopts the following conventions for the command-line syntax:

• Angle brackets (<>) indicate that the enclosed arguments are mandatory.
• Square brackets ([]) indicate that the enclosed arguments are optional.
• Ellipsis (...) indicate that the preceding argument can be repeated several times in one command.
• Pipe or vertical line (|) indicates a choice within an argument. You can select either one of them, but cannot select more than one.

IMPORTANT NOTES

• All arguments starting with a dash (-) will be treated as options. This includes negative integers, which would trigger unknown options exception

• For all specified options, only the arguments that follow the first declaration will be parsed. i.e. any subsequent re-declarations of the same option will be ignored.
  For example, for the following input:
  /view -c food -c clothing
  Only entries in the food category will be listed.

If you face any problems, do visit the FAQ segment!

Command	Function
/add	Adds an entry
/delete	Deletes an entry
/edit	Edits an entry
/view	Displays details of an entry e.g. Price, Category
/help	Displays the help menu
/bye	Terminates the program

Back to Table of Contents

Adding an entry: /add

Adds an entry to your current account.

Format: /add -d <description> -c <category> -p <price>

Options:

• -d <description>
-description <description>
  Description of the entry.
  • All characters except comma (,) are valid.
  • Multiple words separated by spaces are allowed. However, a word should not start with dash (-) or it will be treated as an option.
• -c <category>
-category <category>
  Category of the entry.
  • Must be a one-word category currently supported in PocketPal.
  • Non case-sensitive.
• -p <price>
-price <price>
  Price of the expense.
  • Must be a positive numeric or decimal value with no more than 2 decimal points.
  • Minimum value: 0.01
  • Maximum value: 999999999.99
• The order of the options are interchangeable, but they are all required.

Supported Categories

These are the categories currently supported by PocketPal:

Clothing, Entertainment, Food, Medical, Personal, Transportation, Utilities, Others, Income

---

Note: An entry with category Income will be added to your total income which can be seen in /view.

---

Example of usage:

/add -d Lunch at McDonalds -category Food -price 19.9

/add -d Apple Macbook Air -p 1300 -category Personal

/add -p 1300 -c Personal -d Apple Macbook Air

Back to Table of Contents

Deleting an entry: /delete

Deletes specified entry(s) from your current account.

The entry IDs can be obtained from the /view command.

Format: /delete <index> [additional_index...]

• index, additional_index: Index of the entry to be deleted.
  • Index must be a positive integer. The maximum index allowed is the total number of existing entries.
  • Additional indexes must be separated by spaces.

Example of usage:

/delete 5

/delete 4 6 10

Back to Table of Contents

Edit an entry: /edit

Edits a specified entry in your current account with the given flag(s).

Format: /edit <index> [options]

• index: Index of the entry to be deleted.
  • Only digits characters are allowed.
  • The maximum index allowed is the number of existing entries.

Options:

• -d | -description <description>: New description of the entry.
  • All characters except comma (,) are valid.
  • Multiple words are allowed.
• -c | -category <category>: New category of the entry.
  • Must be a one-word category currently supported in PocketPal.
  • Non case-sensitive.
• -p | -price <price>: New price of the expense.
  • Must be a non-negative numeric or decimal value with no more than 2 decimal points.

The order of the options are interchangeable.

At least one of the options must be specified.

Example of usage:

/edit 5 -p 10.50

/edit 5 -description Grab to school -c Transportation

Back to Table of Contents

View an entry: /view

Displays a list of your current entries.

Format: /view [count] [filter_options]

• count: Number of entries to be listed.
  • Only digits characters are allowed.
  • If not specified, or if count is greater than number of existing entries, all entries will be listed.

Filter options

Filter by category

• -c | -category <category>: Category of entries to be listed.
  • Must be a one-word category currently supported in PocketPal.
  • Non case-sensitive.
  • If not specified, entries of all categories will be listed.

Filter by price

• -sp | -startprice <min_price>: Minimum price of entries to be listed.
• -ep | -endprice <max_price> Maximum price of entries to be listed.

Note:

• If max_price and min_price are both specified, all entries between and inclusive of min_price and max_price will be listed.
• If only min_price is specified, all expenses greater than or equal to min_price will be listed.
• If only max_price is specified, all expenses smaller than or equal to max_price will be listed.
• min_price should not be greater than max_price.
• All prices should have no more than 2 decimal points.
• If both specified prices are the same, the entries with that exact price will be listed.

Filter by date range

• -sd, -startdate <start_date>: Starting date of entries to be listed.
• -ed, -enddate <end_date>: Ending date of entries to be listed.

Note:

• start_date, end_date must be in dd/MM/yyyy format.
  • dd - Day of the month, from 01 to 31
  • MM - Month of the year, from 01 to 12
  • yyyy - Supported year, from 0001 to 9999
• Both flags are required if user wishes to use this option.
• start_date should not be after end_date.
• If both specified dates are the same, the entries on that date will be listed.

Order of options are interchangeable.

Example of usage:

/view 10

/view -c food

/view -sd 12/03/2023 -ed 11/04/2023 -c food

/view -c food -sp 2 -sd 12/03/2023 -ed 11/04/2023

Back to Table of Contents

Show help menu: /help

Displays the help menu in the format of the supported commands in the application and their functions.

If a valid command is entered after /help, it displays the format and function of that specific command instead.

Format: /help [command_type]

Example of usage:

/help

/help edit

/help delete

Back to Table of Contents

Exit Program: /bye

Terminates PocketPal.

Format: /bye

Back to Table of Contents

Command Summary

Command	Format
/add	/add -d <description> -c <category> -p <price> e.g. /add -d Gucci Bag -c Others -p 2000
/view	/view [count] [-c <category>] [-sp <startprice>] [-ep <endprice>] [-sd <start_date> -ed <end_date>] e.g. /view -c food e.g./view -sp 100 -ep 200
/edit	/edit <index> [-c <category>] [-p <price>] [-d <description>] e.g. /edit 1 -d Gucci Wallet -p 3000
/delete	/delete <index> [additional_index…] e.g. /delete 1 e.g. /delete 1 5 10
/help	/help [command_type] e.g. /help e.g./help add
/bye	/bye

Back to Table of Contents

Frequently Asked Questions

Q: I am facing trouble starting the application. Do you know what might be the issue?

A: Please ensure that you have Java 11 and above installed on your machine. You may find more instructions at the Getting Started section

Q: How do I know whether the data entered is saved?

A: Your data is saved automatically when you interact with the application. There is no need to manually perform the save operation.

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

A: Your application data stored in data/storage.txt. To use PocketPal on another device, simply copy the data folder to the same directory as PocketPal.jar and start the application as per normal. Your stored entries will be automatically loaded.

Q: My application crashed. How do I report the problem to the developers?

A: We are sorry for the unpleasant experience with PocketPal, and we would be more than happy to solve the issue. You may file an issue on our GitHub stating how you arrived at the problem, so that our developers can assist you with the issue. Please also attach the application logs, which can be found at logs/pocketpal.txt

Q: I am a developer. How can I find the source code and contribute to PocketPal?

A: PocketPal is an open-source application, and we welcome developers to share their ideas. You may find the source code on GitHub.

Q: I accidentally touched the data in my storage.txt file - what do I do?

A: The data in the storage.txt file is saved in the format DESCRIPTION,PRICE,CATEGORY,DATE. Make sure the data in the file is in the correct format, or else it will be overwritten with a blank data file. The category must be capitalized, and the date must be in the format D MMM YYYY; HH:MM.

Back to Table of Contents