CompSci 308 : Spring 2024

SLogo: Detailed Specifications

Basic Functional Requirements

Your project team will implement multiple views on the Model and multiple commands, some simple and some very complex. Start with as simple an implementation as possible of all parts, encapsulated by a design that considers how to accommodate one example from each variation, to ensure that when you "fill in" a more complete and complex implementation you do not need to change the APIs. Thus it can be helpful to start by assuming an abstraction will be useful (even if you can only see one possible subclass) to minimize the exposure of mutable concrete classes.

Below is a table of the project’s basic functionality, following the format in the Functional Requirements Glossary (which describes the difference between Core, Variation, and Extension requirements). You are expected to implement all Core requirements, and only enough Variation and Extension requirements of your choice to validate you are making good choices to meet the Design Specifications.

SLogo Program Commands

Your program must implement these text commands that use the simplified syntax and must be able to properly run these example programs.

User Interface

The exact User Interface for a SLogo IDE is up to your team to decide.

It should support at least all of the following:

IDE Display

ID	Name	Priority	Description
`SLOGO-56`	Splash Screen	Core	When the program starts, provide a Splash Screen that: displays the program's name a mechanism to select a language (see `SLOGO-69`) and color theme (see `SLOGO-73`) a mechanism to start a new session (see `SLOGO-57`) or load a saved session (see `SLOGO-67`) any other information or configuration that you think will be helpful
`SLOGO-57`	New IDE Session	Core	When a new IDE session opens, the user is presented with no initial drawings, command history, user defined variables, or user defined commands. The turtle starts at the coordinate (0, 0) centered in the Turtle Graphics Window (see `SLOGO-58`).
`SLOGO-58`	Turtle Graphics Window	Core	Provide a view that shows the effect of all commands that create drawings or change the state of the turtle. These outputs are not erased between commands.
`SLOGO-59`	Interactive Command Prompt	Core	Provide users a text area to input commands that effect the turtle. When a user executes valid command(s) in this prompt (either by pressing the `Shift-Enter` key or another mechanism you provide), the system should execute the commands in order, applying any changes in succession, and visualize the results in the Turtle Graphics Window. Commands are separated by whitespace, as defined by the SLogo language specification. All commands that are successfully executed should be added to the command history.
`SLOGO-60`	View of Command History	Core	Provide users a view of *all* successfully executed commands from this session, ordered in execution order. In the case of nested commands, entries should display just the outermost complete command (with a mechanism to expand it to see all the nested commands within).
`SLOGO-61`	View of User-defined Variables	Core	Provide users a view of all currently available user-defined variables. It should include both the variable's name and numeric value (with a mechanism to expand it to see the commands assigned to the variable).
`SLOGO-62`	View of User-defined Commands	Core	Provide users a view of all currently available user-defined commands. It should include the keyword for the command and any parameters the command takes (with a mechanism to expand it to see the nested commands within).
`SLOGO-63`	Help Documentation: Overview	Core	Provide a help view that lists the currently available commands. For each command, it should provide the name of the command and any parameters the command takes. The commands should be displayed in the current command language (see `SLOGO-69`). For example, the FORWARD command should show "FORWARD pixels" in English and "ADELANTE píxeles" in Spanish.
`SLOGO-64`	Help Documentation: Command Help	Core	From the Help Overview page, include a mechanism to load detailed documentation on individual commands (i.e., make the commands clickable). For each command, display at least: its canonical name any aliases any parameters one example a description of the command's functionality NOTE, this documentation should be generated from resource files (i.e., XML) in your project.

Program Management

ID	Name	Priority	Description
`SLOGO-65`	Command XML	Core	Provide an XML file for command metadata for each command your application supports. This file should include: canonical name description example help documentation (such as parameters, return value, category, etc.) number of expected parameters implementing Class or Method name This file should be used to programmatically map command names to implementations (see `DESIGN-19`) and generate help documentation (see `SLOGO-64`). It may optionally include extra information such as alternate names or help documentation depending on how you decide to handle language translation (see `SLOGO-69`).
`SLOGO-66`	Save Program	Core	Provide a mechanism for a user to save their current history of commands as a program in a file. The program should be formatted in with each top-level command on a newline. The user should have the option to choose where to save the program file. The default file extension should be `.slogo`.
`SLOGO-67`	Load and Execute Program	Core	Provide a mechanism for a user to load a SLogo program from a file on the Splash Screen. When the user loads the program from the file, the IDE is opened to the default initial state, and then program is executed. If the program cannot be loaded, an error should be displayed to the user on the Splash Screen. If the program loads successfully but contains unexecutable commands, the program should execute valid commands up to the first invalid command, and then provide the user with an error message as if the invalid command had been entered into the command prompt.
`SLOGO-68`	Load and Execute Program from Open IDE	Core	Provide a mechanism for a user to load a SLogo program from a file in an already open IDE environment. This should function identically to `SLOGO-67`, except that the user should be presented with the option to not reset the environment to the initial state before executing the program. If the user does not reset the state, the commands in the program should be executed from the current state of the program.

Interface Customization

ID	Name	Priority	Description
`SLOGO-69`	Language Selection	Core	Allow users to select from at least three different languages for the text displayed in the UI, including the language in which commands are understood. This may be configured in the Splash Screen (see `SLOGO-56`) before loading the IDE to avoid the complexity of dynamically resetting the text of every Node already created. Logo is used by children internationally! (see Example Translations)
`SLOGO-70`	Background Color Customization	Core	Provide a mechanism for users to customize the background color of the turtle’s display area, allowing a choice beyond the default specified in the CSS style. When the user changes the background color, the background color of the Turtle Graphics Window should be changed to the newly selected color.
`SLOGO-71`	Pen Colors	Core	Provide a mechanism for the user to change the color of the pen. When the user changes the pen color, no current lines should be changed, but future lines should be created in the new selected color.
`SLOGO-72`	Turtle Image Override	Core	Provide a mechanism for users to select and set their own turtle image from the local file system, overriding the default turtle image specified in the CSS style. When the user selects a new turtle image, it should replace the default image in the Turtle Graphics Window.
`SLOGO-73`	Theme Selection	Core	Provide a mechanism for users to select from different UI themes, such as “dark mode” and “light mode” or “Duke mode” and “UNC mode”. These themes can include multiple style changes, such as font sizes. Note: when the user changes the theme, the UI should be immediately updated to reflect the changed theme (since applying a new stylesheet has an immediate effect on all Nodes in the Scene).

Animation

ID	Name	Priority	Description
`SLOGO-74`	Turtle Animation	Core	When a command is executed that causes the turtle to move or rotate, the system animates the turtle's movement, displaying multiple intermediate states.
`SLOGO-75`	Play/Pause/Step Through Animation	Core	Provide mechanisms for pausing and playing animations. When a user executes a command, they should be able to pause the animation before it completes. Then, they should be able to play the animation from where it was paused or step through the animation one animation-step at a time.
`SLOGO-76`	Replay Animation	Extension	Provide mechanisms for a user to replay the previous animation. When a user replays an animation, any lines that were drawn should be erased and the turtle should return to its position before the previous command. Then, the animation should play exactly as it did previously such that the Turtle Graphics Window ends in the same state it started.
`SLOGO-77`	Line Animation	Extension	When a command is executed that causes a line to be created, the system animates the creation of any lines that the turtle creates, revealing the line progressively, corresponding to the turtle's path through the animation.
`SLOGO-78`	Animation Speed Adjustment	Extension	Provide a mechanism for users to adjust the animation speed of the turtle's movements and rotations. There should be a minimum and maximum speed. The maximum speed should result in no animation, directly displaying the final position of the turtle. When the user changes the speed, all future commands should be animated at the prescribed speed.
`SLOGO-79`	Dynamic Animation Speed	Extension	Extend `SLOGO-78`, but instead of applying changes to future animations, change the speed of any ongoing animations as well.

Design Requirements

You will be accountable for ensuring that your code's design meets the specification just like you are responsible for ensuring your code's functionality meets the Functional Specification. Keep in mind that design is more important than functionality for your final grade and you should not expect to meet all the design requirements by simply getting it “working” right before the deadline.

These design requirements are an extension of those given for previous projects. Below is a table of the project's expected design goals, following the format in the Design Requirements Glossary.

New Requirements

ID	Name	Priority	Description
`DESIGN-17`	Model API	Consistent	Provide a well-defined Application Programming Interface (API) for your Model. The View should only interact with the model via the API. Each class and method should have complete Javadoc comments. SLogo Note: The `slogo.model.api` package should represent your External API and contain *only* abstractions (Java `interface`s or `abstract` classes), purely immutable classes, or Exceptions to be used by other packages. The rest of the internal Model code, consisting primarily of concrete subclasses that are not `import`ed or known about directly by other packages, should be in other sub-packages of `slogo.model`. *No classes should be directly in the `slogo.model` package.*
`DESIGN-18`	Automated Testing	Consistent	Your program must be tested using JUnit (with assertions both for typical situations and possible thrown Exceptions) to verify it works as intended. These tests should be a mix of: Model Tests: tests that test one small unit of functionality End-to-End Tests: tests that simulate the user interacting with user interface (using TestFX) Your testing goals are to: write JUnit Tests for each concrete class with at least two well-named tests for each non-trivial `public` method (more than two for complex methods) write at 10 negative scenario JUnit Tests where the expected behavior is to throw an Exception achieve at least 70% line test coverage overall
`DESIGN-19`	Reflection for Instantiation from Strings	Consistent	Use reflection whenever you need to create objects from `String`s rather than hardcoding conditionals or a mapping between the `String` literal and your object. You may need to couple this with dynamic method calls using reflection.
`DESIGN-20`	Apply Design Patterns	Forthcoming	Define and describe your system design using Design Patterns. Your classes should follow the naming conventions of the design pattern you are applying (i.e., a factory class from a factory pattern should be named with the suffix `Factory`). Document your design patterns where appropriate, such as Javadoc comments and the project `DESIGN` document.

Previous Requirements

ID	Name	Priority	Description
`DESIGN-01`	Multiple Classes	Complete	Code should be divided into several classes that each have a useful purpose (i.e., non-get/set methods). Avoid these code smells: large class and data clumps.
`DESIGN-02`	Named Constants	Complete	Named constants, including numbers, strings, and Enums, for values used multiple times or in program logic. This includes being declared as final variables with an intention revealing name.
`DESIGN-03`	Don’t Repeat Yourself (DRY)	Complete	The same lines of code should not appear in multiple different places in the same project (i.e., they should not be duplicated). Instead, the code should be refactored so that the duplicated logic is written only once and called from many places.
`DESIGN-04`	Tightly Scoped Methods	Consistent	Each method should be small and single-purpose. Long methods should be decomposed into smaller pieces of functionality. Long methods are a code smell.
`DESIGN-05`	Code Formatting	Consistent	Code should follow course formatting conventions, including things that cannot be automatically checked, especially the Java naming conventions.
`DESIGN-06`	Interact Through Methods	Consistent	Classes should avoid inappropriate intimacy by collaborating via method calls. A class should not directly access the instance variables of another class. Do not use public instance variables or global variables.
`DESIGN-07`	Comments	Consistent	Follow Javadoc conventions for commenting on public classes, interfaces, methods, and packages. In-line comments should be used judiciously; self-explanatory code is preferred. See Internal Documentation.
`DESIGN-08`	Incremental Delivery	Complete	Your team's project GIT repository should show many, purposeful commits from all team members rather than just one or two large “kitchen sink” commits and marathon merging or redesign sessions. Commit messages should include the requirement number as described in the requirements glossary, starting with either `[SLOGO-NN]` for new features and `[DESIGN-NN]` for refactorings). NOTE: Each person must push at least four commits that show the results of refactoring existing code to improve its design, with a commit message describing the issue(s) addressed. Start these commit messages with `[DESIGN-NN]`.
`DESIGN-09`	Model View Separation	Complete	GUIs should be separate from the model; this requires clear articulation about what information (including errors) needs to be communicated between each part. SLOGO Note: You may optionally include a Controller from Model-View-Controller if your team has complex logic for handling user inputs that results in code duplication or tight coupling between View components. The View should be a collection of classes in package called `slogo.view`. Classes in the `slogo.view` package use OpenJFX to display to the user and interact with the Model. The Model should be a collection of classes in a package called `slogo.model`. The Model maintains the state of the turtle and associated program information. Classes in the `slogo.model` package should not import any classes from `javafx.*`; classes in `slogo.model` should be agnostic to how the information is presented to user. For both the `slogo.view` and `slogo.model` packages, you can put classes in sub-packages as well, i.e. in `slogo.model.foo` or `slogo.model.bar`.
`DESIGN-10`	Encapsulation	Complete	Key implementation details *must* be hidden such that they can be changed *without impacting any other classes*.
`DESIGN-11`	Make and Use Abstractions	Complete	Create abstractions that capture commonality (superclasses or interfaces) and encourage variability (subclasses or implementors). Build your classes to depend on the abstractions (superclasses and interfaces) rather than implementations (concrete subclasses). EXAMPLES: Use the most abstract collection possible (i.e., `List` instead of `ArrayList` and `Map` instead of `HashMap`). Do not downcast to specific subclasses or use `instanceof` checks (except in `equals()` methods).
`DESIGN-12`	Externalize Configuration	Complete	Move hardcoded values into configuration files, rather than compiled into your program, specifically: “magic” values stored as `static final` constants any text displayed in the user interface, by using resource property files (the `String.format()` method allows you to make any complex string a single value) any styles (colors, font, borders, etc.) used to customize the user interface, by using CSS files Store these files in `src/main/resources`.
`DESIGN-13`	Programs Should Not Crash	Complete	Build robustness into your program so that it does not crash or hang. Handle errors and provide a reasonable response to exceptional cases so that the user can continue to run the program.
`DESIGN-14`	No Dead Code	Consistent	Your project should not include unused variables, methods, or classes. Do not comment out blocks of code to save them for later; instead, use your GIT history to find old code.
`DESIGN-15`	Handle Errors Using Exception Flows	Consistent	Communicate errors in a thoughtful, intentional, manner rather than returning `null` or other error prone values. Consider using custom Exceptions or Java's `Optional`.
`DESIGN-16`	Explicit Immutability	Consistent	For classes and values that should not change after they are instantiated, explicitly restrict them from changing using language features. Consider using Enumerated types or Records.