Interacting with Jython files

Requirements Document

Team 3 - Jython programming Environment for Students

The purpose of this project is to create a Jython programming environment for students. The environment will be put to use in the 2002 academic year in a new Introduction to Computing class at Georgia Tech. The target students for the class are those that are not engineering or computer science majors. Therefore the user interface for the development environment must be easy for people with little programming experience to use. The user interface must be clearly labeled and free of excess clutter. The system should be contained inside one window for maximum clarity. Also, the user will only be allowed to edit one file at a time. The system will have two text areas, one for editing a file, and the other for access to the interpreter. The intended use is for a student to write a function in the top editor, then load it and execute it by typing the name of the function in the interpreter window. The system will attempt to keep novice users from making obvious mistakes. The system will catch errors thrown by the interpreter and provide comprehensible error messages. Also, the main debugging option available to users will be a function call that opens a separate window to display the values of the current variables. The system will provide a “Help” menu that links to external html help files provided by the client. These tools should provide the student with the basic things needed to learn how to program in Jython.

The project will be continually revised during its use in class. Professor Guzdial will maintain the software, and as a result the code must be well documented and extremely readable. The code must also execute reliably. The IDE will be implemented in Jython, which runs on a Java Virtual Machine. This allows the system to be platform independent. Error messages, as well as other default settings, will be included in a constants file so that they can be easily modified after the release of the project. The system will provide the basic tools an inexperienced user needs to succeed in the class. The system will be expandable, since people other than the original authors will modify it at a later date. The system should be as error free as possible, since many different people will use it on many different platforms. The final product will be an IDE that is slightly simpler than commercial ones, but will be easier to understand and use for students specifically taking this class.

A. Interacting with Jython files:

1. 
   The system must allow users to create new Jython files.
   
   • 
     JES will provide a menu option for users to create a new Jython file, clearing out the currently opened Jython file.
     
2. 
   The system must allow users to open Jython files.
   
   • 
     JES will provide a menu option for users to open existing Jython files. Only one file can be open and used at a time. Opening a file will clear the existing file from the JES editor.
     
3. 
   The system must allow users to save Jython files.
   
   • 
     JES must provide a menu option for users to save the currently open Jython file.
     
4. 
   The system must allow users to edit Jython files.
   
   • 
     JES will allow users to edit the currently open Jython file.
     
5. 
   The system must provide minimal preprocessing of Jython files, which can be defined within an external file.
   
   • 
     When JES executes a Jython file, it will execute code that is provided in an external file. This file will be used for importing specific modules for the users of JES to use.
     

B. Interacting with the Jython Interpreter:

1. 
   The system must allow users to execute Jython files.
   
   • 
     The interpreter will run as a separate thread so that the GUI will still function when the user is running code.
     
2. 
   The system must provide a method to the users that will pop up a window that shows all visible variables.
   
   • 
     Each call to the method should pop up an instance of the show variables window.
     
3. 
   The system must open the debug window displaying variables upon errors.
   
4. 
   The system must give error messages that would be clear to first time programmers.
   
   • 
     JES must catch Jython exceptions and give the user clearer error messages
     
5. 
   The system must make these error messages editable from an external file.
   
   • 
     The class administrator should be able to define the error messages that he or she wants the students to see without editing any source code.
     
6. 
   The system should highlight lines that contain errors after a user attempts to run the Jython file.
   
7. 
   The system should highlight Jython keywords.
   
   • 
     The keywords may all be the same color so users can tell keywords from non-keywords.
     
8. 
   The system must allow user to interrupt the program.
   
9. 
   The system must prompt the user to save before loading the program, if any changes have not been saved.
   
10. 
    The system should check the file for indentation errors prior to loading.
    
    • 
      JES will provide a separate error message just for indentation errors.
      

C. GUI Requirements:

1. 
   The system must have a text area at the top of the screen for editing Jython text.
   
   • 
     This text area is just for function definitions, no executable code.
     
2. 
   The system must have a text area at the bottom of the screen for interacting with the Jython interpreter and displaying error messages.
   
   • 
     This text area is for executable code that can use function definitions from the top text area after it has been loaded. Also displays error messages generated by code execution.
     
3. 
   The system should have windows that are resizable.
   
4. 
   The system should have text areas that handle cut, copy, paste, and undo.
   
5. 
   The system must have a menu bar with a “File Menu” containing “new”, “open”, “save”, and “save as” buttons.
   
6. 
   The system should have a menu bar with an “Edit Menu” containing “Cut”, “Copy”, “Undo”, and “Paste” buttons.
   
7. 
   The system must have a “Load” button that will send the text to the interpreter.
   
   • 
     The “Load” button will be located in between the text areas, underneath the top text area containing the function definitions to load.
     
8. 
   The system should have a menu bar with a “Help” menu containing links to HTML files written by the client.
   
   • 
     Mark Guzdial will prepare HTML files for help topics. JES will provide links to his files from the “Help” menu.
     
9. 
   The system should have an “About” option on the “Help” menu to view information about the program.
   
   • 
     The “About” window will include author names and license information.
     
10. 
    The system must include script and batch files to run the program on major operating systems.
    
    • 
      JES should support Windows, Unix, Macintosh, Linux, and Sun operating systems.
      

D. Non-functional Requirements:

1. 
   The system must be usable by first time programmers.
   
   • 
     JES will be primarily used by students who are non-CS freshmen and who do not have any programming experience. The user interface will be kept as simple as possible so as not to confuse these students.
     
2. 
   The system must be portable to major operating systems.
   
   • 
     JES will need to run on Windows, Macintosh, and Unix systems.
     
3. 
   The code should be readable and maintainable.
   
   • 
     JES will be maintained and enhanced by Mark Guzdial after it has been completed. The code will be readable and maintainable so that its functionality can be easily extended.
     
4. 
   The system must be written in Jython.
   
5. 
   The GUI must be implemented in Swing.
   
6. 
   The system should indicate areas in the code for the client’s later use.
   
   • 
     In the future, JES will be enhanced with some additional functionality. The area where these modifications must be made will be clearly indicated in the code. These enhancements include:
     
     1. 
        Ability to encode and turn-in files from JES
        
     2. 
        Log user events with timestamps and include that in turn-in
        
     3. 
        Multiple sizes of text to make use in lecture easier
        

E. Bibliography

1. 
   Primary Source: Mark Guzdial, Associate Professor, Georgia Institute of Technology
   
2. 
   Texts:
   
   1. 
      Eckstein, Robert, Marc Loy, and Dave Wood. Java Swing. California: O’Reilly & Associates, Inc., 1998.
      
   2. 
      Lundh, Fredrik. Python Standard Library. California: O’Reilly & Associates, Inc., 2001.
      
   3. 
      Pedroni, Samuele, and Noel Rappin. Jython Essentials. California: O’Reilly & Associates, Inc., 2002.