MyBookshelf User Guide

Community libraries are a testament to the goodwill of the community, but what is stopping bad actors from taking advantage of your library?

Welcome to MyBookshelf, a desktop application for Community Library Managers like you!

MyBookshelf is here to provide you with a framework to better manage library user contacts, books, and borrowing activity.

MyBookshelf provides you with a contact list to help keep track of library users, a library to keep track of your books and a novel Merit Score system to help manage library users' ability to borrow books.

This application is tailored for fast typists, optimised for use via a Command Line Interface (CLI) while not compromising on the benefits of a Graphical User Interface (GUI).

If you need help with running MyBookshelf, this user guide is designed to help you with:

• Installation,
• Understanding the user interface and commands,
• Troubleshooting issues and answer queries and,
• Giving you a sneak peek to future updates!

---

Quick Installation

Windows

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

   • You can refer to this YouTube video to check your current Java version.
   • If you do not have Java 11, you are recommended to download it from here
     
     

2. Download the latest mybookshelf.jar from here.

3. Copy and paste the file to you will use as the home folder for the MyBookshelf app.

   • Open your file explorer with Windows Key + E or clicking the file explorer icon.
   • Navigate to the Downloads folder (Default directory for downloaded files will be the Downloads folder).
   • Copy the downloaded mybookshelf.jar and paste it to the folder you will use as the home folder for the MyBookshelf app.
     
     

4. Access the command prompt.

   • Open the Run menu with Windows Key + R, then type "cmd".
     
     
   • Click "Ok".
   • Command prompt window will appear in a few seconds. Command prompt window should look similar to the image below.
     
     
   • If you have issues opening command prompt, you can refer this YouTube video.
     
     

5. cd into the folder you placed mybookshelf.jar file in, and enter the following command to run the application.
   

   java -jar mybookshelf.jar
   

   • You can refer to the image below.
     Note: YOUR_USERNAME and HOME_FOLDER might be different from yours.
     
     
     

6. A window similar to the one below should appear in a few seconds. Notice that the app initialises with some sample data.
   

   
   

7. Type the command into the command box and press Enter to execute it. e.g. typing help and pressing Enter will open the help window.
   

8. You can refer to Glossary for the definition of some words used and Command Summary for a quick overview of the commands. Refer to the Features below for more details of each command.

MacOS

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

   • You can refer to this YouTube video to check your current Java version.
   • If you do not have Java 11, you are recommended to download from here
     
     

2. Download the latest mybookshelf.jar from here.

3. Copy and paste the file to you will use as the home folder for the MyBookshelf app.

   • Open your finder by clicking the finder icon.
   • Navigate to the Downloads folder (Default directory for downloaded files will be the Downloads folder).
   • Copy the downloaded mybookshelf.jar and paste it to the folder you will use as the home folder for the MyBookshelf app.
     
     

4. Access the terminal.

   • Open the Spotlight search window using Command + Space, then type "Terminal".
     
   • Double-click on Terminal in search result.
     
   • Terminal window will appear in a few seconds. Terminal window should look similar to the image below.
     
     
   • If you have issues opening Terminal window, you can refer here
     
     

5. cd into the folder you placed mybookshelf.jar file in, and enter the following command to run the application.
   

   java -jar mybookshelf.jar
   

   • You can refer to the image below.
     Note: Your directory might be different from the image.
     
     
     

6. A window similar to the one below should appear in a few seconds. Notice that the app initialises with some sample data.
   

   
   

7. Type the command into the command box and press Enter to execute it. E.g. typing help and pressing Enter will open the help window.
   

8. You can refer to Glossary for the definition of some words used and Command Summary for a quick overview of the commands. Refer to the Features below for more details of each command.

---

A Quick Walkthrough of MyBookshelf

Overview:

1. Taskbar: Where you can access the File and Help tabs.
2. Command Box: Where you can type in their commands into MyBookshelf.
3. Result Box: This is where MyBookshelf returns the relevant output to the commands you had typed in.
4. Contact List: Contains the list of Library User Information.
5. Library User Information: This is where the particulars of individual library users are displayed at. More details to follow in the next part.
6. Library: Contains the list of Books currently available in your library.
7. Books: Identified by their titles, this is where each book in your library is displayed.

Library User Information:

1. Name: The name of the library user.
2. Index: The sorted position of the library user in the contact list.
3. Merit Score: The merit score associated with the library user. This term is defined below at the Glossary section.
4. Tags: Tags associated with the library user.
5. Phone Number: The phone number of the library user.
6. Address: The home address of the library user.
7. Email: The email address of the library user.
8. User's Book List: The list of books that the library user is currently borrowing from the library.

---

Features

---

Viewing help : help

Shows a message explaining how to access the help page.

Format: help

Adding a library user: add

Adds a new library user to the contact list. Parameters are populated with the library user's personal information.

Format: add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​

Example:

• add n/Kokoro Tsurumaki p/980101296 e/kokoro@bandori.com a/311, Hanasakigawa Ave 2, #08-08

Listing all library users : list

Displays a list of all library users in the contact list.

Format: list

Editing a library user : edit

Edits an existing library user's personal information from the contact list.

Format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…​

• Edits the library user at the specified INDEX. This index refers to the index number of the target library user in the contact list.
• At least one of the optional parameters must be provided.
• Existing values in the contact list will be updated to the input values.
• When editing tags, the existing tags of the library user will be removed i.e adding of tags is not cumulative.
• You can remove all the library user’s tags by typing t/ without specifying any tags after it.

Example:

• edit 2 n/Mashiro Kurata edits the name of the 2nd person to be Mashiro Kurata.

  Before edit:

Edit:

Locating library users by name: find

Finds library users whose names matches any of the given keywords.

Format: find KEYWORD [MORE_KEYWORDS]

• The search (KEYWORD) is case-insensitive. E.g hans will match Hans.
• The order of the keywords does not matter. E.g. Hans Bo will match Bo Hans.
• Only the name is searched.
• Only full words will be matched. E.g. Han will not match Hans.
• All library users matching at least one keyword will be returned (i.e. OR search). E.g. Hans Bo will return Hans Gruber, Bo Yang

Example:

• find kokoro mashiro returns Kokoro Tsurumaki, Mashiro Kurata.

  

Deleting a library user : delete

Deletes the specified library user from the contact list through its index.

Format: delete INDEX

• Deletes the library user at the specified INDEX.
• The index refers to the index number associated with the target library user.

Examples:

• list followed by delete 2 deletes the 2nd user in the contact list.

• find kokoro mashiro followed by delete 2 deletes the 2nd user in the results of the find command.

  Before delete:

Delete:

Add a book to Library : addbook

Adds a book to the library's book list.

Format: addbook b/BOOKTITLE

• Adds a book BOOKTITLE to the library and stores it.

Example:

• addbook b/Tales of Kokoro will add a book titled "Tales of Kokoro" into the library.

Delete a book from Library : delbook

Removes a book from the library's book list.

Format: delbook b/BOOKTITLE

• Remove the first book titled BOOKTITLE from the library.

Example:

• delbook b/Tales of Kokoro will remove a book titled "Tales of Kokoro" from the library.

Borrowing a book: borrow

Library user borrows a book. A book is removed from the library's book list and added to the library user's book list.

Format: borrow INDEX b/BOOKTITLE

• Library user at position INDEX in the contact list borrows a book titled BOOKTITLE.
• This index refers to the index number associated with the target library user in the contact list.
• Borrowing a book decreases the library user's merit score by 1.

Example:

• borrow 1 b/Tales of Kokoro will record the user index 1 borrowing a book titled "Tales of Kokoro".

Returning a book : return

Library user returns a book. A book is removed from the library user's book list and added to the library's book list.

Format: return INDEX b/BOOKTITLE

• Library user at position INDEX in the contact list returns a book titled BOOKTITLE.
• This index refers to the index number associated with the target library user in the contact list.
• Returning a book increases the library user's merit score by 1.

Example:

• return 1 b/Tales of Kokoro returns a book titled "Tales of Kokoro" from the user at index 1.
  

Donating a book : donate

Library user donates a book. A book is added to the library's book list.

Format: donate INDEX b/BOOKTITLE

• Library user at position INDEX in the contact list donates a book titled BOOKTITLE.
• This index refers to the index number associated with the target library user in the contact list.
• Donating a book increases the library user's merit score by 1.

Example:

• donate 1 b/Tales of Kokoro will record user index 1 donating a book titled "Tales of Kokoro".

Set the merit score threshold of the library: limit

Sets the limit of the library such that only users with a merit score more than or equal to the set limit can borrow.

Format: limit [THRESHOLD]

• Sets the limit of the merit score to the specified THRESHOLD.
• The limit refers to the threshold such that any library user with a merit score less the THRESHOLD is not allowed to borrow from the library.
• THRESHOLD is optional. Typing limit without THRESHOLD will display the currently set threshold.
• The default threshold set for libraries is -3.

Examples:

• limit will display the current merit score limit.

• limit -10 will set the merit score limit of the library to -10.

Clearing all library users : clear

Clears all entries of library users from the contact list.

Format: clear

Exiting the program : exit

Exits the program.

Format: exit

Saving the data

MyBookshelf offers an automated data saving feature.

This ensures that any modifications to your library's records will be preserved on your hard disk without necessitating manual intervention.

This functionality simplifies your workflow by automatically saving your progress, enabling seamless continuation from your last session upon reopening the application.

MyBookshelf also focuses on data integrity, guaranteeing that only accurate records are maintained within the system.

Invalid data for available books will be automatically discarded and will not be saved.

Editing the data files

User data in MyBookshelf is saved automatically as a JSON file at [JAR file location]/data/addressbook.json.

Library book data in MyBookshelf is saved automatically as a .txt file at [JAR file location]/data/library.txt.

Experienced users are welcome to make changes to the data directly by editing these data files.

---

Things to Note

1. Every library user starts with a default merit score of 0.
2. ONLY library users with a Merit Score >= Threshold are allowed to borrow books.
3. Library users can borrow multiple books as long as their merit score is above the threshold.
4. The default threshold is set at -3. Use the limit command to set the threshold.
5. edit can only be used to change the library user's personal information. This includes his/her name, phone number, email address, home address and tags. (Not merit score and user's book list).
6. add and edit command DOES NOT support the direct adding and/or editing of merit score or user's book list.
7. add, delete, edit, clear and find commands are for managing users, while addbook, delbook, borrow, donate and return commands are for managing books.
8. The parameter BOOKTITLE is case-sensitive to allow books of similar titles to be differentiated.
9. While there are no restrictions on BOOKTITLE (expect that it cannot be empty), we cannot guarantee the performance when books with titles in other languages are inserted.
10. delbook deletes one book at a time to prevent accidental deletion of all entries with the same book title.
11. We allow entries with the same email and phone number into the contact list as there may be cases where two users share the same contact details. An example would be when a child does not own a mobile phone nor has an email and has to share with his/her parent.
12. Commands that modifies book lists will reference the book using their respective book titles instead of their indexes. This is because the findbook command has not been implemented yet and would make indexing specific books in a large book list unfeasible.
13. We allow delete to remove the library user's book list. This allows for more flexibility in managing the library. If books are returned, the library manager can use the return command to account for the books before deleting the person.
14. Do not use words that start with b/, a/ as part of booktitles and addressess respectively. Tip: If you have a word starting with b/ or a/, you can type a filler character before. E.g. addbook b/Book with .b/ in the title.

---

Troubleshooting

You might see something similar to the image below when the command does not run successfully.

Unable to add/donate/return a book to the library

1. Error message received: Book title cannot be empty!

   • Reason one: You attempted to add/donate/return a book with an empty book title.
     • Resolve this issue by adding character(s) to the BOOKTITLE.
   • Reason two: You attempted to add/donate/return a book which only consists of white space(s).
     • Resolve this issue by altering the BOOKTITLE so it consists at least one non-white space character.

2. Error message received: Multiple values specified for the following single-valued field(s): b/

   • Reason one: You attempted to add/donate/return a book with BOOKTITLE containing " b/". (Note the white space before "b"). In this case, BOOKTITLE is interpreted to be "Please b/ careful".
     • Since b/ is the prefix of Book, MyBookshelf restricts commands with BOOKTITLE containing " b/".
     • Resolve this issue by removing "/" in BOOKTITLE (e.g. Please b careful) or;
     • Resolve this issue by adding a filler character (e.g. ".") in front of "b/" in BOOKTITLE (e.g. Please ./b careful).
   • Reason two: You attempted to add/donate/return multiple books (e.g. addbook b/Book 1 b/Book 2)
     • MyBookshelf restricts adding/donating/returning multiple books in a single command.
     • Resolve this issue by adding/donating/returning the books one by one.

Unable to delete/borrow a book from the library

1. Error message received: Book title cannot be empty!

   • Reason one: You attempted to delete/borrow a book with an empty book title.
     • Resolve this issue by adding character(s) to the BOOKTITLE.
   • Reason two: You attempted to delete/borrow a book which only consists of white space(s).
     • Resolve this issue by altering the BOOKTITLE so it consists at least one non-white space character.

2. Error message received: Multiple values specified for the following single-valued field(s): b/

   • Reason one: You attempted to delete/borrow a book with BOOKTITLE containing " b/" (note the white space before "b"). In this case, BOOKTITLE is interpreted to be "Please b/ careful".
     • Since b/ is the prefix of Book, MyBookshelf restricts commands with BOOKTITLE containing " b/".
     • Resolve this issue by removing "/" in BOOKTITLE (e.g. Please b careful) or;
     • Resolve this issue by adding a filler character (e.g. ".") in front of "b/" in BOOKTITLE (e.g. Please ./b careful).
   • Reason two: You attempted to delete/borrow multiple books (e.g. delbook b/Book 1 b/Book 2).
     • MyBookshelf restricts deleting/borrowing multiple books in a single command.
     • Resolve this issue by deleting/borrowing the books one by one.

3. Error message received: Book: BOOKTITLE is not available in the library.

   • Reason one: You attempted to delete/borrow a book which does not exist in the library.
     • You are not allowed to delete/borrow a non-existing book.
   • Reason two: You attempted to delete/borrow a book, but you misspelt the BOOKTITLE.
     • Please check the spelling of BOOKTITLE of the book you want to delete/borrow and run the command with correct BOOKTITLE.
   • Reason three: You attempted to delete/borrow a book with a BOOKTITLE that does not match any of the BOOKTITLE(s) in the library.
     • Please check if the book with the title BOOKTITLE exists in the library.

Unable to add/edit tags

1. Error message received: Tags names should be alphanumeric.
   • Reason: You attempted to add/edit tags with non-alphanumeric characters (including white space) (e.g. Frequent User).
     • Resolve this by altering the tag you want to add/edit into non-alphanumeric characters only (e.g. FrequentUser).

Library user is unable to donate a book

1. Error message received: The person index provided is invalid.

   • Reason one: You mistyped the index of the library user.
     • Please check the validity of INDEX of the library user and run the command with correct INDEX.
     • Ensure that the INDEX exists in the library user contact list.
   • Reason two: Library user information is not added to the contact list.
     • Resolve this by adding the library user to the contact list first before running the command again.

2. Other error message received:

   • Book title cannot be empty! or Multiple values specified for the following single-valued field(s): b/
     • Please check Unable to add/donate/return a book from the library.

Library user is unable to borrow a book

1. Error message received: The person index provided is invalid.

   • Reason one: You mistyped the index of the library user.
     • Please check the validity of INDEX of the library user and run the command with correct INDEX.
   • Reason two: Library user information is not added to the contact list.
     • Resolve this by adding the library user to the contact list first before running the command again.

2. Error message received: User has insufficient Merit Score.

   • Reason one: Library user's merit score is lower than the threshold of the library.
     • Library user can donate/return book(s) to increase his/her merit score, so that he/she can borrow a book again, OR;
     • Resolve this by lowering the threshold of the library using limit command.

3. Other error message received:

   • Book title cannot be empty! or Multiple values specified for the following single-valued field(s): b/ or Book: BOOKTITLE is not available in the library.
     • Please check Unable to delete/borrow a book from the library.

Library user is unable to return a book

1. Error message received: The person index provided is invalid.

   • Reason one: You mistyped the index of the library user.
     • Please check the validity of INDEX of the library user and run the command with correct INDEX.

2. Error message received: Person is currently not borrowing any books!

   • Reason one: You mistyped the index of the library user.
     • Please confirm the correct INDEX of the library user and run the command with correct INDEX.

3. Error message received: Person does not have this book borrowed currently!

   • Reason one: You mistyped the index of the library user.
     • Please confirm the correct INDEX of the library user and run the command with correct INDEX.
   • Reason two: You misspelt the index of the library user.
     • Please check the spelling of BOOKTITLE of the book the user wants to return and run the command with correct BOOKTITLE.

4. Other error message received:

   • Book title cannot be empty! or Multiple values specified for the following single-valued field(s): b/
     • Please check Unable to add/donate/return a book to the library.

---

Future Features

Introducing more flexibility for clear

1. Will be adding a clearlib command to clear all books currently in your library.
2. Will rename the current clear command to clearuser to clear all the data of library users.
3. Will be adding a clearall command to clear both library book and library user data.

Introducing the findbook command

1. As the number of books in your library increases, you will have to spend more time scrolling through the list to search for a book.
2. The findbook command will allow the library manager quickly check for the existence of a specific book in the library.
3. This will also allow you to explore the use of indexing to run commands that modify the book list instead of having to do so with the lengthy book title.

Introducing the undo and redo commands

1. Even the most meticulous and fastest typists are bound to make some unintended errors.
2. With the undo command, your experience will be enhanced as these mistakes can be reverted with a simple yet effective command.
3. Similarly, the addition of the redo command further improves your experience by allowing users to effortlessly revert back to undone actions, refining the process.

---

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

Q: How do I manually change the merit score of a library user that I have added?
A: Please read the tutorial section on increasing and decreasing merit score.

Q: Can I clear both the contact list and the library at the same time? A: Unfortunately, MyBookshelf currently cannot clear both the contact list and the library at the same time. You can use the clear command to clear the contact list and refer to this section to clear the library.

---

Known issues

MyBookshelf is always a Work-In-Progress as we are constantly refining our application for your needs. Listed below are some of our planned enhancements as well as current limitations, to keep you abreast of the current state of our application.

1. When using multiple screens, if you move the application to a secondary screen, and switch back to 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. Email does not check for presence of top-level domain, such as .com, .net and .org. Refer to the Developer Guide for more information.
3. When a value beyond the range -2147483648 to 2147483647 is used for INDEX and THRESHOLD, the wrong error message is displayed. Will be fixed in the future. Refer to the Developer Guide for more information.
4. There can be different individuals with the same name, but our current implementation does not support this due to our definition of duplicated people. Will be fixed in the future. Refer to the Developer Guide for more information.
5. Duplicated library users can be added with the same name but different capitalisation, due to our definition of duplicated people. Will be fixed in the future. Refer to the Developer Guide for more information.
6. All parameters except INDEX and THRESHOLD do not have a limit to the number of characters. Refer to the Developer Guide for more information.
7. The clear command only clears the library user data. The usage pertaining to this command will be made clearer with the implementation of future features. Refer to the Future Features section above for more information.
8. UI may not display special characters as intended.
9. Some languages may cause the UI to display unexpectedly. For example, Arabic characters will cause the number next to book titles to appear from right to left.

---

Tutorials

How to increase Merit Score of a library user

With the current features, there is no direct command to manually increase the merit score of a library user.

You can use the following steps below to indirectly increase the merit score of an individual library user:

1. Make the library user whose merit score you want to increase donate a placeholder book using donate.
2. Repeat step 1 by the amount you want to increase the library user's merit score by.
3. Delete all the placeholder books that you had added from the library using delbook.

Example: You want to increase the merit score of the third library user by 2.

1. Enter donate 3 b/placeholder book.
2. Enter donate 3 b/placeholder book.
3. Enter delbook b/placeholder book.
4. Enter delbook b/placeholder book.

How to decrease Merit Score of a library user

With the current features, there is no direct command to manually decrease the merit score of a library user.

Method 1: Within MyBookshelf

You can use the following steps below to indirectly increase the merit score of an individual library user:

1. Add placeholder books from the library using addbook.
2. Repeat step 1 by the amount you want to decrease the library user's merit score by.
3. Make the library user whose merit score you want to increase borrow all the placeholder books you added using borrow.

Example: You want to decrease the merit score of the second library user by 2.

1. Enter addbook b/~~~ignore book~~~.
2. Enter addbook b/~~~ignore book~~~.
3. Enter borrow 2 b/~~~ignore book~~~.
4. Enter borrow 2 b/~~~ignore book~~~.

Method 2: Editing the data file

Using this method will not alter the library user's book list. Please read the above section on Editing Data Files before proceeding.

1. Locate the data file at this file location: [JAR file location]/data/addressbook.json.
2. Open the file with any valid application of your choice. For this example, we will open the file with Notepad on Windows.
3. Locate the library user you wish to edit and edit their merit score.

How to clear the whole library

The current clear command is designed to clear the contact list only but there is no command to clear books from the library.

The safest method to clear the library would be to individually delete each book from the library using the delbook command.

You can quickly delete books from the library by directly editing the data file. Please read the above section on Editing Data Files before proceeding.

1. Locate the data file at this file location: [JAR file location]/data/library.txt.
2. Open the file with any text editor of your choice. For this example, we will open the file with Notepad on Windows.
3. Delete all lines after the first line (first line is the number you have set as the limit for your library).

---

Command summary

---

Glossary

1. CLI: Command-Line Interface, a tool you employ to communicate with your operating system via your keyboard.

2. GUI: Graphical User Interface, a graphical interface where users engage with visual elements like icons, buttons, and menus.

3. JSON: JavaScript Object Notation, a text format for storing and transporting data.

4. Parameter: Data that users input into commands.

5. Alphanumeric: A character that is either a letter or a number.

6. Library User: The people that are saved into the contact list of MyBookshelf. Sometimes referred to as "borrowers" or "person".

7. Library Manager: Community Library Managers (CLM) are the people using the MyBookshelf application. CLMs are responsible for adding, storing, and updating the entire library database via MyBookshelf.

8. Contact List: Refers to the list of library users currently stored in the MyBookshelf application. It appears in the left column of the User Interface.

9. Book: Identified by its BOOKTITLE. Appears in both the User's Book List and the Library Book List.

10. User's Book List: Refers to the list of Book(s) currently borrowed by an individual library user.

11. Library Book List: Refers to the list of available Book(s) currently stored in the MyBookshelf application. It appears in the right column of the User Interface. Sometimes referred to as "available books" or simply "library".

12. Command: Instructions given to the application to perform specific tasks.

13. Merit Score: A score associated with each Library User. This score provides an estimate of the number of books a library user can borrow.

14. Limit: Refers to limit set for the library and is synonymous with THRESHOLD, where library users are only allowed to borrow books when their merit score is greater or equal than the limit that has been set.

15. Threshold: The minimum merit score required for a library user to borrow books from the library.

16. Data Saving: The automated feature of the application that preserves modifications to the library's records by saving them on the hard disk.