P Lisp User Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 17
| Download | |
| Open PDF In Browser | View PDF |
pLisp User Manual 1. Introduction pLisp is an integrated development environment for Lisp. While it aims to be a friendly Lisp development system for beginners, its feature-set is comprehensive enough to address the needs of a small-to-medium sized Lisp project. Please refer to the README file for more details. This document is the user manual for pLisp. It is not a language reference manual. Email me at rajesh.jayaprakash@gmail.com for comments and suggestions. 2. Getting pLisp You can get pLisp from here. You can either use git to check out the code or download a single source tar.gz, deb, or zip file. 3. Installing pLisp Note: Please refer to Section 14 for instructions on installing pLisp from source. Linux pLisp can be installed using the 'dpkg' command (sudo dpkg -i). The following dependencies need to be satisfied first (you can install these packages using the package manager of your choice): libgtk-3-0 libgtksourceview-3.0-0 libffi6 tcc Note: If you get the error "tcc: error: file '/usr/local/lib/tcc/libtcc1.a' not found" on launching pLisp after installation, create a symbolic link to this file (found in the installation directory of tcc) in /usr/local/lib/tcc. I am investigating this. Windows Simply unzip the downloaded zip file to a location of your choice. You will also need the GTK and GTKSourceView packages for Windows, which can be installed using MSY2 and pacman. For example (from an MSYS2 shell): pacman -S mingw-w64-i686-gtk3 pacman -S mingw-w64-i686-gtksourceview3 Before running pLisp, ensure that the PATH environment variable has been updated to reflect the location of the MSYS2 DLLs. For example set PATH=%path%;c:\msys32\mingw32\bin OS X Double-click the downloaded .DMG file and drag the pLisp application to the directory of your choice (typically 'Applications'). You can then run pLisp as you would any other OS X application (from the Launcher, Spotlight, and so on). Please note that this will launch pLisp in the current user's home directory, so if you would like automatic opening of an image on startup, you should create/save the image as 'plisp.image' in your home directory. 4. Invoking pLisp Command line warnings when running pLisp in OS X: tcc throws up a lot of warnings when running pLisp. These warnings can be ignored. One option is to redirect them to /dev/null (plisp 2>/dev/null). I'm working on this. You have four options while starting pLisp: a. plisp -c: Run pLisp in command-line mode, i.e., without any of the user interface bells and whistles. You will be presented with just a prompt, and you have to type your Lisp expressions at this prompt (Figure 1). The results of evaluating the expression will be displayed below the prompt (more later in Section 13 on what the prompt signifies). After you're done with all the expressions, type '(quit)' to exit pLisp. Then do a hundred push-ups and take a cold shower. b. plisp -e : Use pLisp to just evaluate a single expression, print the results and Figure 1 quit (see Figure 2). This is useful for both running the programs that you have created using pLisp, and for using pLisp as a calculator [plisp -e '(+ 1 2)']. Note that the expression has to be enclosed in single or double quotes. Figure 2 c. plisp -i : Start pLisp by loading an existing image. An image is a file on your hard disk that stores a snapshot of your pLisp system – all the functions, variables, and other objects that you created in the course of your development. Image-based development is not only an incredibly powerful way to build code, but also has other benefits (easier debugging and persistent objects, to name a few). Also, the cool thing about pLisp images is that they remember the details of the UI elements, so if you open an image, you will be presented with the same windows (even the Debugger window) that were open when you saved the image last. d. pLisp -p: Run pLisp in pipe mode. This is an experimental feature; this mode is similar to command-line mode, except that no prompts are printed. It is for scenarios where you might want to interface to pLisp with another executable. These options can be used alone or in combination: you can start with an image in command line mode, or evaluate a single expression on an image and quit. But you cannot use both the '-c' (or '-p') and '-e' options together: if you're going to quit after evaluating a single expression, it doesn't matter whether you are in command-line mode or GUI mode. The order of these options also does not matter; for example, you can either say plisp -e -i or plisp -i -e . Note: If you invoke pLisp without any arguments, it looks for the default image file named 'plisp.image' in the current directory, and if this file is found, proceeds as if it was invoked with the '-i ./plisp.image' option. If plisp.image is not found, it starts up in 'no-image' mode (warning: this will take a while, since all the core library forms will have to be compiled from scratch); you will then have to save/create the image manually yourself when you exit pLisp. pLisp ships with this default image file as part of the distribution, copy this file to a location of your choice. 5. The Transcript Window So you have invoked pLisp in GUI mode. You will be presented with the main window in the pLisp UI, namely the Transcript window (Figure 3). Figure 3 The Transcript window displays the results of evaluating expressions entered in the Workspace window. In addition to this, it's also the primary means of controlling pLisp, through the tool bar actions. The tool bar has six buttons: Click on this button if pLisp has been invoked without an image file and you would like to load an image file, or if you would like to switch to another image file. Keyboard shortcut: Control-L Click on this button either to save an already loaded image file or to create a fresh image. Keyboard shortcut: Control-S. This button opens the Workspace window or, if it's already open, brings it to the front. Keyboard shortcut: F7. This button opens the System Browser window or, if it's already open, brings it to the front. Keyboard shortcut: F9. Click on this button to clear the contents of the Transcript. Exits pLisp. If you have made changes to an image, you will be prompted to save the changes. Keyboard shortcut: Control-W. 6. The Workspace Window As mentioned in the previous section, pressing F7 or clicking on the Workspace tool bar button in the Transcript window brings up the Workspace window (Figure 4). Figure 4 As the text in the window helpfully indicates, type the pLisp expressions here that you would like evaluated. The result will appear in the Transcript window if all goes well. The Workspace window has five tool bar buttons that can be used to control its behaviour: Click on this button to load a file containing pLisp source expressions. Useful if you would like to feed multiple (previously saved) expressions in one shot. Keyboard shortcut: Control-O. This button opens the File Browser window, or, if it's already opened, brings it to the front. Click on this button to evaluate a selected expression entered into the workspace. Keyboard shortcut: Control-Enter. Click on this button to clear the contents of the workspace. Click on this button to close the Workspace Window. Keyboard shortcut: Control-W. 7. System Browser Window Pressing F9 or clicking on the System Browser tool bar button in the Transcript window brings up the System Browser Window (Figure 5). Figure 5 The System browser has three panels: the Packages panel, the Symbols panel, and the code panel. The Packages panel lists all the packages defined in the system (see Section 13). The Symbols panel lists all the symbols belonging to the selected package. Finally, the code panel displays the code corresponding to the selected symbol if it's a closure or a macro, or the value (integer, float, character, etc.) that is bound to the symbol. The System Browser has these nine tool bar buttons: Click on this button to create a new package. Keyboard shortcut: Control-K. Click on this button to rename a symbol. Keyboard shortcut: F2. Click on this button to create a new symbol in the selected package. Keyboard shortcut: Control-N. Click on this button to accept the changes made in the code panel. Keyboard shortcut: Control-S. Click on this button to delete the selected symbol. Keyboard shortcut: Control-X. Click on this button to refresh the contents of the System Browser (for example, if you've made changes by typing expressions in the Workspace window and would like to sync the System Browser with these changes). Keyboard shortcut: F5. Click on this button to export the contents (in pLisp source form) of the selected package Click on this button to list all the top-level definitions that refer to the selected symbol Click on the button to close the System Browser window. Keyboard shortcut: Control-W. 8. Referrers Window The Referrers window is invoked from the System Browser window to list all the top level definitions that refer to the selected symbol. Figure 6 below shows a sample invocation of the Referrers window for the core symbol 'length': Figure 6 9. File Browser Window The File Browser window is invoked from the Workspace window. You can view and edit pLisp source files using the File Browser. The File Browser also supports evaluating expressions by using either the keyboard shortcut (Control-Enter) or the provided toolbar button. Figure 7 Note: Press Control-F to trigger the search window in the File Browser, press Control-G to continue the search. 10. Debugger Window Debugging pLisp code entails placing '(BREAK)' statements judiciously in your expressions and inspecting the state of the system by means of the Debugger window. The Debugger window displays the call stack. A (contrived) example will clarify things. (let ((x 0)) (print x) (break) (incf x) (break)) This code creates a local variable x, initialized to zero, prints it, then increments it. There are break statements after the print and the increment. Evaluating this expression brings up the Debugger window twice (Figure 7), once for each break statement (pressing the Resume button in the window resumes the evaluation). Pressing the Abort button aborts the evaluation. Figure 8 11. Exceptions The Debugger window is also invoked automatically whenever your code hits an exception. The call stack is displayed, with the expression causing the exception on top (Figures 9, 10 and 11). An important point to note is that since the pLisp code is compiled into native code using continuation-passing style, no function ever returns, and the call stack includes all the function objects invoked directly and indirectly through the REPL invocation. Figure 9 Figure 10 Figure 11 12. Online Help Context-sensitive help is available in pLisp for all the keywords and core forms. Pressing F1 on a symbol when in code-editing mode (i.e. in the Workspace, System Browser code panel or the File Browser; also in the Referrers window) launches the help window for that symbol if available. The status bar in the relevant window also displays the signature of the function or core form when the name of the function or core form is typed. pLisp also comes with an autocomplete feature: if there is no ambiguity about what symbol you're referring to when you press tab midway through the typing of the symbol name, pLisp fills in the remaining part of the name. Figure 12 13. A Note About Packages pLisp objects are categorized into namespaces called packages. The CORE package contains all the predefined special operators (CAR, CDR, and so on), and it is not permitted to modify this package by adding or modifying any symbols in it. A package called USER is created by default, and the user is expected to define their code in this package. Additional packages can be created if needed, of course. The evaluation of any expression is always in the context of the current package, indicated in the title of the Workspace window in GUI mode and in the prompt in the console mode. 14. Building pLisp From Source Linux To install pLisp, simply type './configure', 'make' and 'sudo make install' at the command line after navigating to the directory to which you downloaded/extracted the pLisp files. Before you do this, however, the following dependencies need to be taken care of (in addition to having GCC and make in your system): a. Flex and Bison b. The GTK 3.0 development package (libgtk-3-dev) c. The GtkSourceView development package (libgtksourceview-3.0-dev) d. Tiny C Compiler (tcc and libtcc-dev) e. The libffi package (libffi6) f. The Boehm Garbage Collector All these packages can be installed using the package manager that comes with your distro. OS X a. Install pkg-config using Homebrew b. Install GTK3 using the jhbuild system: ./gtk-osx-build-setup.sh jhbuild bootstrap jhbuild build meta-gtk-osx-bootstrap meta-gtk-osx-gtk3 c. Install GtkSourceView3, again using jhbuild: jhbuild build gtksourceview3 d. Install the Tiny C Compiler. You will have to do it the './configure; make; sudo make install' way. e. Install the Boehm Garbage Collector using './configure; make; sudo make install' f. Install pLisp by entering into a jhbuild shell and typing './configure', 'make' and 'sudo make install' at the command line after navigating to the directory to which you downloaded/extracted the pLisp files. Windows a. Install MSYS2 b. Install gcc, make, flex, bison, pkg-config, GTK3, GtkSourceView3 using the pacman utility from an MSYS2 shell: pacman -S c. Install the Tiny C Compiler. You will have to do it the './configure; make; sudo make install' way. d. Install the Boehm Garbage Collector using './configure; make; sudo make install' e. Install pLisp from the MSYS2 shell by './configure', 'make' and 'sudo make install' at the command line after navigating to the directory to which you downloaded/extracted the pLisp files. Note: pLisp can be installed on Cygwin; however, issues with compiling TCC on Cygwin make this quite cumbersome.
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No Page Count : 17 Language : en-US Creator : Writer Producer : OpenOffice 4.1.3 Create Date : 2019:01:02 09:53:43+05:30EXIF Metadata provided by EXIF.tools