Skip to content

UserGuide.adoc

Latest commit

 

History

History
397 lines (298 loc) · 15.3 KB

UserGuide.adoc

File metadata and controls

397 lines (298 loc) · 15.3 KB

BookSquirrel - User Guide

By: Team W11-04 Since: Feb 2019 Licence: MIT

1. Introduction

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 book management tasks done faster than traditional GUI apps. Interested? Jump to the Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

  1. Ensure you have Java version 9 or later installed in your Computer.

  2. Download the latest bookSquirrel.jar here.

  3. Copy the file to the folder you want to use as the home folder for your application.

  4. Double-click the file to start the app. The main window should appear in a few seconds, as shown in the screenshot below.

    Ui

  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:

    • addBookn/Alice in Wonderland a/Lewis Carroll m/5 t/fantasy t/fairy tale : adds a book named Alice in Wonderland to the record. The book is written by Lewis Carroll, with a rating of 5, and labeled with tags fairy tale and fantasy.

    • exit : exits the app

  7. Refer to Section 3, “Features” for details of each command.

3. Features

Command Format

  • The total length of user input should not exceed 500 characters (space included).

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in addBook n/NAME, NAME is a parameter which can be used as addBook n/Book.

  • Words in UPPER_CASE without brackets are the parameters that should only be supplied once e.g. in addBook n/NAME, NAME is a parameter which should only appear once in user input, addBook n/John Doe n/Alice is not allowed.

  • Items in square brackets are optional (can be supplied once or not at all) e.g n/NAME [a/AUTHOR] can be used as n/Alice in Wonderland a/Jack or as n/Alice in Wonderland.

  • 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/fantasy, t/fantasy t/textbook etc.

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

  • Book name, review title and review content should only contain alphanumeric characters, space, *, ,, ., ?, ', (, ) and &.

  • Author and tag should only contain alphanumeric characters and spaces.

  • The Book name and author should not exceed 50 characters (space included).

  • Review title should not exceed 50 characters (space included).

  • Review content should not exceed 400 characters (space included).

  • Rating should be an integer from 0 to 10 inclusive and the input should be 1 or 2 digit number.

  • Tags should not exceed 20 characters (space included).

3.1. Book Commands

3.1.1. Adding a book: addBook

Adds a book to the Bookshelf
Format: addBook n/BOOKNAME a/author m/RATING [t/TAG]…​

Examples:

  • addBook n/Alice in Wonderland a/Lewis Carroll m/5 t/fantasy t/fairy tale
    Adds a book named Alice in Wonderland to the record. The book is written by Lewis Carroll, rated 5 stars, and labeled with tags ‘fantasy’ and ‘fairy tale’.

  • addBook n/Structure and Interpretation of Computer Programs a/Jerry Sussman m/4 t/textbook
    Adds a book named Structure and Interpretation of Computer Programs to the record. The book is written by Jerry Sussman, rated 4 stars, and labeled with tag ‘textbook’.

  • The book name is case sensitive

  • Two books with same book name are considered the same book

  • Trying to add a book which is already present on the bookshelf will result in duplicate book error, and the addBook command will fail

  • Take a look at [Command-Format] to see the valid format for each parameter

3.1.2. Editing book entry : editBook

Edits an existing book entry (eg. edit the book name, rating, author or tag).
Format: editBook INDEX [n/BOOKNAME] [a/AUTHOR] [m/RATING] [t/TAG]…​

  • Edit the book at the specified INDEX. The index refers to the index number shown in the displayed Bookshelf. The index must be a positive integer 1, 2, 3, …​

  • Edit a book with a new name that already exists on the bookshelf is not allowed

  • At least one of the optional fields must be provided.

  • Take a look at [Command Format] to see the valid format for each parameter

  • Existing values will be updated to the input values

  • When editing tags, the existing tags of the book will be removed i.e adding of tags is not cumulative

  • You can remove all the book’s tags by typing t/ without specifying any tags after it

Examples:

  • editBook 1 n/Alice in Wonderland a/some author t/some tag
    Change the name, author, tag of the first book to Alice in Wonderland, some author, some tag.

  • editBook 2 t/
    Clear all the existing tags of the second book in the result list.

3.1.3. Deleting a book : deleteBook

Deletes the specified book from the Bookshelf.
Format: deleteBook INDEX

  • Deletes the book of the specified INDEX.

  • All the reviews of the deleted book will also be deleted.

  • The index refers to the index number shown in the displayed Bookshelf.

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

Examples:

  • listBook n/Computer Security
    deleteBook 1
    Deletes the 1st book in the results of the listBook command.

3.1.4. 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

3.1.5. Sort books command : sortBook

sort booklist in specify order.
Format: sortBook st/TYPE…​ [o/ORDER] [o1/ORDER] [o2/ORDER] [o3/ORDER]

  • TYPE can only be either AUTHOR, NAME or RATING.

  • Able to sort more than one TYPE by writing down more than one TYPE after the sortBook.

  • ORDER can be either ASC(ascending) and DES(descending).

  • Omit o/ORDER, it will sort in ASC(ascending).

  • o1, o2, o3 is corresponding order for each TYPE that specify in front.

  • o/ORDER is the order for all TYPEs, it will overwrite order if both o and o1 appear at the same time.

  • TYPE and ORDER are all case-insensitive.

Examples:

  • sortBook st/name sort bookList by book name in ascending order.

  • sortBook st/rating st/name o1/des sort bookList by the rating of the book in descending order and if they having the same rating it will sort them by book name in ascending order.

  • sortBook st/author st/rating o/des o2/asc sort bookList by the author in descending order and if they having the same rating it will sort them by rating in des order. (o/des overwrite o2/asc)

  • sortBook st/rating st/author st/name o1/des o3/asc sort bookList by rating in descending order and since the o2 order is not specified, if the same rating it will consider author as ascending order.

3.2. Review Commands

3.2.1. Adding a book review: addReview

Adds a book review to a certain book in the Bookshelf

Format: addReview n/BOOKNAME rt/REVIEW TITLE r/REVIEW MESSAGE

Examples:

  • addReview n/Alice in Wonderland rt/An interesting child book r/While Lewis Carroll purists will scoff at the aging of his curious young protagonist, most movie audiences will enjoy this colorful world.

  • addReview n/Structure and Interpretation of Computer Programs rt/Computing Bible r/A very difficult book:(

  • The book has specified BOOKNAME must already exist in the BookShelf.

  • BOOKNAME and REVIEW TITLE should not contain more than 50 characters.

  • REVIEW MESSAGE should not contain more than 400 characters.

3.2.2. Deleting a book review: deleteReview

Deletes the review of the specified index number from the review list.
Format: deleteReview INDEX

Example:

  • deleteReview 1

  • Deletes the review of the specified INDEX.

  • The index refers to the index number shown in the displayed review list.

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

3.2.3. Listing all book reviews: listAllReviews

Lists all the reviews in the BookShelf.
Format: listAllReviews

3.2.4. Listing book reviews of a certain book : listReview

Lists the reviews of the book identified by the index number used in the displayed Bookshelf.
Format: listReview INDEX

Example:

  • listReview 1

  • Lists the review of the book at the specified INDEX.

  • The index refers to the index number shown in the displayed Bookshelf.

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

3.2.5. Selecting an review: selectReview

Selects a review.

Format: selectReview INDEX

Example:

  • selectReview 1

  • Selects the review of the specified INDEX.

  • The complete review will be displayed at the rightmost panel.

  • The index refers to the index number shown in the displayed review list.

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

3.3. System Commands

3.3.1. Viewing help : help

Offer a guide of all possible commands.
Format: help

3.3.2. Listing entered commands : history

Lists all the commands that you have entered in reverse chronological order.
Format: history

ℹ️

Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.

3.3.3. Undoing previous command : undo

Restores the records to the state before the previous undoable command was executed.
Format: undo

ℹ️

Undoable commands: those commands that modify the records content (addBook, addReview, deleteBook, deleteReview, editBook, sortBook and clear).

Examples:

  • listBook n/Alice
    deleteBook 1
    undo (reverses the deleteBook 1 command)

  • sortBook st/rating
    undo (reverses the sortBook st/rating command)

  • listBook a/James
    undo
    The undo command fails as there are no undoable commands executed previously.

  • deleteBook 1
    clear
    undo (reverses the clear command)
    undo (reverses the deleteBook 1 command)

3.3.4. Redoing the previously undone command : redo

Reverses the most recent undo command.
Format: redo

Examples:

  • deleteBook 1
    undo (reverses the deleteBook 1 command)
    redo (reapplies the deleteBook 1 command)

  • deleteBook 1
    redo
    The redo command fails as there are no undo commands executed previously.

3.3.5. 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).

3.3.6. Clearing all entries : clear

Clears all entries from the bookshelf.
Format: clear

3.3.7. Exiting the program : exit

Exits the program.
Format: exit

3.3.8. Saving the data

Book review data are saved in the hard disk automatically after any command that changes the data.
There is no need to save manually.

4. 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 BookSquirrel folder.

5. Command Summary

5.1. Book Commands

  • AddBook addBook n/BOOKNAME a/author m/RATING(0-10) [t/TAG]…
    e.g. addBook n/Alice in Wonderland a/Lewis Carroll m/5 t/fantasy t/textbook

  • EditBook : editBook INDEX [n/BOOKNAME] [a/AUTHOR] [m/RATING]…​
    e.g. editBook 1 n/Alice in Wonderland a/some author

  • DeleteBook : deleteBook INDEX
    e.g. deleteBook 4

  • ListBook : listBook [n/NAME] [t/TAG] [m/RATING] [a/Author]
    e.g. listBook t/textbook m/5

  • sortBook : sortBook st/TYPE o/ORDER
    e.g. sortBook st/AUTHOR o/ASC

5.2. Review Commands

  • AddReview addReview n/BOOKNAME r/review
    e.g. addReview n/Alice in Wonderland r/While Lewis Carroll purists will scoff at the aging of his curious young protagonist, most movie audiences will enjoy this colorful world.

  • DeleteReview : deleteReview INDEX
    eg. deleteReview 1

  • ListAllReviews : listAllReviews
    e.g. listAllReviews

  • ListReview : listReview INDEX
    e.g. listReview 1

  • SelectReview : selectReview INDEX
    e.g. selectReview 1

5.3. System Commands

  • Help : help

  • History : history

  • Undo : undo

  • Redo : redo

  • Summary : summary

  • Clear : clear

  • Exit : exit