By: AY1920S2-CS2103-W15-4      Since: Feb 2020      Licence: MIT

1. Introduction

Pet Store Helper (PSH) is for owners of pet stores who prefer to use a desktop app for managing their store. More importantly, PSH is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, PSH can help you get your work done faster than traditional GUI apps.

It is based on 2 main systems, one that manages pets, and another one that organises showering schedules.

Interested? Jump to the Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

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

  2. Download the latest .jar file from here.

  3. Copy the file to the folder you want to use as the home folder for your Pet Store Helper.

  4. Double-click the file to start the app. The GUI should appear in a few seconds.

    Welcome

  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.

  6. Some example commands you can try:

    • display p : Displays the list of all pets.

    • addpet n/Teddy g/male b/01/01/2019 s/dog f/brand A:15 f/brand B:20 t/small t/lazy: Adds a new pet with name Teddy and other details as given.

    • display s : Displays the current schedule as a list of slots.

    • addslot n/Teddy t/10/4/2020 1300 d/90: Adds a new showering slot for Teddy with details as given.

    • exit : Exits the program.

  7. Refer to Section 5, “Commands” for details of each command.

3. Features

3.1. Pet Tracker System

Details about each pet kept track of are its name, gender, species, date of birth and dietary requirements. In addition, tags for each pet may also be added.

petView

3.1.1. Pet Food Inventory

This shows the a list of all pet food (inventory) and the needed amount per week. Double-click on each food item to view the breakdown for each pet individually. This feature is integrated under the display feature as display i.

inventoryView

3.2. Schedule System

Written by Dylan Lim

There are 2 ways of displaying the slots tracked by the schedule system: either sequentially as a list of slots, or in the form of a calendar view.

3.2.1. Slots list view

Slots displayed here are arranged in ascending chronological order, with the earliest slot displayed first. In the case where multiple slots start at the same time, the slot with the shortest duration is shown first. If both starting time and duration are the same, they are sorted by pet names in ascending alphabetical order.

slotListView

Conflicted slots are distinguished from regular slots from the "[CONFLICT]" label beside the slot index number.

This view is obtained by the command display s.

3.2.2. Calendar view

The calendar view allows many more slots to be seen at once. From a quick glance, the relative durations and timings apart between slots can be seen.

Slots that fall on the same day are displayed on the same row. They are then positioned horizontally according to the time they start. The width taken up by each slot in this view is proportional to its duration.

If there are conflicted slots, then the time period in which these conflicted slot lie in is simply rendered as single "conflicted" slot.

calendarView

Regular slots are indicated by the salmon-colored regions, while conflicted slots of the same time period are represented by the maroon-colored regions.

This view is obtained by the command display c.

3.3. Statistics

The statistics of the pet store, which can be shown via stats, are:

  • The proportion of species of pets,

  • The planned schedule for the next 3 days, and

  • A breakdown of how many of each type of pet food is needed in a week.

stats

3.4. Back Up and Load

The back up and load commands together allow data to be stored and managed directly.

3.4.1. Back up

To back up the current state of the pet store, enter the backup command.

The file name is generated based on the current date and time and reported back.

It is stored in the same directory as the default data file.

backup

3.4.2. Load

To load a file, enter the load command followed by the file name.

The file should be stored in the same directory as the default data file.

For example, after removing a few pets and slots, the screen will be different from when we backed up previously.

load1

In this case, entering load 20200413_20_23_57 restores the system to its backed-up state.

load2

The file name can be any valid file name under the curent operating system and need not conform to the backup file naming scheme.

4. Limitations

Written by Dylan Lim

  • If the duration of a slot is sufficiently short, then information about the slot can be displayed only partially in calendar view. Workarounds available:

    • Hover the cursor over the slot, and a tooltip containing all the information about that slot will be shown.

    • Taking note of the index number of the slot, do display s and look up the slot with that index number.

    • Taking note of the date of the slot, search for that slot using findslots.

5. Commands

Command Format

  • Words in UPPER_CASE 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/Some Pet t/lazy or as n/Some Pet.

  • Items with …​ after them can be used multiple times including zero times e.g. [t/TAG]…​ can be used as   (i.e. 0 times), t/cute, t/small t/white etc.

  • Parameters can be in any order e.g. if the command specifies n/NAME g/GENDER, G/GENDER n/NAME is also acceptable.

5.1. Common / general commands

5.1.1. Viewing help: help

Shows the help window.

Format: help

5.1.2. Exiting the program: exit

Exits the program.

Format: exit

5.1.3. Changing the display: display

Written by Dylan Lim

Changes the display board to show the specified system.

Format: display SYSTEM

  • SYSTEM must be p (pets), s (slots list view), c (calendar view) or i (inventory). No other values are allowed.

Examples:

  • display p
    Displays all pets.

  • display s
    Displays all slots as a list.

  • display c
    Displays all slots in calendar view.

  • display i
    Displays a list of all pet food (inventory) and the needed amount per week.

See Section 3, “Features” for examples of how the different types of display look like.

5.1.4. Saving the data: backup

All data is saved to the hard disk automatically after any command that changes the data.
There is no need to save manually.
However, it is possible to save a separate backup file through the backup command.
The file name is a timestamp in the format "yyyyMMdd_HH_mm_ss".

5.1.5. Retrieving data: load

Loads the specified file from the hard disk.
Format: load FILE_NAME

  • Loads the file with the specified FILE_NAME.

  • The file name must be a valid file name under the OS.

Examples:

  • load 20200402_21_54_52
    Loads the file 20200402_21_54_52.json from the hard disk.

  • load pettracker
    Loads the file pettracker.json from the hard disk.

5.1.6. Statistics: stats

Written by Zhao Tianqi

Provides statistics about the pet tracker, schedule system, and inventory.

  • There is a pie chart representing the ratio of different pet species.

  • A timetable that shows an overall schedule for recent 3 days.

  • A bar chart that shows the weekly consumption of different pet food.

Written by Zhao Tianqi

5.2.1. Adding a pet: addpet

Adds a pet to the pet tracker system.

Format: addpet n/NAME g/GENDER b/DATE OF BIRTH s/SPECIES f/FOOD : AMOUNT [t/TAG]…​

  • The date of birth must be in the format of d/M/yyyy, e.g. 01/01/2019, 1/7/2018

  • The gender must be either female or male. Letter case does not matter.

  • Food is specified as a type of food complied with quantity of weekly consumption in an arbitrary unit. The food name and amount should be separated by a colon ":". There can be more than 1 types of food for one pet.

  • A pet can have any number of tags (including 0). Each tag must be restricted to one word .

  • The application ignores letter case of user input. The name, species, gender of pets, and name of food will be displayed in the format of "Xxx Xxx …​".

Example:

  • addpet n/Garfield g/male b/01/01/2019 s/cat f/Brand A: 30 t/lazy t/lasagna

5.2.2. Finding pets by names: findpets

Finds pets whose name contains any of the given keywords. The application will automatically change to the pet display system.

Format: findpets PETNAME [MORE PETNAMES]…​

  • At least one argument must be supplied.

  • Pets matching at least 1 keyword will be returned (i.e. OR search).

Example:

  • findpets garfield odie
    Returns a list of pets, whose names either contain garfield or odie or both.

5.2.3. Editing a pet: editpet

Edits any field of an existing pet in the system.

Format: editpet INDEX [n/NAME] [g/GENDER] [t/TAG]…​

  • If the app is displaying pets, the index refers to the index number shown in the displayed pets list, and must be a positive integer, e.g. 1, 2, 3, …​ Otherwise, the index refers to the number in the whole pet list.

  • The existing field(s) of the pet will be removed, i.e adding of list of food and tags is not cumulative.

  • You can remove all tags of a pet by typing t/ without specifying any tags after it.

  • Similarly to addpet command, pet name, species, gender, and name of food will be displayed in the format of "Xxx Xxx…​".

Example:

  • display p
    editpet 2 n/Coco b/02/01/2020 t/cuddly t/grey
    Overwrites information of the 2nd pet in the system with name "Coco", date of birth "2 Jan 2020, and 2 tags of “cuddly”, “grey”.

  • findpets garfield
    editpet 2 n/Coco
    Overwrites the name of the 2nd pet in the results of findpets garfield to "Coco"

  • display s
    editpet 1 n/garfield Overwrites name of the 1st pet in the whole pet list to be "Garfield".

5.2.4. Deleting a pet: deletepet

Deletes the specified pet from the system.

Format: deletepet INDEX

  • If the app is displaying pets, the index refers to the index number shown in the displayed pets list, and must be a positive integer, e.g. 1, 2, 3, …​ Otherwise, the index refers to the number in the whole pet list.

Examples:

  • display p
    deletepet 2
    Deletes the 2nd pet in the system.

  • findpets n/garfield
    deletepet 2
    Deletes the 2nd pet in the results of the findpets garfield command.

  • display i
    deletepet 2 Deletes 2nd pet in the whole pet list.

Written by Dylan Lim

5.3.1. Adding a slot: addslot

Adds a new slot to the schedule.

Format: addslot n/PETNAME t/DATETIME d/DURATION

Adds a new showering slot for a pet, identified by its name. This given pet must already exist in the pet tracker system.

The Pet Store Helper does not allow slots to span across multiple days. This is to allow slots to be displayed properly in calendar view. As such, slots must start and end on the same day.

Unlike pets, duplicate slots (same pets, same datetimes, same durations) are allowed to be added in, so that the system remains flexible to use. Such slots, when added, would simply be indicated as conflicts.

Upon addition of slot, the display remains the same (e.g. if the program was showing the list of pets, it will continue to show that even after a slot is added). This is because the user may wish to continue referring to the pets while adding more slots.

Details about the arguments:

  • The datetime must be in d/M/yyyy HHmm format.

    • The time must be in 24-hour format.

  • The duration is to be specified in minutes as a non-zero, positive integer, and cannot be longer than a day.

Examples:

  • addslot n/Coco t/10/4/2020 1300 d/90

  • addslot n/Teddy t/11/4/2020 1500 d/45

5.3.2. Finding slots: findslots

Finds slots occupied by a pet matching the specified name, or slots occupied on the given date, or both. At least a name, or a date, must be provided. Slots that matched the query will be returned and displayed sequentially as a list.

Format: findslots [n/PETNAME [MORE_PETNAMES]] [t/DATE [MORE_DATES]]

  • This command can take one pet name, one date, or one pet name and one date.

  • Slots with pets matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang. The similar case applies for dates. Thus, informally, given findslots n/name1 name2 t/date1 date2, it is equivalent to searching for slots that match (name1 OR name2) AND (date1 OR date2).

The program display will be switched to show the slots that are matched. These slots are shown sequentially as a list and are ordered chronologically, from earliest to latest.

Details about the arguments:

  • The date must be in d/M/yyyy format.

Example:

  • findslots n/Coco
    Displays all slots occupied by Coco.

  • findslots n/Coco Teddy
    Displays all slots occupied by Coco, as well as slots occupied by Teddy.

  • findslots n/Coco t/10/4/2020 11/4/2020
    Displays all slots occupied by Coco on 10/4/2020, and on 11/4/2020.

  • findslots n/Coco Teddy t/10/4/2020 11/4/2020
    Displays the slots that are:

    • occupied by Coco on 10/4/2020,

    • occupied by Coco on 11/4/2020,

    • occupied by Teddy on 10/4/2020, and

    • occupied by Teddy on 11/4/2020.

5.3.3. Edting a slot: editslot

Edits the details of an existing occupied slot in the schedule.

Format: editslot INDEX [n/PETNAME] [t/DATETIME] [d/DURATION]

The index passed in is intepreted differently, based on current display of the program.

  • If the program is displaying slots (via display s, display c or findslots), then the index is based on the index numbers shown in the current display (indicated with blue boxes).

slotIndex1
slotIndex2

  • Otherwise, the index refers to the index number of the slot in the entire schedule.

Every argument of this command is optional, since it might not be necessary to edit all the fields of a slot. However, at least one must be provided (else, nothing about the slot is changed). For fields with no new values provided, their existing values are retained. Only fields with new values provided will be updated to the input values.

As explained in the above section, the new slot must start and end on the same day.

Details about the arguments:

Examples:

  • display s
    editslot 1 t/10/4/2020 1300 d/120
    Edits the datetime and duration of the 1st slot to be 10/4/2020 1300, and 120 minutes respectively. The pet occupying the slot remains the unchanged.

  • findslots t/11/4/2020
    editslot 3 d/45
    Edits the duration of the 3rd slot in the search results of findslots to be 45 minutes.

  • display p
    editslot 12 n/Teddy
    Edits the 12th slot in the entire schedule to be occupied by Teddy.

5.3.4. Deleting a slot: deleteslot

Deletes the specified slot from the schedule.

Format: deleteslot INDEX

The index is intepreted in the same manner as in Section 5.3.3, “Edting a slot: editslot”.

Similar to addslot, the display remains the same (e.g. if the program was showing the list of pets, it will continue to show that even after a slot is deleted). This is because the user may wish to continue referring to the pets while deleting more slots.

Details about the argument:

  • The index must be a positive integer 1, 2, 3, …​

Examples:

  • display s
    deleteslot 2
    Deletes the 2nd slot in the schedule.

  • findslots n/Coco
    deleteslot 2
    Deletes the 2nd slot in the search results of findslots.

  • display i
    deleteslot 2
    Deletes the 2nd slot in the schedule (same as the first example in this section).

5.3.5. Showing all conflicts: conflicts

Displays all conflicted slots.

Format: conflicts

Displays the slots that have a conflict, i.e., an overlap in time with another occupied slot.

  • If the screen is not displaying the ful list of slots due to previous commands (e.g. findslots), command conflicts will show a list of conflicting slots among the shortlisted slots.

  • Otherwise, upon calling this command, the program display will be switched to show all conflicted slots. These conflicted slots are shown sequentially as a list and are ordered chronologically, from earliest to latest.

This command takes in no arguments.

6. Command Summary

  1. Common / general commands

    • Help: help

    • Exit: exit

    • Display: display SYSTEM
      e.g. display p
      e.g. display s
      e.g. display c
      e.g. display i

    • Statistics: stats

    • Back up: backup

    • Load backup: load FILE_NAME
      e.g. load 20200402_21_54_52

  2. Pet-related commands

    • Add pet: addpet n/NAME g/GENDER b/DATE OF BIRTH s/SPECIES f/FOOD NAME: AMOUNT [f/FOOD NAME: AMOUNT] [t/TAG]…​
      e.g. addpet n/Garfield g/male b/01/01/2019 s/cat tabby t/lazy f/Brand A: 30 t/lasagna

    • Find pet: findpets PETNAME [MORE PETNAMES]…​
      e.g. `findpets garfield odie

    • Edit pet: editpet INDEX [n/name] [b/DATE OF BIRTH] [t/TAG]…​
      e.g. editpet 2 n/garfield t/cuddly

    • Delete pet: deletepet INDEX
      e.g. deletepet 2

  3. Schedule-related commands

    • Add slot: addslot n/PETNAME t/DATETIME d/DURATION
      e.g. addslot n/Coco t/10/4/2020 1300 d/90
      e.g. addslot n/Teddy t/11/4/2020 1500 d/45

    • Find slots: findslots [n/PETNAME [PETNAME]] [t/DATE [DATE]]
      e.g. findslots n/Coco
      e.g. findslots n/Coco Teddy
      e.g. findslots n/Coco t/10/4/2020 11/4/2020
      e.g. findslots n/Coco Teddy t/10/4/2020 11/4/2020

    • Edit slot: editslot INDEX [n/PETNAME] [t/DATETIME] [d/DURATION]
      e.g. editslot 1 t/10/4/2020 1300 d/120
      e.g. editslot 3 d/45
      e.g. editslot 12 n/Teddy

    • Delete slot: deleteslot INDEX
      e.g. deleteslot 2

    • Show conflicts: conflicts

7. 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 Pet Store Helper folder.

Q: Why did I added a schedule slot and it is not showing in the statistics page?
A: The statistics page only provides the schedules of the nearest 3 days, according to the system time PSH operates on.

Q: What if I edit an attribute of a pet multiple times in a single command? eg. editpet 1 n/Andy n/Andrew
A: For f/ and t/, you can provide them for multiple times and all of them will be added to the attributes of the pet. However, for the other attributes, only the last entry is accepted, with a warning message generated.

Q: How do I start an empty application without the sample data?
A: First start PSH, and then use exit to quit the application. Go to the data directory, and open pettracker.json. Delete all information in the json file and leave pettracker.json as an empty file. Restart PSH and PSH will be empty.