MatchMate User Guide

MatchMate is a desktop app for Computer Science students in NUS to create groups among their friends / acquaintances, as well as to allow students to find balanced groups with diverse skill sets out of their own contact list. It is optimized for Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI).

This User Guide assumes that you have zero knowledge of our app and does not require any programming knowledge. However, familiarity with keyboard shortcuts will significantly improve your experience with Matchmate.

---

Navigating the User Guide

This user guide serves as an introductory guide to our app, MatchMate. Through this user guide, we hope to introduce to users what features are available, the format for each command, as well as to give instructions to aid users when a command is invalid or fails.

Ready to connect with other like-minded students and create the best group possible? Then jump right in with our list of features:

CourseMate Management

• Add a courseMate: Met a new friend? Add them to your contact list with add.
• Edit a courseMate: Wrongly inputted some details? No worries! Edit your course mate's information using edit.
• Add skills to a courseMate: Does your friend have notable skills that you want to take note of? If so, then you can use add-skill.
• Delete skills from a courseMate: Mistyped the skill name? Delete the skill by using delete-skill.
• Finding courseMates: Looking for someone specific? The find-mate command does exactly that!
• Rate courseMate: Had a good/bad experience with your course mates? rate-mate helps you to keep track of those experiences!
• List all courseMates: Shows all course mates and groups with list.
• Delete a courseMate: Burnt a bridge with someone? You can always remove them from your list with delete.

Group Management

• Create a group: Create a group for your upcoming project with create-group.
• Add members to your group: Easily add your friends to the group project using add-member.
• Delete members from your group: Changed your mind on some group members? delete-member has you covered!
• Add/edit a telegram URL to your group: Bring over the discussion to telegram by adding a telegram group url using edit-tg-chat-url.
• Require skills: Require some specific skill sets for your group project? Add those requirements using require-skill.
• Unrequire skills: Had second thoughts on the required skills? Easily delete them with unrequire-sklill.
• Mark important skills: Often times some skills are more needed than others. Mark these important skills with mark-important.
• Unmark important skills: Made a mistake in marking what's important? unmark-important reverses that.
• Suggest mate: Not sure which course mate to add into your group? suggest-mate helps you find course mates that fulfills the group's required skills.
• Finding groups: Looking for a specific group? The find-group command does exactly that!
• Delete a group: Finally done with your project? Say goodbye to your group project and remove it with delete-group.

Forgot about the features and formats for each command? Head over to the Command Summary for a quick overview.

---

Glossary

There may be some unfamiliar terms and tech jargon sprinkled within our user guide. As such, this segment aims to simplify those terms to improve your experience with MatchMate.

---

Quick start

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

   First check if you have Java 11 by opening your terminal, and typing in java -version. If the command fails, that means that you have not downloaded Java yet. If you do not have Java 11 installed yet, then you can download it from here.

2. Download the latest matchmate.jar from here.

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

4. Select "Open in Terminal" in the folder you put the jar file in, and use the java -jar matchmate.jar command to run the application.
   A GUI similar to the 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, these commands simulate the user flow of adding contacts, creating a group that require skills, and finding members for said group:

   • list : Lists all courseMates.

   • add John Doe -p 87654321 -e johndoe@example.com -s Leadership -s C++: Adds a courseMate named John Doe to the courseMate list.

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

   • create-group CS Group -cm John Doe -s C++ -s Java : Creates a group containing John Doe, this group also requires the skill C++.

   • suggest-mate CS Group: Suggests a possible courseMate whose skills match some unfulfilled skills in the group CS Group.

   • exit : Exits the app.

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

---

User Interface

The UI consists of four main components:

1. Command Box: You can type your commands here and press Enter to execute them. You can also use the and arrow keys to navigate through your command history.

   Note: The key will retrieve the previous command in the command history. When there is no previous command, it will cycle back to the most recent command. The key will retrieve the next command. However, it will not cycle if you have reached the most recent command.

   This behavior is similar to the command history in a typical terminal.

2. CourseMate List Panel: Displays the list of courseMates. Press Enter or double click to select a courseMate from the courseMate list panel.

3. CourseMate Detail Panel: Displays the details of a selected courseMate.

4. Group List Panel: Displays the list of groups.

You can use the Tab key to switch between the command box and the courseMate list panel.

---

Commands: General

Viewing help : help

Shows a message that explains how to access the help page.

Format: help

Listing all courseMates and groups: list

Lists all courseMates and groups in the lists.

Format: list

Expected output:

• Message: Listed all courseMates and groups

Exiting the program : exit

Exits the program.

Format: exit

Commands: CourseMate Management

Adding a courseMate: add

Adds a courseMate to the courseMate list. A name and an email will be required, and all other information will be optional.

Format: add NAME -e EMAIL [-p PHONE_NUMBER] [-t TELEGRAM_HANDLE] [-s SKILL]...​

Parameters:

• NAME: Name of the courseMate. The string must only contain alphanumeric characters and spaces. Pick a nickname if the name is not fully alphanumeric.
• EMAIL: Email of the courseMate. Refer to the notes below for the acceptable format.
• PHONE_NUMBER (optional): Phone number of the courseMate. Accept strings with numeric characters only.
• TELEGRAM_HANDLE (optional): Telegram handle of the courseMate. Accept strings formed by alphanumeric characters and underscores only, and its length must be between 5 and 32 characters.
• SKILL (zero or multiple allowed): Skill(s) of the courseMate. Accepts any strings, except that words cannot start with the hyphen (-) character.

Examples:

• add John Doe -e e1234567@u.nus.edu
• add John Doe -e johndoe@example.com -p 87654321 -t johndoe -s Leadership -s C++

Editing a courseMate : edit

Edits an existing courseMate with a given name. This command supports changing the name, email, phone number and telegram handle.

Format: edit COURSEMATE [-n NEW_NAME] [-e NEW_EMAIL] [-p NEW_PHONE_NUMBER] [-t NEW_TELEGRAM_HANDLE] (at least one field to edit must be supplied)

Parameters:

• COURSEMATE: Name of the existing courseMate or aliases (substrings or in hashtag (#) notation).
• NEW_NAME (optional): New name of the courseMate. The string must only contain alphanumeric characters and spaces. Pick a nickname if the name is not fully alphanumeric.
• NEW_EMAIL (optional): New email of the courseMate. Refer to the notes above for the acceptable format.
• NEW_PHONE_NUMBER (optional): New phone number of the courseMate. Accept strings with numeric characters only.
• NEW_TELEGRAM_HANDLE (optional): New Telegram handle of the courseMate. Accept strings formed by alphanumeric characters and underscores only, and its length must be between 5 and 32 characters.
• At least one field to edit must be supplied.

Examples:

• edit John Doe -n Joe Schmo
• edit #1 -n Joe Schmo
• edit John -e johndoe@gmail.com -p 98765432

Add skills to a courseMate : add-skill

Adds a list of skills to a courseMate. Adding a skill that already exists in the courseMate will still succeed, but it won't show duplicate skills.

Format: add-skill COURSEMATE -s SKILL [-s SKILL]...

Parameters:

• COURSEMATE: Name of the existing courseMate. Accept aliases (substrings or in hashtag (#) notation).
• SKILL (one or multiple allowed): Skill(s) of the courseMate. Accepts any strings containing ASCII characters (characters with ASCII value from 0-127), except that words cannot start with the hyphen (-) character.

Examples:

• add-skill John Doe -s C++ -s Leadership

Delete skills from a courseMate : delete-skill

Deletes a list of skills from a courseMate.

Format: delete-skill COURSEMATE -s SKILL [-s SKILL]...

Parameters:

• COURSEMATE: Name of the existing courseMate. Accept aliases (substrings or in hashtag (#) notation).
• SKILL: (one or multiple allowed): Skill(s) of the courseMate. These must be existing skills that the courseMate contains.

Examples:

• delete-skill John Doe -s C++ -s Leadership

Finding courseMates with keywords: find-mate

Finds all courseMates whose names or skills contain the specified keyphrase (case-insensitive).

To match a courseMate’s skill, the keywords should match exactly with the skill. To match a courseMate’s name, the keywords can be a case-insensitive substring of the name.

Format: find-mate KEYPHRASE

Parameters:

• KEYPHRASE: Combination of keywords to be used for the search. Accepts any strings including spaces.

Examples:

• find-mate John
• find-mate C++

Deleting a courseMate : delete

Deletes a courseMate with a given name.

Format: delete COURSEMATE

Parameters:

• COURSEMATE: Name of the existing courseMate. Accept aliases (substrings or in hashtag (#) notation).

Examples:

• delete ##
• delete John

Rate a courseMate: rate-mate

Rates a courseMate by up to five stars.

Format: rate-mate COURSEMATE -r RATING

Parameters:

• COURSEMATE: Name of the existing courseMate to give the rating to. Accept aliases (substrings or in hashtag (#) notation).
• RATING: The rating given, which is a single digit integer between 0 and 5, where 0 signifies that no rating is given.

Examples:

• rate-mate Bob -r 5

Commands: Group Management

Create group project: create-group

Creates a group project. You can specify the courseMates in the group when creating the group, or choose to add them later.

Format: create-group GROUP_NAME [-t TELEGRAM_CHAT_URL] [-cm COURSEMATE]... [-s SKILL]...

Parameters:

• GROUP_NAME: The group name. The string must only contain alphanumeric characters and spaces. Pick a nickname if the name is not fully alphanumeric.
• TELEGRAM_CHAT_URL (optional): The URL of the Telegram chat for the group. Accept strings that start with https://t.me/ and followed by alphanumeric characters and the special characters +, - and _.
• COURSEMATE (zero or multiple allowed): Name of the existing courseMates to be added to the group. Accept aliases (substrings or in hashtag (#) notation).
• SKILL (zero or multiple allowed): Required skill(s) of the group. Accepts any strings, except that words cannot start with the hyphen (-) character.

Examples:

• create-group CS2103T G18
• create-group CS2103T G18 -t https://t.me/+WDTg34uuUlH8Ml2d
• create-group CS2103T G18 -cm John -cm #2 -s C++ -s Java
• create-group CS2103T G18 -cm John -s C++ -s Java -cm #2 -t https://t.me/+WDTg34uuUlH8Ml2d

Add courseMates to group: add-member

Adds some team members to an existing group.

Format: add-member GROUP_NAME -cm COURSEMATE [-cm COURSEMATE]...

Parameters:

• GROUP_NAME: Name of the existing group.
• COURSEMATE (one or multiple allowed): Name of the existing courseMates to be added to the group. Accept aliases (substrings or in hashtag (#) notation).

Examples:

• add-member CS2103T G18 -cm Ivan -cm #1
• add-member CS2103T G18 -cm ##

Delete courseMates from group: delete-member

Deletes some team members from an existing group.

Format: delete-member GROUP_NAME -cm COURSEMATE [-cm COURSEMATE]...

Parameters:

• GROUP_NAME: Name of the existing group.
• COURSEMATE (one or multiple allowed): Name of the existing courseMates to be deleted from the group. Accept aliases (substrings or in hashtag (#) notation).

Examples:

• delete-member CS2103T G18 -cm Ivan -cm #1
• delete-member CS2103T G18 -cm ##

Edit the telegram chat URL of a group: edit-tg-chat-url

Edits the telegram chat URL of a group.

Format: edit-tg-chat-url GROUP_NAME -t NEW_TELEGRAM_CHAT_URL

Parameters:

• GROUP_NAME: Name of the existing group.
• NEW_TELEGRAM_CHAT_URL: New URL of the Telegram chat for the group. Accept strings that start with https://t.me/ and followed by alphanumeric characters and the special characters +, - and _.

Examples:

• edit-tg-chat-url CS2103T G18 -t https://t.me/+WDTg34uuUlH8Ml2d

Require skills in a group: require-skill

Add skills that should be required or necessary for the group. You only need one member that possesses the skill for it to be marked as fulfilled. Fulfilled skills are marked in green while unfulfilled ones are marked in red.

Format: require-skill GROUP_NAME -s SKILL [-s SKILL]...

Parameters:

• GROUP_NAME: Name of the existing group.
• SKILL (one or multiple allowed): Required skill(s) of the group. Accepts any strings, except that words cannot start with the hyphen (-) character.

Examples:

• require-skill CS2103T G18 -s C++ -s Java

Unrequire skills in a group: unrequire-skill

Mark skills that are no longer required or necessary for the group.

Format: unrequire-skill GROUP_NAME -s SKILL [-s SKILL]...

Parameters:

• GROUP_NAME: Name of the existing group.
• SKILL (one or multiple allowed): Skill(s) to be marked as no longer required in the group. Accepts any strings, except that words cannot start with the hyphen (-) character.

Examples:

• unrequire-skill CS2103T G18 -s C++ -s Java

Mark important skills in a group: mark-important

Mark skills that are considered as important in the group. Important skills are signified with a [!] notation.

Format: mark-important GROUP_NAME -s SKILL [-s SKILL]...

Parameters:

• GROUP_NAME: Name of the existing group.
• SKILL (one or multiple allowed): Skill(s) to be marked as no longer required in the group. Accepts any strings, except that words cannot start with the hyphen (-) character.

Examples:

• mark-important CS2103T G18 -s C++ -s Java

Unmark important skills in a group: unmark-important

Mark skills that are no longer considered as important in the group.

Format: unmark-important GROUP_NAME -s SKILL [-s SKILL]...

Parameters:

• GROUP_NAME: Name of the existing group.
• SKILL (one or multiple allowed): Skill(s) to be marked as no longer required in the group. Accepts any strings, except that words cannot start with the hyphen (-) character.

Examples:

• unmark-important CS2103T G18 -s C++ -s Java

Suggest courseMates for group: suggest-mate

Searches courseMates that has any of the required skills from the group that is not fulfilled yet. CourseMates already in the group will not be listed.

Format: suggest-mate GROUP_NAME

Parameters:

• GROUP_NAME: Name of the existing group.

Examples:

• suggest-mate CS2103T G18

Search groups with keywords: find-group

Search groups that include all matching keywords in their name.

To match a group's name, the keywords can be a case-insensitive substring of the name.

Format: find-group KEYPHRASE

Parameters:

• KEYPHRASE: Combination of keywords to be used for the search. Accepts any strings including spaces.

Examples:

• find-group CS2103T G18

Delete a group: delete-group

Deletes a group.

Format: delete-group GROUP_NAME

Example: delete-group CS2103T G18

Parameters:

• GROUP_NAME: Name of the existing group.

Other Features

Save and load the state of app

Load the saved data when starting the app. Save the state of courseMates and groups every time it is updated via adding or editing. This should run automatically on start and subsequently after a command that alters the state of the app (e.g. add, edit).

Editing the data file

MatchMate data are saved automatically as JSON files in [JAR file location]/data/. It is possible but not recommended to edit the different .json files directly instead of through the app.

---

Troubleshooting

Q: I encountered the error message Invalid command format! when I tried to execute a command. What should I do?
A: You are likely to have missed out on a required parameter for the command. Refer to the Command Summary for the correct format of the command. Note that parameters in square brackets are optional, while those without square brackets are required.

Q: I encountered the error message Some of the specified members could not be found. when I tried to add a member to a group. What should I do?
A: If you used the hashtag notation (## or #n) to refer to a courseMate, check if the courseMate is displayed in the panel. Retry the command with an existing hashtag. Otherwise, you may have misspelled the courseMate's name. You can use the find-mate command to search for the courseMate.

Q: I accidentally deleted a courseMate. Can I undo the deletion?
A: Unfortunately, the deletion of a courseMate is irreversible. You will need to re-add the courseMate to the list.

---

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 MatchMate home folder.

Q: Do I need internet connection to run MatchMate?
A: MatchMate is an offline application that does not require any internet connection.

Q: How do I save the changes that I have made?
A: All your data is automatically saved, so there's no need to manually save it.

---

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.

---

Command summary