============= Using PurePad ============= The following information is available: * :doc:`windows`: important release notes that you should read first * `Getting Started`_: a brief overview of PurePad * `Editing Scripts`_: manage Pure scripts with PurePad * `Running Scripts`_: run Pure scripts using the Pure interpreter * `Using the Log`_: how to interact with the Pure interpreter * `Locating Source Lines`_: quickly find source lines in error messages from the interpreter Please also check the sidebar for other available documentation, including :doc:`pure`, the :doc:`purelib` and information about various bundled modules. (Note that at present only a subset of all available addon modules is included in the Windows distribution.) Getting Started =============== PurePad is a standard Windows application, with the menus, toolbar and status line you are familiar with (see figure below). Like the standard Windows editor from ancient times, PurePad is a single-document application, i.e., there is only one source file open at any time. The main window is divided into two panes. The upper pane is the source pane which usually contains the Pure script you are currently working with. The lower pane is the log pane in which you interact with the interpreter (input expressions to be evaluated, watch the interpreter's output, etc.). Editing operations, as well as the :menuselection:`Font` and :menuselection:`Tab Stops` commands in the :menuselection:`View` menu and the :menuselection:`Print` and :menuselection:`Print Preview` commands in the :menuselection:`File` menu, always apply to the currently selected pane, i.e., the pane which contains the cursor. .. figure:: purepad.png PurePad main window. To start up the interpreter you use :menuselection:`Script --> Run` (:kbd:`F9`) and wait for the interpreter's ``>`` prompt to appear. This command will run the Pure interpreter with the script currently shown in the source pane (or an empty script if you haven't yet loaded a script using the :menuselection:`File --> Open` (:kbd:`Ctrl-O`) command). The cursor will be placed in the log pane (see `Using the Log`_) and you can start typing in expressions and definitions to be evaluated. See `Running Scripts`_ for more information on this. To begin a new script, use the :menuselection:`File --> New` (:kbd:`Ctrl-N`) command. Probably the next thing you want to do is to enter your first own little Pure script. For instance, here is a version of the factorial function:: fact n = if n>0 then n*fact (n-1) else 1; Enter this equation into the source editor pane, save the script as ``fact.pure`` with the :menuselection:`File --> Save` (:kbd:`Ctrl-S`) command and press :kbd:`F9`. The cursor will be placed into the log pane and after a while the interpreter's ``>`` prompt will appear. You can now type an expression like :: map fact (1.. 10); and see what happens. The currently selected pane (source or log) can be printed using the :menuselection:`File --> Print` (:kbd:`Ctrl-P`) command; you can also obtain a print preview with the :menuselection:`Print Preview` command in the :menuselection:`File` menu. To change the font and tabulator settings in the current pane, use the :menuselection:`Font` and :menuselection:`Tab Stops` commands in the :menuselection:`View` menu. (Usually it is best to choose a fixed-width font here, like ``Fixedsys``, which is also the default. Tab stops are set to 8 by default.) Editing Scripts =============== The :menuselection:`File` menu contains the usual set of operations which let you create new script files, open existing files, save a file that has been edited, preview and print the current file and exit the application. The :menuselection:`View` menu allows you to change tabulator settings (:menuselection:`Tab Stops` option) and the font used for display and printing (:menuselection:`Font` option). Scripts are edited in the upper (source) pane of the main window just as in the Windows Notepad editor. In the :menuselection:`Edit` menu you find the common editing operations (:menuselection:`Undo`, :menuselection:`Cut`, :menuselection:`Copy`, :menuselection:`Paste`, :menuselection:`Select All`, :menuselection:`Find`, :menuselection:`Replace`, and :menuselection:`Go To`, which allows you to jump to the line number you specify). Many of these operations can also be accessed by means of the familiar accelerator keys or the toolbar. Running Scripts =============== Once you have entered your script and saved it in a file, you can run the script using the Pure interpreter. The relevant commands can be found in the :menuselection:`Script` menu: * :menuselection:`Run` runs your script with the Pure interpreter, in the directory where your source script is located. If the interpreter is already running, it is terminated first. * :menuselection:`Debug` invokes the interpreter with the built-in debugger. This allows you to trace the calculations ("reductions" in Pure parlance) performed by your script. Note that to actually debug a function, you must first set a breakpoint using the interpreter's ``break`` command; please see :doc:`pure` for details. * :menuselection:`Break` sends a :kbd:`Ctrl-C` to the interpreter process. This allows you to interrupt the interpreter when it is doing a time-intensive evaluation, is producing output or is waiting for input. * :menuselection:`Quit` exits the interpreter. This usually has the same effect as typing ``quit`` at the interpreter's prompt and is performed automatically when PurePad is exited and the interpreter is still active. It also kills off the interpreter process if it does not terminate within a reasonable amount of time after it has been notified. As soon as the script has been started, the cursor switches to the log (the lower pane), the interpreter's prompt will appear and you can start typing definitions and expressions, and watch the interpreter print the results. The log pane is an edit control into which you can type text as usual. It also has some special commands which allow you to access an input history and to quickly locate positions in source files, see `Using the Log`_ for details. If you run a script which has errors in it then the Pure compiler will display a list of error messages. To quickly locate the source file positions listed in the error messages, use the commands described in `Locating Source Lines`_. You can check whether a script is running by taking a look at the title bar of the PurePad window. The name of the previously started script is shown there inside brackets. If it is preceded with the text ``Terminated -``, then the script is not currently running, either because the interpreter was exited in a regular fashion, or because some other, unexpected event happened, like a stack overflow. There are a number of other items in the :menuselection:`Script` menu which deal with the running script and the interpreter's configuration: * :menuselection:`Open` reopens the previously started script (the one whose name is shown inside brackets in the title bar) in the upper source pane. This operation is useful when you have opened other source files and now want to quickly reload your "main" script. * The :menuselection:`Prompt` option allows you to change the interpreter's prompt (this only becomes effective when the interpreter is started the next time using the :menuselection:`Run` or the :menuselection:`Debug` command). * :menuselection:`History File`, :menuselection:`History Size`. With these options you can set the name of the file used to store the input history, and the size of the history, respectively (see `Using the Log`_ for details). * :menuselection:`Reset Log`. When this option is checked, the log is cleared any time a new script is run. Using the Log ============= The log, the lower pane of the PurePad main window, is an edit control which logs both your input to the interpreter and the interpreter's output. In the log you can use all the usual editing operations, as well as the commands in the :menuselection:`Edit` menu. Furthermore, printouts and print previews of the current contents of the log can be obtained using the corresponding operations of the :menuselection:`File` menu, and the :menuselection:`View` menu allows you to change tabulator settings and the font used for display and printing. The size (i.e. number of lines) of the log is limited. This limit (500 lines by default, but you can change this manually with the Windows regedit utility) is necessary because each evaluation can produce an arbitrary amount of output, while the text size of a Windows edit control is usually limited to 64 KB. When the interpreter is currently running, typing :kbd:`Return` in the last line (the current input line) of the log sends the line (with the prompt removed) to the interpreter. In fact, any line in the log window, not only the last one, can be edited and sent to the interpreter using :kbd:`Ctrl-Return`. When using this command, the line is copied down to the end of the log. The log also maintains an input history for the (non-empty) lines you sent to the interpreter. When positioned at the input line, you can browse through this history using the :kbd:`Ctrl-Up` and :kbd:`Ctrl-Down` cursor keys (which recall and insert the previous and the next input line, respectively). :kbd:`Ctrl-PgUp` and :kbd:`Ctrl-PgDn` go to the first and the last line of the history, respectively. Finally, you can search the history using the :kbd:`Shift-Ctrl-Up` and :kbd:`Shift-Ctrl-Down` keys which look for the closest previous (resp. next) history line which matches the text before the current cursor position. The size of the input history (100 lines by default) can be set using the :menuselection:`History Size` option of the :menuselection:`Script` menu. Furthermore, the history is stored in a text file (``PurePadHistory`` by default) when PurePad is exited. You can switch to another history file using the :menuselection:`History File` command in the :menuselection:`Script` menu. Locating Source Lines ===================== To quickly locate the source line of an error message shown in the log pane, PurePad provides some keyboard commands and toolbar buttons which can be invoked from both the source and the log pane. * :kbd:`F3` (:menuselection:`Next Error`, :guilabel:`>` button) finds and displays the position of the next source line reference in the log, starting below the current line in the log. * :kbd:`Shift-F3` (:menuselection:`Previous Error`, :guilabel:`<` button) finds and displays the position of the previous source line reference in the log, starting above the current line in the log. * :kbd:`Ctrl-F3` (:menuselection:`Last Error`, :guilabel:`>>` button) finds and displays the position of the last source line reference in a sequence of consecutive messages in the log, starting at or above the current line in the log. * :kbd:`Shift-Ctrl-F3` (:menuselection:`First Error`, :guilabel:`<<` button) finds and displays the position of the first source line reference in a sequence of consecutive messages in the log, starting at or above the current line in the log. Each of these commands opens the file indicated by the message (if it is not open already) and sets the cursor to the corresponding line. Furthermore, it marks the message in the log and also displays the source position in the status line. Please note that since PurePad is a single-document application, opening a new source file in this manner closes the file currently in the source pane. If this file has been modified, you will be prompted to save the file, just as if you used the :menuselection:`File --> Open` command. Another useful command in the :menuselection:`View` menu, which is often used in conjunction with the above operations is :menuselection:`To Input Line` (:kbd:`Esc`) which quickly returns you to the input (i.e., last) line in the log pane.