ContactCS User Guide

ContactCS is a desktop application designed for NUS Computer Science freshmen to help them efficiently manage and locate essential contact details. The app is designed to store and organize contacts for key individuals relevant to their academic journey, including:

• Professors and teaching assistants for enrolled modules
• Classmates for collaborative projects and study groups
• School offices for administrative matters
• Emergency contacts for urgent situations
• and more!

Callouts Convention

The callout boxes below are used in documentation to enhance readability and provide important contextual information.

Quick start

1. Ensure that Java 17 is installed on your computer.

   • Open a command terminal.
     • For Windows users, follow instructions here.
     • For Mac users, follow instructions here.
   • Type the following command to check the Java version:
     

     java -version
     

   • If Java 17 is installed, you should see an output similar to: java version "17.0.1"
   • If you do not have Java 17, you can download it from Oracle's official website.
     
     

2. Download the application

   • Get the latest .jar file from here.
     
     

3. Set up the home folder

   • Choose a folder where you want to store your ContactCS data.
   • Copy the downloaded .jar file to this folder.
   • This folder will serve as the "home folder" for your ContactCS.
     
     

4. Run the application

   • Open a command terminal.
   • Navigate (cd) to the folder where you placed the .jar file.

     • For Windows users, type:

       cd \path\to\your\folder
       

       Caution: Replace path\to\your\folder with the actual path. e.g. cd C:\Documents\ContactCS

       To find the actual path to your folder:
       

       Press the Windows key + S to open the search bar, type in the name of the file, and right-click the file that appears. Click on copy path.

     • For Mac users, type:

       cd /path/to/your/folder
       

       Caution: Replace path/to/your/folder with the actual path. e.g. cd ~/Documents/ContactCS

       To find the actual path to your folder:
       

       1. Navigate to the file in the Finder and select it.
       2. Right-click or Control-click on it and choose Get Info.
       3. In the window that opens, look at the Where field.
       4. Copy the path from the Where field.
   • Run the application with the following command:

     java -jar contactcs.jar
     

   A GUI similar to the screenshot below should appear in a few seconds. Note how the app contains some sample data.
   
   
   

5. 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:

   • list : Lists all contacts.

   • add n/John Doe p/98765432 e/johnd@example.com r/CS1101S : Adds a contact named John Doe who takes CS1101S to the Address Book.

   • delete 3 : Deletes the 3rd contact shown in the current list.

   • clear : Deletes all contacts.

   • exit : Exits the app.
     
     

6. Refer to the Features below for details of each command.

Overview of GUI

Once ContactCS is running, you’ll see the main interface divided into several key panels, as illustrated below. Here’s an overview of each panel:

• Command Box: You can type and execute commands here .

• Result Display Box: Shows the outcome of the commands you enter, including success messages, errors, and other feedback.

• Contact List: Displays the list of contacts, allowing easy access to contact information.

• Command History Window: Contains a history of commands that modify the contact list, enabling you to quickly refer to recent modifications.

• Menu (File/Help): Provides options such as exiting the application and accessing help documentation.

• Data Storage Location Footer: Shows the directory where the contact data are saved, providing quick access to storage information.
  
  

Viewing help: help

Help command supports two input formats which allows for more flexibility when you want to seek help:

Format: help [COMMAND_KEYWORD]

Shows a message explaining the usage of the specified command keyword

Example:

• help add shows the help message for add command in the following format

Format: help

Shows a message and a pop-up window showing the full list of help messages, and an external link to the full user guide.

Example:

Adding a person: add

Adds a person to the address book.

Format: add n/NAME (p/PHONE_NUMBER | e/EMAIL | p/PHONE_NUMBER e/EMAIL) [r/MODULECODE[-ROLETYPE]]+ [a/ADDRESS] [t/TAG]+ [d/DESCRIPTION]

• NAME can take any values and can not be blank.
• PHONE_NUMBER is almost a free-form text field with minimal validation.
• MODULECODE should be valid NUS module codes such as 'CS2040S' or 'MA1521'.
• ROLETYPE can be one of the following: student, ta, tutor, prof, professor. It defaults to student if not specified.
• The full r/MODULECODE[-ROLETYPE] parameter means that the person has the role for this module (e.g. r/CS1101S-student means that the person is a student of CS1101S).
• If the same module is added multiple times, then it is assumed to be an error in user input, because a person should not have multiple roles at the same time (e.g. r/CS1101S-student r/CS1101S-prof is not allowed).
• Note: A professor is not considered a teaching assistant (TA).
• EMAIL should be a valid email address.
• ADDRESS can take any values and can not be blank.
• TAG can take any alphanumeric values and can not be blank.
• DESCRIPTION can take any values but cannot exceed 500 characters.

For more explanation on the format and design of each input field, refer to the input format section.

Examples:

• add n/John Doe p/98765432 e/johnd@example.com r/CS1101S.
• add n/Jane Doe p/81234567 e/janed@example.com r/CS1101S-TA r/CS2040S.

Listing all persons: list

Shows a list of all persons in the address book.

Format: list

Editing a person: edit

Edits an existing person in the address book.

Editing module-role

The module-role pairs can be edited by adding and deleting.

Adding new module-role pairs

Format: edit INDEX r/+(MODULECODE[-ROLETYPE])+

• Adds new roles to 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 module-role pair must be provided.
• Multiple module-role pairs can be added at once, separated by " ".
• The role type can be omitted, in which case the role STUDENT will be the default.

Examples:

• edit 1 r/+CS2103T-Prof adds role "professor of CS2103T" to the first person.
• edit 1 r/+CS1101S MA1521-TA adds role "Student of CS1101S" and "TA of MA1521" to the first person.

Deleting existing module-role pairs

Format: edit INDEX r/-(MODULECODE[-ROLETYPE])+

• Deletes existing roles from 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 module-role pair must be provided.
• Multiple module-role pairs can be deleted at once, separated by " ".
• The role type can be omitted, in which case any associated role will be deleted. i.e. edit 1 r/-MA1521 will delete MA1521-Student, MA1521-TA or MA1521-Prof, whichever is present.

Examples:

• edit 1 r/-CS2103T deletes any role related to module CS2103T from the first person.
• edit 1 r/-CS1101S-Student MA1521-TA deletes the role "Student of CS1101S" and "TA of MA1521" from the first person.

Editing all other fields

Except for the module-role pairs, all other fields can only be edited by complete replacement.

Format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]+ [d/DESCRIPTION]

• 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.
• Similarly, you can remove a person's description by typing d/ without specifying any description after it.
• After editing, the app will go back to the main window and display the updated person list.

Examples:

• edit 1 p/91234567 e/johndoe@example.com Edits the phone number and email address of the 1st person to be 91234567 and johndoe@example.com respectively.
• edit 2 n/Betsy Crower t/ Edits the name of the 2nd person to be Betsy Crower and clears all existing tags.

Locating persons: find

The find command allows you to locate persons by their names, module-role pairs, tags or any combinations of them.

Finding by name

Finds persons whose names contain any of the given keywords.

Format: find (n/KEYWORD)+

• The search is case-insensitive. e.g hans will match Hans
• Each keyword can contain multiple words. e.g. John Doe
• Each keyword must exist contiguously in the name in order to match. e.g. John Doe will not match John David Doe
• Only the name is searched.
• Partial words will be matched as well. e.g. Han will match Hans
• Persons whose names matching at least one keyword will be returned (i.e. OR search). e.g. find n/Hans n/Bo will match Hans Gruber, Bo Yang

Examples:

• find n/John returns john and John Doe
• find n/alex n/david li returns Alex Yeoh, David Li
  

Finding by module-role

Finds persons whose module-role pairs contain any of the given keywords.

Format: find (r/KEYWORD)+

• Search by module code and optionally specify the role type (separated by a dash). For example, CS2103T-Prof will search for the module CS2103T with the role Professor.
• The search is case-insensitive. e.g. cs2103t-student will match CS2103T-Student.
• If the role type is not specified, role STUDENT will be assumed. For example, find r/CS2103T will return all students taking CS2103T.
• Persons whose module-role pairs matching at least one module-role keyword will be returned (i.e. OR search).

Examples:

• find r/CS2103T returns all students taking the module CS2103T

• find r/CS2103T-Prof r/CS1101S returns all persons with the role Prof in CS2103T or Student in CS1101S

  

Finding by tag

Finds persons whose tags contain any of the given keywords.

Format: find (t/KEYWORD)+

• The search is case-insensitive. e.g Friends will match friends
• Partial words will be matched as well. e.g. class will match classmates
• Persons whose tags matching at least one tag keyword will be returned (i.e. OR search)

Examples:

• find t/office returns all contacts whose tags contain word office

• find t/classmates t/friends returns all contacts whose tags contain either classmates or friends

  

Finding by combinations of names, module-roles and/or tags

Finds persons whose names, module-role pairs and tags contain any combination of the given keywords.

Format: find [chained] (n/KEYWORD | r/KEYWORD | t/KEYWORD)+

• Persons matching at least one name keyword (if provided) AND at least one module-role keyword (if provided) AND at least one tag keyword (if provided) will be returned.

• If chained is specified, chained find will be used.

Example:

• find n/Martin n/Boyd r/cs1101s-prof r/cs1231s-prof t/favorite return all persons whose name are either Martin or Boyd, and assumes either CS1101S Professor or CS1231S Professor, and has the tag favorite.

  

Deleting persons: delete

Deletes the specified person from the address book.

Format: delete (INDEX)+

• Deletes the person(s) at the specified INDEX(es).
• The index refers to the index number shown in the displayed person list.
• The indices must be a positive integer 1, 2, 3, …​

Examples:

• list followed by delete 1 2 3 deletes the 1st, 2nd and 3rd person in the address book.
• find n/Betsy followed by delete 1 deletes the 1st person in the results of the find command.

Clearing all entries: clear

Clears all contacts from the address book.

Format: clear

Undoing latest change to contact data: undo

Undoes the effect done by the latest data-modifying command, if any.

Format: undo

• Data-modifying commands refers to those who has direct manipulation over the contact data, such as add, edit, delete or clear.
• Commands that do not modify contact data in the address book(list, help, find etc.) are not considered by the undo command.
• If you input undo when there's nothing to undo, GUI will remind you about this and no effect would be applied to the address book.

Examples:

• If you accidentally delete a contact using the delete command, you can revert this change by input undo command.
• Similarly, if you accidentally clear the whole address book using the clear command, you can restore the whole address book using undo command as well.
• Wrong adding/editing of contact info can be reverted by inputting undo as well.

Redoing latest undone change to contact data: redo

Redoes the latest undone modification on contact data, if any. Format: redo

• Redo only helps to restore command results that can be handled by undo command, such as add, edit, delete and clear.
• If you input redo when there's nothing to redo, GUI will remind you about this and no effect would be applied to the address book.

Examples:

• If you undo a change to the contact data, but end up thinking that it may be better to keep it, you can input redo after undo the change to restore it back.
• Taking the same example from the undo session:

Exiting the program: exit

Exits the program.

Format: exit

Saving the data

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

Editing the data file

ContactCS data are saved automatically as a JSON file [JAR file location]/data/contactcs.json. Advanced users are welcome to update data directly by editing that data file.

Archiving data files [coming in v2.0]

Details coming soon ...

Input format

NAME field

In our application, we understand that everyone's names can have various characters and symbols, thus we decided that as long as it is not a blank string, it is considered acceptable.

PHONE_NUMBER field

The PHONE_NUMBER field (specified in the add or edit commands) is defined as a string where, if split by spaces, at least one of the resulting tokens is a valid phone number.

Some valid PHONE_NUMBER values include 81234567, 81234567 (handphone), or 81234567 (office 1) 91234567 (office 2). Since a contact may have different phone numbers at the same time, such as mobile, office, home etc, and any length of annotation to differentiate between them, we decide not to enforce any input length restriction on this field, to offer you more flexibility when taking down and annotating phone numbers of a contact.

EMAIL field

The EMAIL field accepts any string that is a valid email address.

Note that the email address does not need to contain a period(.) to be considered valid. For example, example@domain is considered valid.

MODULE_ROLE field

The MODULE_ROLE field represents the role of a contact, such as CS1101S Student, CS1231S Tutor or MA1522 Professor and so on. It consists of two sub-fields: MODULECODE and ROLETYPE.

MODULECODE field

The MODULECODE field refers to the module codes of modules in NUS, and is defined as at least one letter followed by at least one number and lastly ended by an optional sequence of letters.

This field is case-insensitive.

Some valid module code inputs include CS1231S, CS1231, CFG2002MY and DMA1201CH.

ROLETYPE field

The ROLETYPE field refers to the role assumed by a person in a module, and currently can be any of student, professor or tutor.

This field is case-insensitive.

ADDRESS field

The ADDRESS field can be used to refer to the address of any location related to a contact, such as home, office, consultation venue etc.

Since the length of address input may differ drastically because of the nature of the location and the complexity in its address name structure, we do not enforce restriction on the input length and as long as the input is not blank, it is considered as a valid address.

Some valid ADDRESS values include COM3-01-20, #05-03, Blk 211, Any Place Street 123, Singapore 123456, Utown Residence #12-34 etc.

TAG field

The TAG field allows you to group contacts. you can later use the find by tag feature to query them more easily.

For more detail on find by tag feature, refer to find contacts by tag section.

Examples of TAG values include friends, office and classmates.

DESCRIPTION field

The DESCRIPTION field aims to provide you a simple way to annotate a contact with some basic information for easy reference in the future.

For example, you can use it to record down how you feel about a professor's way of teaching, or remember the important birthday of a friend in NUS SOC or even zoom link of a lecture/tutorial session taught by a professor/tutor.As you can see, we try to provide as much flexibility to you as possible to allow you to record any short pieces of information about the contact, but we also want it to be short. Hence, we restrict the input size of the description to be 500 characters which should be enough for most users.

FAQ

Q: How do I transfer my data to another computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous ContactCS home folder.

Known issues

1. 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.
2. 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.
3. There is an unused space below the command history box.
   As shown in the screenshot above, marked by the red box.

Command summary