PlaNus User Guide v1.4
This user guide provides set-up instructions, and a detailed description of all the features available in the PlaNus application. You can also access this user guide on the application website with this link.
Table of Contents
- Introduction
- Set-up
- Features
- Glossary
- Command summary
- Input format summary
Introduction
PlaNus is a desktop application that manages tasks for students in NUS with busy schedule, optimized for use via a Command Line Interface (CLI) with the benefits of Graphical User Interface (GUI). PlaNus reduces the time spent by students in task management as adding tasks and lessons is simple and quick!
Objectives of PlaNus:
- Provide students with a detailed breakdown of how much time they spend on their tasks and lessons in their respective modules.
- Allow students to have a calendar view of their schedule.
Set-up
(Done by: Gabriella)
-
Ensure you have Java version 11 or above installed in your computer.
-
Download the latest jar file from here.
-
Copy the file to the folder you want to use as the home folder for PlaNus.
-
Double-click the file to start the app. Upon launching PlaNus, you should see the following interface.
-
Alternatively, in command prompt (for Windows) or terminal (in MacOS), go to the directory where planus.jar is stored and enter
java -jar planus.jar
.To open command prompt (for Windows) or terminal (in MacOS), simply search for them in your computer. -
You may try out some commands listed in the command summary to explore the app.
Features
This section is a comprehensive walkthrough of the features in PlaNus.
Notes about the command format
- Words highlighted are code snippets.
- e.g.
title
- e.g.
- Words in upper case are the parameters (i.e. your input) to be supplied by the you.
- e.g. in
event title:TITLE
,TITLE
is a parameter which you can provide. - For example, you can type
title:homework 1
ortitle:assignment
.
- e.g. in
- Items in square brackets are optional fields that you can provide to add more details to the command.
- e.g. command
event title:Title [desc:DESCRIPTION]
means that thedesc
field is optional. - In the above case, you can either type
event title:homework 1
ortitle:homework 1 desc:science project
if they want to store a description of the event.
- e.g. command
- Items with
...
after them can be keyed in multiple times.
- e.g.
delete-task INDEX...
can be used as bothdelete-task 1
ordelete-task 1 2 3
.
- e.g.
- Parameters can be in any order.
- e.g. commands
deadline title:TITLE desc:DESCRIPTION
anddeadline desc:DESCRIPTION title:TITLE
are the same.
- e.g. commands
1. General Features
This section shows features that deal with the general functionality of PlaNus application.
1.1 Show all commands : help
(Done by: Gabriella)
Shows you a link to the user guide.
Format: help
-
Type in
help
into the command box. -
A pop-up window with some sample commands and a link to the user guide will appear as shown below.
1.2 Clear the program : clear
(Done by: Gabriella)
You can clear all the tasks and lessons in PlaNus.
Format: clear
-
Type in
clear
into the command box. -
All the tasks and lessons in PlaNus will be cleared as shown below.
1.3 Exit the program : exit
(Done by: Gabriella)
You can exit PlaNus.
Format: exit
-
Type
exit
into the command box. -
The application window will automatically close.
2. Create, Read, Update and Delete a Task
This section shows features that deal with operation of tasks including
creating, reading, updating and deleting a task. A task can be either a
event
or deadline
.
2.1 List all tasks : list-task
(Done by: Beining)
You can list all the tasks in PlaNus.
Format: list-task
To show all tasks currently stored in PlaNus, you can do the following:
-
Type in
list-task
into the command box. -
A success message will appear and list of all tasks will be shown in the task panel.
2.2 Add a deadline : deadline
(Done by: Beining)
You can add a deadline to PlaNus.
A deadline is a task that has a compulsory deadline date and time.
Format: deadline title:TITLE [desc:DESCRIPTION] datetime:DATE_TIME [tag:MODULE_CODE]
- Adds a deadline to PlaNus,
- with the specified title in
title:TITLE
, - with the specified description in
description:DESCRIPTION
, - with a date and time in
datetime:DATE_TIME
of when this deadline should be completed before, - with a tag in
tag:MODULE_CODE
indicating the module of which this deadline belongs to.
- with the specified title in
- The added deadline will be tracked for time analysis if it has a tag.
Examples:
To add a deadline with title “Return book”, and a date and time of “02-01-2020 18:00” to PlaNus, you can do the following:
1) Type in the command box the following command:
deadline title:Return book datetime:02-01-2020 18:00
2) This adds the corresponding deadline to PlaNus. You can see the added deadline in the task list.
Notes
- Multiple inputs of the same attribute is not allowed.
E.g.
deadline title:Return book title:Borrow book datetime:02-01-2020 18:00
is not allowed as thetitle
attribute is input twice.
2.3 Add an event : event
(Done by: Beining)
You can add an event to PlaNus.
An event is a task that has a start time, end time and a date.
Format: event title:TITLE date:DATE from:START_TIME to:END_TIME [desc:DESCRIPTION] [tag:MODULE_CODE]
- Adds an event to PlaNus,
- with the specified title in
title:TITLE
, - with the specified description in
desc:DESCRIPTION
, - on the date specified in
date:DATE
, starting from the time specified infrom:START_TIME
to the time specified into:END_TIME
, - with a tag in
tag:MODULE_CODE
indicating the module this deadline belongs to.
- with the specified title in
- The added event will be tracked for time analysis if it has a tag.
- Event must not overlap with existing events or lessons.
Examples:
To add an event with title “Project meeting”, and a date “07-11-2020” with start time of “09:00” and end time of “12:30” and with tag “CS2103T” to PlaNus, you can do the following:
1) Type in the command box the following command:
event title:Project meeting date:07-11-2020 from:09:00 to:12:30 tag:CS2103T
2) This adds the corresponding event to PlaNus. You can see the added event in the task list and the calendar. The duration of the event will be recorded for time analysis.
Notes
- Multiple inputs of the same attribute is not allowed.
E.g.
event title:Project meeting title:Group meeting date:07-11-2020 from:09:00 to:12:30 tag:CS2103T
is not allowed as thetitle
attribute is input twice.
2.4 Mark a deadline as done : done
(Done by: Beining)
You can mark a specified deadline in PlaNus as done.
Format: done INDEX:TIME_TAKEN...
- Marks the deadline(s) at the specified
INDEX
as done and records the time taken to complete the deadline. - The index refers to the index number shown in the displayed task list.
- The time taken refers to the time in minutes that you took to complete the specific deadline.
- The index and time taken must be a positive integer e.g. 1:20, 2:30, 3:120, …
Notes
- There are two type of tasks, event and deadline.
- Only a deadline can be marked as done through this command, an error message will be shown if you attempt to mark an event as done.
- After you have marked a deadline as done, you cannot edit the deadline or undo the done command anymore.
Examples:
-
list-task
followed bydone 2:30 3:60
- Marks the 2nd and 3rd tasks in the results of the
list
command status to be done, and records that you have spent 30 minutes to finish the 2nd task, and 60 minutes to finish the 3rd task.
- Marks the 2nd and 3rd tasks in the results of the
-
find-task title:homework
followed bydone 1:20
- Marks the 1st task in the results of the
find
command status to be done and record the time taken to complete the deadline as 20 minutes.
- Marks the 1st task in the results of the
To mark the first deadline in the current task list as done and recording the time spent on it as 50 minutes, you can do the following:
1) Type in the command box the following command:
done 1:50
2) The status of the deadline has been set to complete, and the time taken to complete the task will be used for time analysis.
2.5 Edit a task : edit-task
(Done by: Gangwei)
You can edit a task by a set of attributes given below.
Format: edit-task INDEX ATTRIBUTE_1:NEW_VALUE ATTRIBUTE_2:NEW_VALUE ...
- Edits the task(s) at the specified INDEX.
- The index refers to the index number shown in the displayed task list.
- The index must be a positive integer e.g. 1, 2, 3, …
Notes
- If different fields are provided in the command, all the provided fields of the specified task will be updated.
- If a deadline has a status of complete, it cannot be edited.
- Fields that you can modify differ by the type of task (Event or Deadline) you are trying to modify.
- Available attributes for both deadline and event in 4 include:
-
title:
edits the title of the specified task -
desc:
edits the description of the specified task -
tag:
edits the tag of the specified task
-
- Available attributes for deadline only in v1.4 include:
-
datetime:
edits the date and time of the specified deadline
-
- Available attributes for event only in v1.4 include:
-
date:
edits the date of the specified event -
from:
edits the start time of the specified event -
to:
edits the end time of the specified event
-
Examples:
To edit the time of a task, you can do the following:
1) Display all lessons by typing list-task
in the command box, and find the index of the task you want to edit in the task list. The index is displayed in the top left corner of each task.
2) Type edit-task
and the index of the task, followed by the new date and time you want to update the task with.
For example, if you want to change the start time of the sixth task to be an hour earlier, you can type
edit-task 6 from:10:00
in the command box.
3) This changes the start time of the sixth task to 10:00 which is one hour earlier than the original start time. You can view the task with the updated information in the task list.
4) If the task that is being edited is an event, the calendar view will also be updated with the information.
Other examples:
-
edit-task 1 title:play games
- Edits the first task in the current displayed task list, changing its title to
play games
.
- Edits the first task in the current displayed task list, changing its title to
-
edit-task 3 desc:This is very urgent!
- Edits the third task in the current displayed task list, changing its description to “This is very urgent!”.
-
find-task title:homework
followed byedit-task 2 desc:Homework is difficult date:01-01-2020
- Edits the second task in the results of the
find-task
command. If the task is an event, it changes the date of the event to 01-01-2020 and its description to “Homework is difficult”. Otherwise, PlaNus will notify you of the incompatible error.
- Edits the second task in the results of the
-
edit-task 1 tag:CS2103T
- Edits the first task in the results of the current displayed task list, changing its tag to “CS2103T”.
Notes
- Multiple inputs of the same attribute is not allowed.
E.g.
edit-task title:play games title:watch tv
is not allowed as thetitle
attribute appeared twice in the input.
2.6 Find a task by an attribute : find-task
(Done by: Gangwei)
You can find a task by a set of attributes given below.
Format: find-task ATTRIBUTE_1:SEARCH_PHRASE ATTRIBUTE_2:SEARCH_PHRASE ...
Notes
-
If you provide different attributes in the command, tasks that match all attributes will be displayed.
-
If you provide multiple search phrases of the same attribute in the command, tasks that match any of the search phrases will be displayed.
Available attributes in v1.4 include:
-
title:
finds all tasks that contain the search phrase in the given title -
desc:
finds all tasks that contain the search phrase in the given description -
date:
finds all tasks that happen or due on the given date -
status:
finds all tasks with the given status -
tag:
finds all tasks related with the given module tag (case-insensitive)
Examples:
To find all tasks with a title containing the phrase “CS” (case-insensitive), you can do the following:
1) List all tasks by typing list-task
in the command box
2) Type the following command in the command box:
find-task title:CS
3) This lists all tasks with a title including the phrase CS
.
Other examples:
-
find-task title:play games
- Lists all tasks with a title containing the phrase
play games
.
- Lists all tasks with a title containing the phrase
-
find-task tag:CS2040
- Lists all tasks with the tag
CS2040
.
- Lists all tasks with the tag
-
find-task date:01-01-2020
.- List all tasks that happen or due on
01-01-2020
- List all tasks that happen or due on
-
find-task title:dinner title:lunch
.- List all tasks with the title including either
dinner
orlunch
.
- List all tasks with the title including either
2.7 Delete a task : delete-task
(Done by: Gangwei)
You can delete the specified task from PlaNus.
Format: delete-task INDEX...
- Deletes the task(s) at the specified
INDEX
. - The index refers to the index number shown in the displayed task list.
- The index must be a positive integer e.g. 1, 2, 3, …
- You can provide more than 1 index at the same time, e.g.
delete-task 1 2 3
.- However, if one of the index is invalid, the whole command will not be executed and an error message will be shown.
Examples:
To delete the first task, you can do the following:
1) Type list-task
in the command box to display all tasks.
2) Type delete-task 1
in the command box.
3) This deletes the 1st task from PlaNus.
Other examples:
-
list-task
followed bydelete-task 1 2
- Deletes the 1st task followed by the 2nd task in the results of the
list-task
command.
- Deletes the 1st task followed by the 2nd task in the results of the
You can also delete tasks by first finding the tasks of interest, refer to feature 2.6 for more information. Sample usage:
-
find-task title:homework
followed bydelete-task 1
- Deletes the 1st task in the results of the
find-task
command.
- Deletes the 1st task in the results of the
3. Create, Read, Update and Delete a Lesson
This section shows features that you can use to manage lessons. A lesson happens in a recurring manner that have a start and end time, and a start and end date.
3.1 List all lessons :list-lesson
(Done by: Gangwei)
You can list all the lessons in PlaNus.
Format: list-lesson
To show all lessons currently stored in PlaNus, you can do the following:
1) Type list-lesson
in the command box.
2) This displays all lessons in the lesson list.
3.2 Add a lesson : lesson
(Done by: Zijian)
You can add a lesson to PlaNus.
Format: lesson title:TITLE tag:MODULE_CODE [desc:DESCRIPTION] day:DAY from:TIME to:TIME start:DATE end:DATE
- Adds a lesson to PlaNus,
- with the title specified in
title:TITLE
, - that happens on the day specified by
day:DAY
, from the time specified byfrom:TIME
to the time specified byto:TIME
, between the start date specified bystart:DATE
and the end date specified byend:DATE
.
- with the title specified in
Notes
- The format of day in
day:DAY
must be as the following (case-insensitive):- Monday, Tuesday, …, Sunday
Examples:
To add a lesson with title “CS2101 Tutorial” under module “CS2101” that happens on every Monday from 10am to 12pm, starts on 10 Aug 2020 and ends on 10 Dec 2020, you can do the following:
1) Type in the command box the following command:
lesson title:CS2101 Tutorial tag:CS2101 desc:Most exciting tutorial in NUS! day:Monday from:10:00 to:12:00 start:10-08-2020 end:10-12-2020
2) This adds the corresponding lesson to PlaNus. You can then see the added lesson in the lesson list, calendar view and time analysis.
Notes
- Multiple inputs of the same attribute is not allowed.
E.g.
lesson title:Tutorial title:Lecture tag:CS2103T day:Monday from:10:00 to:12:00 start:10-08-2020 end:10-12-2020
is not allowed as thetitle
attribute is input twice.
3.3 Edit a lesson : edit-lesson
(Done by: Zijian)
You can edit a lesson in PlaNus. When a lesson is edited, all occurrences of the particular lesson will be updated.
Format: edit-lesson INDEX [title:TITLE] [tag:MODULE_CODE] [desc:DESCRIPTION] [day:DAY] [from:TIME] [to:TIME] [start:DATE] [end:DATE]
Notes
-
INDEX
refers to the index of the lesson in the lesson list. -
The format of day in
day:DAY
must be as follows (case-insensitive):- Monday, Tuesday, …, Sunday
Examples:
To edit a lesson, you can do the following:
1) Type list-lesson
in the command box. This will display all lessons.
2) Choose the lesson you want to edit. Find its index which is displayed on the top-left corner.
For example, if you want to change the first lesson to Tuesday, you can type edit-lesson 1 day:Tuesday
in the command box.
3) This changes the day of the first lesson to every Tuesday. You can see that the Calendar View and time analysis is also updated.
Notes
- Multiple inputs of the same attribute is not allowed.
E.g.
edit-lesson 1 title:tutorial 1 title:tutorial 2
is not allowed as thetitle
attribute is input twice.
3.4 Find a lesson : find-lesson
(Done by: Zijian)
You can find lessons in the lesson list by a set of attributes.
Format: find-lesson ATTRIBUTE_1:SEARCH_PHRASE ATTRIBUTE_2:SEARCH_PHRASE ...
Notes
-
ATTRIBUTE
refers to the category which you can use to search in the lesson list. The full list of categories supported is given below. -
SEARCH_PHRASE
refers to the actual input that you give for each attribute. -
If you provide different attributes in the command, lesson that match all attributes will be displayed.
-
If you provide multiple search phrases of the same attribute in the command, lessons that match any of the search phrases will be displayed.
Available attributes in v1.4 include:
-
title:
finds all lessons which contain the search phrase in the given title -
desc:
finds all lessons which contain the search phrase in the given description -
date:
finds all lessons happening on the searched date -
time:
finds all lessons happening at the searched time -
datetime:
finds all lessons happening at the searched date and time -
tag:
finds all lessons related to the given module tag (case-insensitive)
Examples:
To find all lessons with titles containing the phrase “tutorial” (case-insensitive), you just need the following steps:
1) List all lessons by typing list-lesson
in the command box:
2) Type the following command in the command box:
find-lesson title:tutorial
3) This lists all lessons with a title including the phrase tutorial
.
Other examples include:
-
find-lesson tag:CS2040
- Lists all lessons with a tag containing ‘CS2040’.
-
find-lesson date:01-01-2020
.- List all lessons happening on 01-01-2020.
-
find-lesson title:dinner title:lunch
.- List all lessons with the title including either
dinner
orlunch
.
- List all lessons with the title including either
-
find-lesson datetime:01-01-2020 14:00
- Lists all lessons happening on 01-01-2020 at 14:00.
3.5 Delete a Lesson : delete-lesson
(Done by: Zijian)
You can delete a specified set of lessons from PlaNus.
Format: delete-lesson INDEX...
Notes
-
INDEX
refers to the index of the lesson in the lesson list. -
...
means that there can be multiple indexes supplied. If all indexes are valid, all lessons of the specified indexes will be deleted.
Examples:
To delete the first two lessons, you can follow 3 simple steps:
1) Type list-lesson
in the command box to display all lessons.
2) Type delete-lesson 1 2
in the command box.
3) This deletes the first and the second lesson from PlaNus.
You can also delete lessons by first finding the lessons of interest, refer to feature 3.4 for more information. Sample usage:
-
find-lesson title:Lab
followed bydelete-lesson 1
- Deletes the 1st lesson in the result lesson list of the
find-lesson
command.
- Deletes the 1st lesson in the result lesson list of the
4. Calendar View
(Done by: Marcus)
PlaNus has two application views:
- Task and Lesson view: interface where you can see the list of your tasks and lessons
- Calendar view: interface where you can see all your tasks and lessons in a calendar
You can switch between Task and Lesson View and Calendar View.
Switching from Task and Lesson View to Calendar View:
Format: calendar
Example:
1) Type calendar
into the command box.
2) The Calendar View will appear as shown below.
With the Calendar View, you can have a clear and intuitive view of:
- how many events ans lessons you have on each day of the current month in the calendar’s Month View.
- what events and lessons you have for a particular day in the calendar’s Day View.
Notes
- Days in the Calendar View that are marked as grey are days that are not in the current month, and therefore unclickable. However, they can still display the number of events and lessons.
Changing back to Task and Lesson View:
You can change back to Task and Lesson view (which is displayed when the app starts) by issuing a list-task
command or a list-lesson
command.
5. Time Analysis
(Done by: Marcus)
You can use the pie chart and list of modules to visualise how much time you spent on each module in the past week. PlaNus calculates the time spent on each module based on the module code in its tag
.
How does it work:
- Each module has a time spent on tasks and time spent on lessons.
- When a
deadline
is marked as done, it contributes towards time spent on tasks for that module. - When an
event
has occurred, it contributes towards time spent on tasks for that module. - When a
lesson
has occurred, it contributes towards time spent on a lesson for that module.
Example:
- The first lesson in the list:
- Title of “CS2105 Lecture”
- Only occurred once in the past week
- Last for 2 hours from 14:00 to 16:00
Therefore, the time analysis for the week will show that the time spent on lessons with the CS2105 tag
as
120 minutes (2 hours).
Notes
- In v1.4 (current version):
- Only time spent on each module in the past week is displayed.
- In the upcoming version:
- A breakdown of time spent on each module in the past week and of all time is displayed.
Glossary
- Task: An event or a deadline.
- Event: Consists of a start time, end time and the date which it occurs on.
- Deadline: Consists of the date and time which the deadline falls on.
- Lesson: Consists of events that repeat every week for specified time period.
Command summary
General commands
Action | Format, Examples |
---|---|
Help | help |
Calendar View | calendar |
Clear all | clear |
Exit | exit |
Task related commands
Action | Format, Examples |
---|---|
List task | list-task |
Add Event |
event title:TITLE [desc:DESCRIPTION] date:DATE from:TIME to:TIME tag:MODULE_CODE e.g. event title:CS2103T Group meeting date:23-10-2020 from:20:00 to:22:00 tag:CS2103T
|
Add Deadline |
deadline title:TITLE [desc:DESCRIPTION] datetime:DATETIME tag:MODULE_CODE e.g. deadline title:Assignment2 submission datetime:23-10-2020 18:00 tag:CS2103T
|
Delete task |
delete-task INDEX... e.g. delete-task 3 , delete-task 3, 4, 5
|
Mark Task As Done |
done INDEX:TIME_TAKEN... e.g. done 1:20 , done 1:20 2:60 3:120
|
Find task |
find-task ATTRIBUTE_1:SEARCH_PHRASE ATTRIBUTE_2:SEARCH_PHRASE ... e.g. find-task title:dinner date:02-02-2020
|
Edit task |
edit-task INDEX [title:TITLE] [date:DATE] [desc:DESCRIPTION] [tag:MODULE_CODE] [datetime:DEADLINE (deadline only)] [date:EVENT_DATE (event only)] [start:START_TIME (event only)] [end:END_TIME (event only)] e.g. edit-task 1 date:02-02-2020 12:00 tag:CS2101
|
Lesson related commands
Action | Format, Examples |
---|---|
List lesson | list-lesson |
Add Lesson |
lesson title:TITLE tag:MODULE_CODE [desc:DESCRIPTION] day:DAY from:TIME to:TIME start:DATE end:DATE e.g. lesson title:CS2103T Lecture tag:CS2103T desc:Most exciting lecture in NUS! day:Mon from:12:00 to:14:00 start:01-01-2020 end:01-05-2020
|
Edit lesson |
edit-lesson INDEX [title:TITLE] [tag:MODULE_CODE] [desc:DESCRIPTION] [day:DAY] [from:TIME] [to:TIME] [start:DATE] [end:DATE] e.g.edit-lesson 1 start:10-10-2020
|
Find lesson |
find-lesson ATTRIBUTE_1:SEARCH_PHRASE ATTRIBUTE_2:SEARCH_PHRASE ... e.g. find-lesson title:Tutorial
|
Delete lesson |
delete-lesson INDEX... e.g. delete-lesson 1 2 3
|
Input format summary
All the keywords mentioned in the command should follow the format stated below:
keyword | Format, Examples |
---|---|
date |
dd-MM-yyyy e.g. 23-10-2020 |
time |
HH:mm e.g. 10:00 |
datetime |
dd-MM-yyyy HH:mm e.g. 21-10-2020 10:00 |
day | Monday/Tuesday/Wednesday/Thursday/Friday/Saturday/Sunday |
from, to, time |
HH:mm e.g. 18:00 |