-
Notifications
You must be signed in to change notification settings - Fork 1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
150 additions
and
131 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,5 +18,4 @@ hs_err_pid* | |
|
|
||
| # Temp files used for testing | ||
| test/actual.txt | ||
| test/*.bat | ||
| test/*.sh | ||
| test/localrun.bat | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,9 +4,151 @@ | |
| the main programming language. | ||
| * It provides a reasonably well-written code example that is significantly bigger than what students | ||
| usually write in data structure modules. | ||
| * It can be used to achieve a number of beginner-level learning outcomes without running into the complications | ||
| of OOP or GUI programmings. | ||
| * It can be used to achieve a number of beginner-level [learning outcomes](#learning-outcomes) without | ||
| running into the complications of OOP or GUI programmings. | ||
|
|
||
| **Table of Contents** | ||
| * [User guide](#user-guide) | ||
| * [Developer guide](#developer-guide) | ||
| * [Learning outcomes](#learning-outcomes) | ||
| * [Contributors](#contributors) | ||
| * [Contact us](#contact-us) | ||
|
|
||
| ----------------------------------------------------------------------------------------------------- | ||
| # User guide | ||
|
|
||
| This product is not meant for end-users and therefore there is no user-friendly installer. | ||
| Please refer to the [Setting up](#setting-up) section to learn how to set up the project. | ||
|
|
||
| #### Starting the program | ||
|
|
||
| **Using Eclipse** | ||
|
|
||
| 1. Find the project in the `Project Explorer` or `Package Explorer` (usually located at the left side) | ||
| 2. Right click on the project | ||
| 3. Click `Run As` > `Java Application` | ||
| 4. The program now should run on the `Console` (usually located at the bottom side) | ||
| 5. Now you can interact with the program through the `Console` | ||
|
|
||
| **Using Command Line** | ||
|
|
||
| 1. Open the `Terminal`/`Command Prompt` | ||
| 2. `cd` into the project's `bin` directory | ||
| 3. Type `java seedu.addressbook.AddressBook`, then <kbd>Enter</kbd> to execute | ||
| 4. Command above enables you to interact with the program through the CLI | ||
|
|
||
| #### Viewing help : `help` | ||
| Format: `help` | ||
| > Help is also shown if you enter an incorrect command e.g. `abcd` | ||
| #### Adding a person: `add` | ||
| > Adds a person to the address book | ||
| Format: `add NAME p/PHONE_NUMBER e/EMAIL` | ||
| >Words in `UPPER_CASE` are the parameters<br> | ||
| Phone number and email can be in any order but the name must come first. | ||
|
|
||
| Examples: | ||
| * `add John Doe p/98765432 e/[email protected]` | ||
| * `add Betsy Crowe e/[email protected] p/1234567 ` | ||
|
|
||
| #### Listing all persons : `list` | ||
|
|
||
| > Shows a list of persons, as an indexed list, in the order they were added to the address book, | ||
| oldest first. | ||
|
|
||
| Format: `list` | ||
|
|
||
| #### Finding a person by keyword `find` | ||
| > Finds persons that match given keywords | ||
| Format: `find KEYWORD [MORE_KEYWORDS]` | ||
| > The search is case sensitive, the order of the keywords does not matter, only the name is searched, | ||
| and persons matching at least one keyword will be returned (i.e. `OR` search). | ||
|
|
||
| Examples: | ||
| * `find John` | ||
| > Returns `John Doe` but not `john` | ||
| * `find Betsy Tim John` | ||
| > Returns Any person having names `Betsy`, `Tim`, or `John` | ||
| #### Deleting a person : `delete` | ||
|
|
||
| Format: `delete INDEX` | ||
| > Deletes the person at the specified `INDEX`. | ||
| The index refers to the index numbers shown in the most recent listing. | ||
|
|
||
| Examples: | ||
| * `list`<br> | ||
| `delete 2` | ||
| > Deletes the 2nd person in the address book. | ||
| * `find Betsy` <br> | ||
| `delete 1` | ||
| > Deletes the 1st person in the results of the `find` command. | ||
| #### Clearing all entries : `clear` | ||
| > Clears all entries from the address book. | ||
| Format: `clear` | ||
|
|
||
| #### Exiting the program : `exit` | ||
| Format: `exit` | ||
|
|
||
|
|
||
| #### Saving the data | ||
| Address book data are saved in the hard disk automatically after any command that changes the data. | ||
| There is no need to save manually. | ||
|
|
||
| #### Changing the save location | ||
| Address book data are saved in a file called `addressbook.txt` in the project root folder. | ||
| You can change the location by specifying the file path as a program argument. | ||
|
|
||
| Examples: | ||
| * `java seedu.addressbook.AddressBook mydata.txt` | ||
|
|
||
| > The file name must end in `.txt` for it to be acceptable to the program. | ||
| > When running the program inside Eclipse, there is a way to set command line parameters | ||
| before running the program. | ||
|
|
||
| ----------------------------------------------------------------------------------------------------- | ||
| # Developer guide | ||
|
|
||
| ## Setting up | ||
|
|
||
| **Prerequisites** | ||
|
|
||
| * JDK 8 or later | ||
| * Eclipse IDE | ||
|
|
||
| **Importing the project into Eclipse** | ||
|
|
||
| 1. Open Eclipse | ||
| 2. Click `File` > `Import` | ||
| 3. Click `General` > `Existing Projects into Workspace` > `Next` | ||
| 4. Click `Browse`, then locate the project's directory | ||
| 5. Click `Finish` | ||
|
|
||
| ## Testing | ||
|
|
||
| **Windows** | ||
| 1. Open a DOS window in the `test` folder | ||
| 2. Run the `runtests.bat` script | ||
| 3. If the script reports that there is no difference between `actual.txt` and `expected.txt`, | ||
| the test has passed. | ||
|
|
||
| **Mac/Unix/Linux** | ||
| Create a script similar to the windows version. | ||
| You can use the `diff` command in place of the `FC` command. | ||
|
|
||
| **Troubleshooting tests** | ||
|
|
||
| * Differences between line endings | ||
| * Diffing the two files | ||
| * Failure during first run | ||
|
|
||
| ----------------------------------------------------------------------------------------------------- | ||
| # Learning outcomes | ||
| Here are the things a student should be able to do after studying this code and completing the | ||
| corresponding exercises. | ||
|
|
@@ -161,139 +303,14 @@ See if you can find where the code contradicts best practices mentioned | |
| programmer (but a very bad programmer :-). | ||
| * In particular, inlining methods can worsen the code quality fast. | ||
|
|
||
| # Setting up | ||
| ### Prerequisites | ||
| * JDK 8 or later | ||
| * Eclipse IDE | ||
|
|
||
| ### Importing the project into Eclipse | ||
| 1. Open Eclipse | ||
| 2. Click `File` > `Import` | ||
| 3. Click `General` > `Existing Projects into Workspace` > `Next` | ||
| 4. Click `Browse`, then locate the project's directory | ||
| 5. Click `Finish` | ||
|
|
||
| # Running the program | ||
| ### Using Eclipse | ||
| 1. Find the project in the `Project Explorer` or `Package Explorer` (usually located at the left side) | ||
| 2. Right click on the project | ||
| 3. Click `Run As` > `Java Application` | ||
| 4. The program now should run on the `Console` (usually located at the bottom side) | ||
| 5. Now you can interact with the program through the `Console` | ||
|
|
||
| ### Using Command Line | ||
| 1. Open the `Terminal`/`Command Prompt` | ||
| 2. `cd` into the project's `bin` directory | ||
| 3. Type `java seedu.addressbook.AddressBook`, then <kbd>Enter</kbd> to execute | ||
| 4. Command above enables you to interact with the program through the CLI | ||
|
|
||
| ### Usage | ||
|
|
||
| ##### Viewing help : `help` | ||
| Format: `help` | ||
| > Help is also shown if you enter an incorrect command e.g. `abcd` | ||
| ##### Adding a person: `add` | ||
| > Adds a person to the address book | ||
| Format: `add NAME p/PHONE_NUMBER e/EMAIL` | ||
| >Words in `UPPER_CASE` are the parameters<br> | ||
| Phone number and email can be in any order but the name must come first. | ||
|
|
||
| Examples: | ||
| * `add John Doe p/98765432 e/[email protected]` | ||
| * `add Betsy Crowe e/[email protected] p/1234567 ` | ||
|
|
||
| ##### Listing all persons : `list` | ||
|
|
||
| > Shows a list of persons, as an indexed list, in the order they were added to the address book, | ||
| oldest first. | ||
|
|
||
| Format: `list` | ||
|
|
||
| ##### Finding a person by keyword `find` | ||
| > Finds persons that match given keywords | ||
| Format: `find KEYWORD [MORE_KEYWORDS]` | ||
| > The search is case sensitive, the order of the keywords does not matter, only the name is searched, | ||
| and persons matching at least one keyword will be returned (i.e. `OR` search). | ||
|
|
||
| Examples: | ||
| * `find John` | ||
| > Returns `John Doe` but not `john` | ||
| * `find Betsy Tim John` | ||
| > Returns Any person having names `Betsy`, `Tim`, or `John` | ||
| ##### Deleting a person : `delete` | ||
|
|
||
| Format: `delete INDEX` | ||
| > Deletes the person at the specified `INDEX`. | ||
| The index refers to the index numbers shown in the most recent listing. | ||
|
|
||
| Examples: | ||
| * `list`<br> | ||
| `delete 2` | ||
| > Deletes the 2nd person in the address book. | ||
| * `find Betsy` <br> | ||
| `delete 1` | ||
| > Deletes the 1st person in the results of the `find` command. | ||
| ##### Clearing all entries : `clear` | ||
| > Clears all entries from the address book. | ||
| Format: `clear` | ||
|
|
||
| ##### Exiting the program : `exit` | ||
| Format: `exit` | ||
|
|
||
|
|
||
| ##### Saving the data in the hard disk | ||
| Address book data are saved in the hard disk automatically after any command that changes the data. | ||
| There is no need to save manually. | ||
|
|
||
| ##### Changing the save location | ||
| Address book data are saved in a file called `addressbook.txt` in the project root folder. | ||
| You can change the location by specifying the file path as a program argument. | ||
|
|
||
| Examples: | ||
| * `java seedu.addressbook.AddressBook mydata.txt` | ||
|
|
||
| > The file name must end in `.txt` for it to be acceptable to the program. | ||
| > When running the program inside Eclipse, there is a way to set command line parameters | ||
| before running the program. | ||
|
|
||
| # Testing | ||
| Make sure the file `storage.txt` exists in the working directory. | ||
|
|
||
| 1. Open `Terminal` for Unix or `Command Prompt` for Windows | ||
| 2. Move to the project's bin directory, using `cd <project_path>/bin` in Unix and `dir <project_path>/bin` in Windows | ||
| 3. Type `java nus.todobuddy.ToDoBuddy storageFilename.txt < ../test/input.txt > ../test/output.txt`, | ||
| then `Enter` to execute | ||
| 4. Command above will tell the program to save the data in `storageFilename.txt`, | ||
| then run the command provided from `../testing/input.txt`. Finally, it will write the output to `../testing/output.txt` | ||
|
|
||
| Sample Windows batch file to automate testing: | ||
| ```sh | ||
| javac ..\src\nus\cs2103\addressbook\Addressbook.java -d ..\bin | ||
| java -classpath ..\bin seedu.addressbook.AddressBook < input.txt > actual.txt | ||
| FC actual.txt expected.txt | ||
| ``` | ||
| Put the code above into a file `test\test.bat`, | ||
| open a DOS window in the `test` folder, | ||
| and run the `call test.bat` command. | ||
|
|
||
| Troubleshooting test results: | ||
| * differences between line endings | ||
| * diffing the two files | ||
| * failure during first run | ||
|
|
||
| ----------------------------------------------------------------------------------------------------- | ||
| # Contributors | ||
| * [Jeffry Hartanto](http://github.com/jeffryhartanto) : Created a ToDo app that was used as the basis for this code. | ||
| * [Leow Yijin](http://github.com/yijinl) : Main developer for the first version of the AddressBook-level1 | ||
| * [Damith C. Rajapakse](http://www.comp.nus.edu.sg/~damithch) : Project Advisor | ||
|
|
||
| ----------------------------------------------------------------------------------------------------- | ||
| # Contact us | ||
| * **Bug reports, Suggestions** : Post in our [issue tracker](https://github.com/se-edu/addressbook-level1/issues) | ||
| if you noticed bugs or have suggestions on how to improve. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| javac ..\src\seedu\addressbook\Addressbook.java -d ..\bin | ||
| java -classpath ..\bin seedu.addressbook.AddressBook < input.txt > actual.txt | ||
| FC actual.txt expected.txt |