User Guide

                                    *Brings food over*
            
             ----------------  /'--.._ `'-="""=-'` _..--'\
             | my lunch? :D |  |   ~. )  _     _  ( .~   |
             ----------------   \  '~/   a  _  a   \~'  /
                             \   \  `|     / \     |`  /
                              \___`'--\    \_/    /--'`
                                      .'._  J__.-'.
                                      / /  '-/_ `-  \
                                     / -"-'-.  '-.__/
                                     \__,-.\/     | `\
                                     /  ;---.  .--'   |
                                    |     /\'-'      /
                                    '.___.\   _.--;'`)
                                    
            
            Welcome to ZooKeep! We know your zookeeping duties are hard,
            so we're here to make your life easier with some automation!
            
            
            ASCII art by Joan G. Stark.

If this is your first time using ZooKeep, this guide will serve to provide a reference for you to get familiar with the application.

1. Introduction (Jun Cheng)

This section gives you a quick overview about ZooKeep.

ZooKeep is a desktop app for managing animals under a zookeeper’s care, optimized for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, ZooKeep can get your management tasks done faster than traditional GUI apps.

2. Legend (Malcolm)

The following are symbols you should look out for when using this guide.

Provides additional information.

Provides tips while performing the feature stated.

Provides input constraints for the command.

3. Quick start (Jeremy)

You can follow the steps below to get started with ZooKeep.

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

2. You can download the latest ZooKeep.jar from here.

3. Copy ZooKeep.jar to the folder you want to use as the home folder for the app.

4. Double-click the file to start the app. The GUI similar to Figure 1 below should appear in a few seconds. Note how the app contains some sample data.
   

   

   Figure 1: GUI shown upon starting ZooKeep

5. Type the command you want in the command box and press Enter to execute it, e.g. typing help and pressing Enter will open the help window.
   Here are some example commands you can try:

   • list : Lists all animals.
   • exit : Exits the app.

6. You can refer to the features below for the details of each command. For the convenience of new users, the basic features are listed first, followed by additional advanced features which may be useful for the user.

4. Basic features (Malcolm)

This section provides you with the most basic features to get you started with ZooKeep.

4.1. Viewing help: help (Aizat)

If you ever need any help on how to use ZooKeep or want to see what features it supports, type help into the input box, and ZooKeep will show a message as shown in Figure 2 below explaining how you can access the help page.

Figure 2: Help message shown upon entering command

Format: help

Expected Outcome:

Opened help window.

A message is displayed containing a link to this User Guide.

4.2. Exiting the program: exit (Malcolm)

After you finish using ZooKeep, you can use this command to close it.

Format: exit

Expected Outcome:

Your ZooKeep application closes.

4.3. Listing all animals: list (Malcolm)

This command is used when you need to display all the animals stored in your ZooKeep book, such as when you have finished filtering animals using the find command.

Format: list

Expected Outcome:

Listed all animals

All animals in your ZooKeep book are displayed.

4.4. Clearing all entries: clear (Zhi Yuan)

You can use this to clear all the entries of your ZooKeep book and start the application with a clean slate.

Format: clear

Expected Outcome:

ZooKeepBook has been cleared!

All animals in your ZooKeep book are cleared.

4.5. Adding an animal: add (Jeremy)

When you get new animals assigned to you, you can use add to make new entries for them to keep track of any important information. Compulsory entries you need to add are the animals’ names, species and ID number. You can choose to add optional fields like medical conditions and feed times if necessary.

Format: add n/NAME s/SPECIES i/ID [m/MEDICAL_CONDITION]… [f/FEED_TIME]…​

Tip: An animal can have any number of medical conditions and feed times (including 0).

Examples:

• add n/Hershey s/Rufous Hummingbird i/193
• add n/Lonesome George s/Galapagos Tortoise i/117 m/Flu f/1200

Example Usage:

add n/Kai Kai s/Giant Panda i/200 m/Sunstroke f/1230 f/1400

Figure 3: User entering add command

Expected Outcome:

New animal added
Name: Kai Kai ID: 200 Species: Giant Panda Medical conditions: [Sunstroke] Feed times: [1230][1400]

Figure 4: User executing add command

As illustrated in Figure 4 above, an animal with the name Kai Kai, ID 200, species Giant Panda, medical condition Sunstroke and feed times of 1230 hrs and 1400 hrs is added to your ZooKeep book.

4.6. Deleting an animal: delete (Aizat)

When a particular animal in your ZooKeep book is no longer under your care, you can use this command to delete that animal by entering its ID. ID refers to the id number shown in the displayed animal list.

Format: delete ID

Example Usage:

delete 200

Figure 5: User entering delete command

Expected Outcome:

Deleted Animal
Name: Kai Kai ID: 200 Species: Giant Panda Medical conditions: [Sunstroke] Feed times: [1230][1400]

Figure 6: User executing delete command

The animal with ID 200 is deleted from your ZooKeep book, as shown in Figure 6 above.

4.7. Undoing a command: undo (Zhi Yuan)

When you make a mistake in your ZooKeep book, such as an accidental delete, you can perform this operation which undoes the most recently used command. No changes will be made if no previous state exists, meaning that you cannot undo if you just started up the application.

Format: undo

Example usage: Refer to the scenario in the delete section above as illustrated in Figure 5 & 6, where you just deleted Kai Kai from your ZooKeep book. Now you decide to use undo to bring Kai Kai back into your book by typing undo as seen in Figure 7 below:

Figure 7: User entering undo command

Expected Outcome:

Undo successful

Figure 8: User executing undo command

The previous command is undone, and as seen in Figure 8 above, Kai Kai is now back in your ZooKeep book!

4.8. Redoing an undo: redo (Jun Cheng)

You can use this command to quickly redo a command that was just undone by undo. For example, after you undo an accidental delete, you can use redo to perform the delete again. You can only use redo if undo was used before and no edit to your ZooKeep book was made in between, otherwise this command will do nothing.

Format: redo

Example usage: Refer to Figures 7 & 8 above where you just executed the undo command. You decide to delete Kai Kai from your ZooKeep book after all, and type redo into the interface as shown in Figure 9:

Figure 9: User entering redo command

Expected Outcome:

Redo successful

Figure 10: User executing redo command

The undone command is redone. It will show Kai Kai deleted from your ZooKeep book as seen in Figure 10.

5. Advanced features (Zhi Yuan)

When you are comfortable with the basic features, you can try the follow advanced features to achieve more.

5.1. Appending information to an animal’s fields: append (Jeremy)

If you forgot to add the medical conditions and/or feed times for a particular animal, you can use this feature to append the missing information to the respective fields of the animal with the specified ID instead of deleting and adding that same animal again. ID here refers to the id number shown in the displayed animal list.

Format: append ID [m/MEDICAL_CONDITION]… [f/FEED_TIME]…​

Tip: An animal can have any number of medical conditions and feed times (including 0).

Examples:

• append 200 f/1900
• append 200 m/Flu

Example Usage:

append 200 m/Flu

Figure 11: User entering append command

Expected Outcome:

Appended Animal Details
Name: Kai Kai ID: 200 Species: Giant Panda Medical conditions: [Flu][Sunstroke] Feed times: [1230][1400]

Figure 12: User executing append command

The medical condition “Flu” is appended to the medical conditions of the animal with ID 200. Figure 12 above reflects what you will see in your ZooKeep book.

5.2. Replacing an animal’s fields: replace (Jeremy)

If you made a mistake while entering the information of an animal in your ZooKeep book, instead of deleting the animal and entering all the information again, you can use this command to replace only the incorrect fields of the animal after specifying its ID. ID refers to the id number shown in the displayed animal list. Note that if this command is used on an animal’s MEDICAL_CONDITIONs or FEED_TIMEs, all of its previous MEDICAL_CONDITIONs or FEED_TIMEs will be replaced.

Format: replace ID [n/NAME] [s/SPECIES] [i/ID] [m/MEDICAL_CONDITION]… [f/FEED_TIME]…​

Tip: An animal can have any number of medical conditions and feed times (including 0). You can use m/ or f/ to clear all the existing medical conditions or feed times of an animal respectively.

Examples:

• replace 200 i/2910
• replace 200 i/2910 n/Jirachi
• replace 200 i/2910 m/

Example Usage:

replace 200 i/2910 n/Jirachi

Figure 13: User entering replace command

Expected Outcome:

Replaced Animal Details
Name: Jirachi ID: 2910 Species: Giant Panda Medical conditions: [Flu][Sunstroke] Feed times: [1230][1400]

Figure 14: User executing replace command

Figure 14 above shows the animal with ID 200 having its ID replaced with 2910 and its name replaced with Jirachi.

5.3. Finding animals by their fields: find (Jun Cheng)

You may find yourself in situations where you need to retrieve a specific group of animals from your ZooKeep book. For example, you may need to find animals with the same feed times or similar medical conditions. You can use this command to find and list all animals in your ZooKeep book whose fields contain any of the specified argument keywords (at least 1). The argument keywords do not need to exactly match the values in the fields; only a partial match is needed.

Format: find KEYWORD [MORE KEYWORDS]…

Tip: Keyword matching is case insensitive.

Examples:

• find Ahmeng Buttercup Coco finds all animals with the fields (name) containing any of the specified keywords.
• find 1200 finds all animals with the field (id or feed time) containing the specified keyword.
• find be finds all animals with the fields containing the specified keyword. If there is an animal named ‘Bell’ and another animal with a medical condition called ‘Benign Tumour’, both animals will be listed due to a partial match.

Example Usage:

find Kai Kai

Figure 15: User entering find command

Expected Outcome:

1 animals listed!

Figure 16: User executing find command

The animal with name Kai Kai is displayed as seen in Figure 16 above.

5.4. Sorting animals: sort (Malcolm)

If you need to create some sort of ordering in your ZooKeep book, such as a chronological order by feed times to organise your feeding schedule, this feature helps you to sort all your animals by the given category and updates the list of animals accordingly.

Format: sort CATEGORY

These are the category options you can sort the animals by:

• name: Sorts all animals by their name in alphabetical order (case-insensitive).
• id: Sorts all animals by their id in ascending order.
• feedtime: Sorts all animals by their earliest feed time in chronological order.
• medical: Sorts all animals by their number of medical conditions in ascending order.

Tip: The category input is case insensitive.

Examples:

• sort name
• sort id

Example Usage:

sort id

Figure 17: User entering sort command

Expected Outcome:

Sorted all animals by id

Figure 18: User executing sort command

The animals in your ZooKeep book are sorted by their ID, in ascending order. Figure 18 above should correspond with what you see.

5.5. Saving a snapshot of animal data: snap (Aizat)

This command is useful for storing important archives in the data/snapshots folder of your ZooKeep application, in case you need to refer to the information of animals that have been deleted long ago. When executed, this command will create a snapshot of the current ZooKeep book data, saved as a file with the user specified file name.

Please refer to the FAQ to find out how to load a snapshot that you have saved.

Format: snap FILE_NAME

Examples:

• snap zookeepbook_19-10-2020
• snap archive_1

Example Usage:

snap zookeepbook_19-10-2020

Figure 19: User entering snap command

Expected Outcome:

Current ZooKeepBook saved as zookeepbook_19-10-2020.json

Figure 20: User executing snap command

Figure 21: The directory where the archived file is located

A file named zookeepbook_19-10-2020.json is created in the data/snapshots directory as seen in Figure 21. This file contains the state of your ZooKeep book data at the point in time when the command was executed.

6. FAQ (Aizat)

This section lists some of the frequently asked questions.

Q: How do I transfer my data to a new computer?
A: First, install the app on your new computer. Next, copy over the zookeepbook.json file from your old computer and paste it into the data folder of your new computer.

Q: How can I manually save new data that I enter into the application?
A: You do not need to manually save data as animal data is saved in the hard disk automatically as a file named zookeepbook.json after any command that changes the data. Please do not manually edit this file as it may result in loss of data or unexpected behaviour when running the application.

Q: How can I load a snapshot that I created using the snap command?
A: First, go to your data folder and rename your zookeepbook.json file into something else, such as zookeepbook_current.json. Next, copy the snapshot you wish to load, paste it into the data folder and rename this snapshot to zookeepbook.json. The next time you launch ZooKeep, your snapshot will be loaded.

Q: Can I record the feed times of a specific animal in any order I prefer?
A: The feed time will be arranged in chronological order regardless of the order entered for easier reference.

Q: Can I search for animals based on a certain alphabet or half specified keywords?
A: Yes. The keywords entered as parameters can be used for partial matching.

7. Command summary (Zhi Yuan)

If you need a quick reference guide, the following tables should help.

Basic commands

Advanced commands