VBook User Guide

VBook is a desktop application for freelance software developers to store and organise client contact details and log client preferences. VBook is optimized for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI).

VBook (VimBook) is inspired by the Vim editor, where users can edit, navigate, and program faster with the keyboard than using a mouse. Hence, our commands and theme are inspired by the style of Vim.

Software developers who type fast can get their contact management tasks done at lightning speed with VBook's keyboard-only navigation feature. With advanced privacy features like password protection and encryption, VBook ensures that software developers’ client details remain secure and confidential at all times.

Quick Start

Note: This document assumes familiarity with the command line, though it is not required.

Ensure you have Java 17 or above installed in your computer. For Mac users, you should use the specific Azul JDK 17 distribution following this guide.
Download the latest VBook.jar file from here.
Copy the file to the folder you want to use as the home folder for VBook.
Open a command terminal, change directory (cd) into the folder you put the VBook.jar file in, and use the java -jar VBook.jar command to run the application.

cd path/to/vbook
java -jar VBook.jar

An initial dialog will appear to prompt you to set a new password.

On subsequent logins, the password dialog will prompt you to enter the password that you set.

A GUI similar to the screenshot below should appear upon successful login. The application contains some sample data for you to get familiar with the application.

Type any command in the Command Box and press ENTER to execute it. For example, typing :help and pressing ENTER will open the help window.

The application contains sample contacts. To remove them, type :clear and press ENTER.

For a summary of all our commands, refer to this table below:

Command Summary

Action	Format	Examples
Add	`:add -n NAME [-p PHONE_NUMBER] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]` `:a -n NAME [-p PHONE_NUMBER] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]`	`:add -n James Ho -p 98765432 -e jamesho@example.com -l 123, Clementi Rd, 1234665 -t friend -r My favourite colleague` `:a -n James Ho -p 98765432 -e jamesho@example.com -l 123, Clementi Rd, 1234665 -t friend -r My favourite colleague`
Clear	`:clear` `:cl`	`:clear` `:cl`
Delete	`:remove -i INDEX` `:rm -i INDEX`	`:remove -i 3` `:rm -i 3`
Edit	`:edit INDEX [-n NAME] [-p PHONE] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]` `:ed INDEX [-n NAME] [-p PHONE] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]`	`:edit 2 -n James Lee -e jameslee@example.com` `:ed 2 -n James Lee -e jameslee@example.com`
Quit	`:quit` `:q`	`:quit` `:q`
Export	`:export` `:exp`	`:export` `:exp`
Find	`:find [-n NAME] [-p PHONE] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]` `:f [-n NAME] [-p PHONE] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]`	`:find -n david -l serangoon` `:f -n david -l serangoon`
Help	`:help` `:h`	`:help` `:h`
List	`:list` `:ls`	`:list` `:ls`
Redo	`:redo` `:r`	`:redo` `:r`
Undo	`:undo` `:u`	`:undo` `:u`

Notes about the command format:

All commands are in lowercase.
Words in UPPERCASE 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 John Doe.
Items in square brackets are optional.
e.g. -n NAME [-t TAG] can be used as -n John Doe -t friend or as -n John Doe.
Items with … after them can be used any number of times.
e.g. [-t TAG]… can be used as (i.e. 0 times), -t friend (i.e. 1 time), -t friend -t family (i.e. 2 times) etc.
Parameters can be in any order.
e.g. if the command specifies -n NAME -p PHONE_NUMBER, -p PHONE_NUMBER -n NAME is also acceptable.
Extraneous parameters for commands that do not take in parameters (such as :help, :list, :quit and :clear) will be ignored.
e.g. if the command specifies :help 123, it will be interpreted as :help.
If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines as space characters surrounding line-breaks may be omitted when copied over to the application.

Notes about the parameters:

Some parameters have restrictions on the values they accept:
- Names should only contain alphanumeric characters and spaces, and it should not be blank.
- Phone numbers should only contain numbers, and it should be at least 3 digits long. Duplicates are allowed because a single phone number may be used by multiple people, such as a company number.
- Emails should be of the format local-part@domain and adhere to the following constraints:
  1. The local-part should only contain alphanumeric characters and these special characters, excluding the parentheses, (+_.-). The local-part may not start or end with any special characters.
  2. This is followed by a '@' and then a domain name. The domain name is made up of domain labels separated by periods. The domain name must:
    - end with a domain label at least 2 characters long
    - have each domain label start and end with alphanumeric characters
    - have each domain label consist of alphanumeric characters, separated only by hyphens, if any.
- Locations can take any values.
- Tags should be alphanumeric, only one word long, and under 50 characters.
- Remarks should only contain alphanumeric characters and spaces.
- Phone numbers, Emails, Locations, Tags and Remarks can be shared by contacts. This is because people in an organisation may share the same information.

Refer to the Features below for details of each command.

Features

Commands

View Help

Shows a command cheatsheet, as well as a link to access this user guide.

Format :help
Shortcut: :h

Add Person

Adds a person to the address book.

Format: :add -n NAME [-p PHONE_NUMBER] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]
Shortcut: :a

Tip: A person can have any number of tags (including 0).

Examples:

From an initial state of the address book as shown above, typing in the commands below will result in an output as shown below.

To add a client named "Jack Lee", key in :add -n Jack Lee.

To add a friend and client you met at a conference named "Ivy King", with a phone number of "87654320", an email of "ivyk@example.com", with location of "808 Palm St", key in :a -n Ivy King -p 87654320 -e ivyk@example.com -l 808 Palm St -t friend -t client -r Met at a conference.

List All

Shows a list of all persons in the address book.

Format: :list
Shortcut: :ls

Edit Person

Edits an existing person in the address book.

Format: :edit INDEX [-n NAME] [-p PHONE] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]
Shortcut: :ed

Edits the person at the specified index. The index refers to the index number shown in the displayed person 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 person will be removed i.e. adding of tags is not cumulative.
You can remove all the person’s tags by typing -t without specifying any tags after it.

Examples:

From an initial state of the address book as shown above, typing in the commands below will result in an output as shown below.

To edit the first person's phone number and email address to be "91234567" and "johndoe@example.com" respectively, key in: :edit 1 -p 91234567 -e johndoe@example.com.

To edit the second person's name to "Betsy Crower" and clear all existing tags, key in: :edit 2 -n Betsy Crower -t .

Find Person

Finds contacts that match any specified search criteria, including name, phone number, email, location, tags, or remark.

Format: :find [-n NAME] [-p PHONE] [-e EMAIL] [-l LOCATION] [-t TAG]… [-r REMARK]
Shortcut: :f

The search is case-insensitive.
E.g. "hans" will match "Hans".
Persons with a certain name, phone number, email, address and remark can be searched through flags.
E.g. to find a person with the name "david" and remark "busy", the arguments would be -n david -r busy.
Each flag is optional, but there must be at least one flag in a query.
As long as the contact contains the query, it is considered a match, e.g. searching "Han" will bring up "Hans".
Only persons matching all keywords will be returned.
E.g. :find -n Hans -p 98765432 will not return "Hans" if his phone number is not "98765432".

Examples:

From an initial state of the address book as shown above, typing in the commands below will result in an output as shown below.

To find a person named "Alice" with location "789 Oak St", key in :find -n alice -l oak.

Remove Person

Removes the specified person(s) from the address book.

Format: :remove -i INDEX1, INDEX2, ...
Shortcut: :rm

Removes the person at the specified index.
The index refers to the index number shown in the displayed list.
Multiple persons can be deleted by listing their indexes, separated by commas.
The index must be a positive integer 1, 2, 3, ...

Examples:

From an initial state of the address book as shown above, typing in the commands below will result in an output as shown below.

To remove the 1st and 3rd person in your address book, key in :list to list all your contacts, followed by :remove -i 1, 3.

To remove a person named "Betsy Crower", key in :find -n Betsy followed by :remove -i 1 to delete the 1st person named "Betsy" in the result of the :find command. If you have multiple people named "Betsy", you can delete them using their specified index as well.

Undo

Reverts the address book to the state before the last change.
User can undo up to 10 changes.
Can undo commands that change the address book data, such as :add, :remove, :edit.

Format: :undo
Shortcut: :u
Examples:

If you accidentally added a person named "John Doe" to the address book (through an :add command), to undo the command and remove "John Doe", key in :undo.
If you accidentally deleted an important contact named "Betsy" (through a :remove command), to undo the command and restore the contact, key in :undo.

Tip: Ctrl-Z can also be used to undo the last change outside the command box.

Redo

Reapplies the last change to the address book that was undone with the :undo command.
User can redo up to 10 changes that were undone with the :undo command.

Format: :redo
Shortcut: :r
Examples:

Given that :undo was used to revert the addition of "John Doe", to add "John Doe" back to the address book, key in :redo.
Given that :undo was used to revert the deletion of "Betsy", to delete "Betsy" again, key in :redo.

Tip: Ctrl-Shift-Z can also be used to redo the last change outside the command box.

Export Data

Exports the address book data to a specified file in JSON format. Upon command, user will be prompted to select a directory to save the file.

Format: :export
Shortcut: :exp

Important: If you want to transfer your data to a VBook application in another computer, use :export instead of directly copying the data file over. Refer to the FAQ for a detailed guide on this.

Clear Data

Clears all entries from the address book's data.

Format: :clear
Shortcut: :cl

Quit Program

Quits the program.

Format: :quit
Shortcut: :q

Command Shortcuts

Command	Shortcut
View Help	`:h`
Add Person	`:a`
List All	`:ls`
Edit Person	`:ed`
Find Person	`:f`
Remove Person	`:rm`
Undo	`:u`
Redo	`:r`
Export Data	`:exp`
Clear Data	`:cl`
Quit Program	`:q`

Keyboard Shortcuts

There are two modes in VBook: Command Box and UI Navigation. The following keyboard shortcuts are available in each mode.

Command Box

Ctrl + Z - Undo the most recently typed words within the command box. This does not affect executed commands.
F1 - Open the Help Window.
ESC - Go back to UI Navigation Mode.

Ctrl + Z - Undo the last change made to the address book.
Ctrl + Shift + Z - Redo the last undone change made to the address book.
F1 - Open the Help Window.
Up-arrow - Highlight the previous contact in the list.
Down-arrow - Highlight the next contact in the list.
: - Focus on the Command Box.

Privacy and Security

Password Prompt

Initial Setup: When you launch VBook for the first time, you’ll be prompted to create a new password. This password will be used to control access to your address book.

Info: The password will be hashed with a salt and saved into a password.txt file stored in the same directory as VBook.jar.

Subsequent Logins: Each time you open VBook, you’ll be prompted to enter your password. This ensures that your data remains secure and accessible only to authorized users.

Caution: If you forget your password, there is no way to retrieve your data. To re-enter the application, you can delete the password.txt file located in the same directory as VBook.jar. However, deleting this file will also permanently erase all your address book data. This safeguard is designed to prevent unauthorized users from bypassing the password prompt.

Tip: Store your password in a secure place to avoid losing access to your data.

Encryption

How it Works:

When you enter your password during the initial setup, it generates an encryption key saved as vbook.jks stored in the same directory as VBook.jar.
All your address book data is encrypted using this key and saved securely on your device.
Each time you open the app, the password is used to decrypt the data for access.

Info: Encryption only happens the first time you make changes to the address book from the VBook GUI. Loading a JSON file to your directory will not automatically encrypt the file.

File Management

Save Data

VBook data is saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Edit Data File

The encrypted VBook data are saved automatically as a JSON file [JAR file location]/data/vbook.json.

Caution: Do not make changes to the encrypted JSON file, as it can corrupt the data and make it unreadable. If you want to manually edit the data file, follow these instructions:

Export your data by running :export.
Overwrite the empty data file in the new computer's data/vbook.json with the vbook.json file from your export in Step 1.
Run VBook and your modified data should appear.

Note: If your changes to the data file makes its format invalid, VBook will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.
Furthermore, certain edits can cause the VBook to behave in unexpected ways (e.g. if a value entered is outside the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.

FAQ

Q: How do I transfer my data to another computer?
A: To transfer your data over, follow these steps:

Export your data from your current computer by running :export.
Install VBook in the other computer (refer to Quick Start for more information).
Overwrite the empty data file in the new computer's data/vbook.json with the vbook.json file from your export in Step 1.
Run VBook and your data should appear in your new computer.

Note: Your data in your new VBook application will only be encrypted when you make a change to it in the application, through commands (i.e. :add, :edit).

Known issues

When using multiple screens, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the preferences.json file created by the application before running the application again.
If you minimize the Help Window and then run the :help command (or use the Help menu, or the keyboard shortcut F1) again, the original Help Window will remain minimized, and no new Help Window will appear. The remedy is to manually restore the minimized Help Window.