PROJECT: BookSquirrel

Overview

BookSquirrel is for those who want to keep a record of books they’ve read. More importantly, BookSquirrel 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, BookSquirrel can get your note management tasks done faster than traditional GUI apps.

Summary of contributions

  • Major enhancement: add the ListBook feature. #42 #53 #66

    • What it does: allows the user to search the book by using keywords of book name, author name, tags or ratings of books.

    • Justification: This feature help the user quickly find the books that satisfy certain criteria.

    • Highlights: This feature is critical for testing as it is used to display the books. As it provides the users a quick and easy method to find books in the bookshelf, it also makes the product much more user friendly especially when the bookshelf contains many books.

  • Major enhancement: modify the storage part of the app. Pull request #70, #85

    • What it does: loads data into the app at runtime and saves data when the program exits.

    • Justification: This part is critical for data saving and updating.

    • Highlights: This part is critical for the functionality of the product, since it guarantees the consistency between the saved data and the attempted modification of the bookshelf.

  • Minor enhancement: added the Summary feature. #94 #98

    • What it does: gives a brief summary of books in the book shelf.

    • Justification: This feature provides the user an overview of what he/she has read.

    • Highlights: This feature makes the app more interesting. It helps users to have a quick overview of all books have been stored.

  • Code contributed: [Functional code]

  • Other contributions:

    • Project management:

      • Create the organization

    • Enhancements to existing features:

      • Make the storage part compatible with the app after the reviews part is added. (Pull request #70, #85)

      • Write some parts in UI to work with the current version. (Pull request #42)

    • Documentation:

      • Update diagrams in the Developer Guide. (Pull request #107, #99, #74)

      • Update the User Guide and the Developer Guide: (Pull request #107)

    • Data Management:

      • Write some sample data for testing and initialization

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Listing book entries : listBook

Shows a list of all book entries, with the specified keywords of bookname, author, tag and rating.
Format: listBook [n/BOOKNAME] [a/AUTHOR] [t/TAG] [m/RATING]

  • If no parameters are given, the command will give the complete list of all the books

  • Keywords should be single word, or will be rejected as an invalid input.

  • Keywords for every type should comply with the constraint enforced for this type.

  • Prefixes should be provided for every keyword. For example, n/Madame Ham will not be recognized as two separate book name keywords 'Madame' and 'Ham', but will be read as a whole.

  • The search is case insensitive. e.g hans will match Hans

  • There are no limits of the number of keywords of one type.

  • The order of the keywords does not matter. e.g. Alice Wonderland will match Wonderland Alice

  • Only full words will be matched e.g. Han will not match Hans

  • Only books match at least one criteria for all kinds will be returned. For example, if two book name keywords and two tag keywords are provided, book that matches at least one name keyword and at least one tag keyword will be displayed. Books contain only one name keyword provided and no tag keyword provided will not be selected.

  • For book name searching, books matching at least one keyword will be returned. e.g. Alice will return Alice in Wonderland, the Westminster Alice

  • For author name searching, books whose author name matching at least one keyword will be returned. e.g. James will return books whose author name is Henry James

  • For tag searching, books containing at least one tag given will be returned. e.g. computer will return Computer Organisation, Computer Networks

  • For rating search, books whose rating is included will be returned.

Examples:

  • listBook t/textbook m/5
    Books with the rating 5 or the tag textbook will be displayed.

  • listBook n/CS2104T t/textbook
    Books whose name contains the keyword CS2104T or tags include textbook will be displayed.

  • listBook m/5 m/6
    Books whose rating is 5 or 6 wil be displayed.

  • listBook n/Madame n/Prejudice m/6 m/8
    Madame Bovary and Pride and Prejudice will be displayed ListBookScreenShot

Providing statistics of all the books read : summary

Generate a summary of all the books read so far.
Format: summary

  • The summary will list out how many books you’ve read.

  • The summary will also list out authors appear more than once on your bookshelf.

  • The summary will also list out books of the highest score.

  • The summary will also list out tags appear more than once on your bookshelf.

Examples:

  • summary An example of a summary You’ve read 9 books. You prefer books by Erika Leonard, as you’ve read: Fifty Shades of Grey, Fifty Shades Darker. Book(s) receive a rating of 10 from you: To Kill a Mocking Bird. You prefer books that you labeled as fantasy(including The Hunger Games, Life of Pi).

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Storage component

StorageClassDiagram
Figure 1. Structure of the Storage Component

API : Storage.java

The Storage component,

  • can save UserPref objects in JSON format and read it back.

  • can save the BookShelf data in JSON format and read it back.

  • both the data of books and reviews will be saved.

  • users are not supposed to touch the data file (the file inside the data folder) directly. If the user insists on doing so, the data might be corrupted.

  • users are not supposed to add data files into the app manually. If the user accidentally corrupts the data file, he or she may have to reinstall the app and all data will get lost.

  • developers can edit the data file for the purpose of testing.

ListBook feature

Current Implementation

The current version of listBook command works to help the user to search books that satisfy certain criteria. The user can look for books by giving keywords of book name, author, tag or rating.

This would be handy when there are many books on the bookshelf. It also makes the app more user-friendly as the user sometimes cannot remember the exact full name of a book but only know a few things about the book desired.

Compared to the list command in the address book app, our listBookCommand is an implementation of the combination of list and find and even more functionally helpful, as it accepts more filtering criteria than the original command does.

Given below is an example usage and how listBook feature behaves at each step.

Step 1. The user launches the application for the first time. The VersionedBookShelf will be initialized with the initial bookshelf state, and the currentStatePointer pointing to that single bookshelf state.

Step 2. The user executes listBook n/Life.

Step 3. The ListBookCommandParser parses this command. It will first create some predicates according to the input and then use theses predicates to create a ListBookCommand. The exception will be thrown if the command is invalid. The command is created by the logic manager as follows.

listBookCommandLogic

Step 4. The ListBookCommand will be executed. The command checks all the books on the BookShelf, selects out books whose name contain Life based on BookNameContainsKeywordPredicate.

The sequence diagram of the whole process is as follows.

listBookSqDiagram

Design Considerations

Aspect: How to select books.

  • Alternative 1 (current choice): Only books match all criteria provided will be selected. For example, if the user gives 2 book name keywords and 2 ratings, only books matching at least 1 name keyword and at least 1 rating will be selected. Books match 1 name keyword but no ratings will not be considered.

    • Pros: Easy to test and manage.

    • Cons: Such search techniques may fail to provide the user with enough information.

  • Alternative 2: Books that match at least one criteria will be selected. For example, if the user gives 2 book name keywords and 2 ratings, books that match 1 name keyword but no ratings will still be selected.

    • Pros: More likely to provide the user with the book that the user is looking for.

    • Cons: Such a design also fails to narrow down search results when the user is providing more keywords for the targeted book. Besides, it’s hard to test and manage.

Summary feature

Current Implementation

The summary feature is a command works to summarize the books on the bookshelf. The user can have an overview of what he/she has read.

Given below is an example of usage and how the summary feature works.

Step 1. The user launches the application for the first time. The VersionedBookShelf will be initialized with the initial bookshelf state, and the currentStatePointer pointing to that single bookshelf state.

Step 2. The user executes summary

Step 3. The SummaryCommandParser parses this command.

Step 4. The SummaryCommandParser`returns an `SummaryCommand. The exception will be thrown if the command is invalid.

Step 5. The SummaryCommand executes. The command will traverse all books in the bookshelf, checks, if there are authors or tags, appear more than once and give relative details. The command will also return the highest rating of books on the bookshelf.

The summary command creates a summary as follows:

SummaryActivity

Design Consideration

Aspect: Component to fetch the data

  • Alternative 1 (current choice): Model manager is in charge of data processing, then returns the result to the command.

    • Pros: This prevents the command from accessing data managed by the model manager, thus independence of different parts is guaranteed.

    • Cons: More methods are introduced into the model manager. To include more information in the summary, not only the summary command should be modified, but also more information query methodS should be added in The Model. This somehow break the abstraction.

  • Alternative 2: Model manager passes the whole bookshelf to the command, then command process the data according to this list.

    • Pros: More flexible as the command can extract any information it desires. Whenever we want the summary to include more information, we just directly fetch the data from the copy of the bookshelf.

    • Cons: This approach is unsafe and may lead to more bugs as it violates the principle of independence.

  • Alternative 3: Model manager creates a list of the copies of the books in the bookshelf and passes it to the command.

    • Pros: More flexible as the command can read whatever information desired, thus keeps the bookshelf safe from any unintended modification.

    • Cons: The manager no longer has control over what information is accessible to the command, thus may still expose some sensitive information. Besides, making a copy of the whole list is not practical when there are many books in the bookshelf.