A1: Command-Line Interaction
Build a command-line application that finds files. The output prints the absolute path of the located files.
Syntax: java FindFiles filetofind [-option parameter1 parameter2 ...]
Using this syntax:
- `FindFiles` is the name of the program that you will create.
- `filetofind` is the full name of the file with the extension, in double-quotes.
- `option' refers to one or more optional arguments that determine how the search is handled.
- `parameters' are arguments that may be required by a particular option.
`filetofind` must be supplied. It must be a valid filename for the system, or a pattern that is being matched using the `-reg` flag. It must be enclosed in double-quotes (see examples below).
Options are specific arguments provided to the program on the that determine how it executes. Options always start with a dash ("-"), and may require zero or more additional arguments to function. Options may appear in any order.
`java FindFiles -help` will display all of the supported options.
Usage: java FindFiles filetofind [-option arg] -help :: print out a help page and exit the program. -r :: execute the command recursively in subfiles. -reg :: treat `filetofind` as a regular expression when searching. -dir [directory] :: find files starting in the specified directory. -ext [ext1,ext2,...] :: find files matching [filetofind] with extensions [ext1, ext2,...].
Most options require one or more additional parameters to operate, which immediately follow the option on the command-line. Parameters cannot start with a dash ("-"), since that symbol is used to designate options. Parameters consist of a string enclosed to double quotes (e.g. "string"). [note: this must be done to ensure that the shell passes the string into your program properly.]
In the case of options that support multiple arguments (described below), they should be separated by a comma. e.g. `java FindFiles img -ext "jpg,png".
- The `-help' `-reg` and `-r` option does not require additional parameters.
- The `-ext' option supports one or more parameters. If more than one parameter is provided, they should be separated by a comma (e.g. -ext "jpg,png,tiff").
- The `-reg` option indicates that the given [filetofind] argument should be treated as a regular expression, not a filename (e.g. FindFile ".*movie.*\.txt" -reg finds all text files that have movie in its name).
- The `-r` option has no argument and indicates that the search will be also done in the sub-directories
- The `-dir' option supports one argument that indicates in which directory the search should start.
Processing Options & Parameters
The following guidelines apply to how you interpret and process command-line arguments.
- The user is expected to provide a minimum number of arguments required to execute the program: the program always needs at least `filetofind` provided to successfully search (exception: -help with no other arguments will display help). If the user doesn't provide the minimum number of arguments, then you should display the help text (above) and exit.
- The default behaviour, if no options are specified, is to search for the file in the currently directory and to NOT recurse into subdirectories.
- Specifying the `-help’ option will cause the program to ignore all other options, display the help text (above), and exit.
- If the user supplies invalid arguments or options, you should report an appropriate error and exit e.g. "'-flyingcows' is an invalid option. Please supply valid options from the following list..."
- If the options are valid but the there are missing or invalid parameters, you should provide a detailed error on how to address it and exit. e.g. `java FindFiles ".*test.*" -reg -ext ' might report "Invalid option: ext requires arguments to be specified."'
- If there is an more than one error in the given command, you should just print the first error, then print the help and exit.
- When performing a file search, you should echo the operations as you perform them, so that the user has immediate feedback (e.g. "looking for file `f1' in `myDirectory`). For this assignment, echoing the operation that was performed is sufficient feedback.
java FindFiles "test.txt"
java FindFiles "test.txt" -r -dir "./myDirectory" ⇒ find the files named 'test.text' in myDirectory folder and all its sub folders.
java FindFiles ".*bla.*" -reg ⇒ find all the files that have bla in their name.
java FindFiles ".*" -ext "txt,java" -reg ⇒ find all the files with txt or java extensions
Invalid examples, which produce errors:
java FindFiles -ext "txt,java" // no filename to find provided
java FindFiles "test.txt" -dir // no directory argument provided
- Your main class should be named `FindFiles' and reside, with a main() method, in a file named `FindFiles.java'.
- Your code must be written in Java 11. You are required to submit all source code and project files.
- You are not required to use IntelliJ, but if you do so, you should IntelliJ 2020.2 or later with the appropriate plugins.
- You may use any classes from the Java 11 JDK, and samples provided in the public repo. You cannot use any other source code without permission from the instructor.
- Your program should be tested using the bash shell under macOS or Linux. If you run Windows, you should ssh into the student environment and test there [ed note: there are issues with bash on Windows, so please test under Unix].
Your submission should include:
- All files required to build your project. This will likely be a single class named "FindFiles.java".
- A `readme.md' file that includes, at a minimum, your name, student number, the version of Java that you used (from `java -version'), and the operating system where you tested. If the TA needs to know anything else to run your assignment (e.g. undocumented hotkeys), include them in this file. For example:
Jeff Avery 12345678 j2avery openjdk version "11.0.2" 2019-04-16 macOS 10.14.6 (MacBook Pro 2017)
You should submit your project in your GitLab repository for this course (and push to the server) by the deadline.
- If you haven't already done so, clone your repository. See the Assignments page for specific instructions.
- Make sure your project is in the
a1folder in your repo. It should look like this:
a1/ ├── FindFiles.java └── readme.md
- Save, commit and push your project to the remote repository. See the Assignments page for specific instructions.
- (Optional) Login to
git.uwaterloo.caand make sure that you can see your project contents through the web interface! This is a helpful way to double-check that you've committed everything properly.
To grade your assignments, TAs will run commands and check the output. e.g. $ javac FindFiles.java $ java FindFiles test1.txt // read output and assign grade
Your submission will be assessed roughly as follows:
- Complete submission including project file and `readme'. Code compiles and runs.
- Correctly parse and identify options and arguments.
- Provide feeback on incorrect options and arguments.
- Combine multiple options in one command.
- Find files correctly using the operations above.
1.0 Aug 18, 2020. Initial draft.
1.1 Aug 26, 2020. Fixed a couple of typos. Clarified help text.
1.2 Sept 17, 2020. Addressed feedback from Q&A Session. Removed invalid 'makefile' reference. Added section on running/testing.
1.3 Sept 23, 2020. Removed Gradle requirement.