\begindata{text,538478900} \textdsversion{12} \template{help} \define{global } \define{sans menu:[Font,Sans] attr:[FontFamily AndySans Int 0]} \chapter{Ness: An Extension Language for the Andrew Toolkit } \section{What is Ness? }\leftindent{Ness is a programming language and associated system based upon the Andrew Toolkit (\italic{\helptopic{ATK}}). It can be used to create stand-alone Ness programs or to create Ness scripts, which are programs that are embedded in an ATK document or application. Ness is particularly suited to extending existing ATK objects and string-processing applications. \ Examples of Ness programs and scripts created so far include databases, document formatting converters, new key definitions and menu functions for EZ, an expandable calculator, and combined music/text/animation programs that can be sent and executed in Messages. Many of these programs and scripts have been created using objects available from the Andrew Development Environment Worksheet (\italic{\helptopic{ADEW}}). This help file contains some warnings about using Ness, some pointers on using Ness for both non-programmers and programmers, a Quick Reference of Ness compilation methods and access levels for programmers, and more detailed instructions on running and compiling Ness programs and scripts for non-programmers. } \section{Warnings } \leftindent{A Ness script is a program. Like any program it can modify the files of a user who executes it. Therefore you should be careful to use scripts that come from people you know and trust. Before a script within a document will do anything, you must select the "Empower" option, either from the script or from the dialog box. See the section on \section{Running a Ness Script from EZ or Messages}.} \section{Using Ness: Non-programmers }\leftindent{If you are not a programmer, you may still want to know a few things about Ness. In particular, you will want to know how to: 1. Read a message or EZ file that contains a Ness script. 2. Run a Ness program someone has created from the Typescript window or other command window. Both these operations are described in this help document.} \section{Using Ness: Programmers} \leftindent{ }\leftindent{If you are a programmer, in addition to the information above on running Ness programs and scripts, you may want to know how to create programs and scripts. You need not have facility in any specific programming language to use Ness, but some knowledge of ATK programming and ADEW may be useful. The Reference manual for Ness is located in \ \italic{/usr/andrew/doc/atk/ness/*.doc} where a guide to the other Ness documents is in nessuser.doc. For information about programming in ATK, see the files in other subdirectories of /usr/andrew/doc/atk; especially the examples subdirectory.} \section{Running a Ness Script from EZ or Messages} \leftindent{ A Ness script within a message, document, or application will look like a piece of text with a scroll bar. Usually the text will begin, "\bold{NESS} - This inset is a Ness script. If ...", and will continue with a description of the hazards and options for "Empowering" the script. If you do not empower the script, it will be inert and will not affect the document or your files. \ The options are at the end of the scroll, where you can get to them by clicking the bottom endzone in the scroll bar. These are your options: \sans{\bold{\leftindent{Scan for dangerous statements}}} The script is checked for potentially dangerous statements. For each, the script is scrolled to the statement, it is highlighted, and a message is displayed at the bottom. To see the next potentially dangerous statement, select \bold{NextError} from the \bold{Ness} menu card. (The system is quite paranoid and often identifies as potentially harmful statements that are actually entirely innocuous.) \bold{\sans{\leftindent{Author mode - Let me edit the script}}} The warning statement is removed from around the script and the script is made to be read-write. You may then modify the script. \sans{\bold{\leftindent{Empower - I trust the source of this script}}} This option causes Ness to compile the script and activate any "extend" definitions. Thereafter any extended inset may behave differently from its normal behvior in response to your actions. For instance a mouse click on a button might be made to play music. } \section{Running a Stand-alone Ness Program from Typescript or Another Command Window} \leftindent{The program /usr/andrew/bin/nessrun is used to compile and execute a Ness program. All Ness program file names should end in a .n extension. If you want to run a Ness program, type the following from your command window: \example{nessrun } where \example{ }is the name of the Ness program and\example{ } are any arguments you need to pass along to the program (such as another filename). You are not given any options for deciding whether to trust the Ness program; it is assumed that if you asked it to execute you trust it. } \section{Quick Reference } \leftindent{To execute a Ness program from your command window: \example{nessrun } To insert a Ness script in a document (such as EZ or a SendMessage): \example{ ness } To execute a Ness script in a document (EZ or SendMessage): Select "\bold{Empower}" from the menu or from the end of the text in the script. Then select \bold{DoMain()} from the \bold{Ness} menu card. To execute a single Ness statement from applications, first put this line in your ~/.atkinit file: \example{addkey ness-dostmt \\e\\e view }\ then use \example{ } in your application to get the prompt for the Ness statement. Example script: \leftindent{-- With this script, a button inset named "when" is extended with a new behavior for a mouse click. Whenever the left mouse button goes up in this inset, the date is printed in the message line. -- extend "when" on mouse "any" if mouseaction = mouseleftup then telluser(system("date")) end if end mouse end extend} Example program: \leftindent{ -- This program is executed via -- nessrun pgm.n filename -- it reads the file and calls the Ness library function wc_CountWords to count the words. Finally, it prints the count -- }\leftindent{function \bold{main}(f) marker text integer cnt text := readfile(f) cnt := wc_CountWords(text) printline("There are " \ ~ textimage(cnt) \ ~ " words in " ~ f) end function} } \section{Pop-Up Menu meanings} Certain menu options are available only under certain conditions, as noted. \italic{Ness Menu Card} \leftindent{ \bold{Next Error:} Highlights the next portion of the Ness script that had an error and scrolls the text so it is visible. If there are no more errors, it displays a message; selecting the option again will start over with the first error. This option is available only after an \bold{Empower-compile} which had an error or after an error occurs during execution. In the latter case, there will be only one error. \bold{Show Origin:} Displays in the message line the probable author and date of the last modification to the script. (This value can be forged, but no instance of this has yet occurred. Forgery is a violation of University Regulations.) \bold{Scan for danger:} Analyzes the script to find any statement or function call which might conceivably modify any of your files, whether in memory or on the disk. \bold{Empower-compile:} Compiles the Ness script and also enables interception of events for objects mentioned in \bold{extend} statements in the script. This option is available if the script has never been compiled or if the script has been changed. \bold{Do main():} Calls the function called \bold{main} if the script has one. The option appears after the script has been \bold{Empower-compiled}. \bold{Author mode:} Makes a script read-write. You can use this option if you want to modify a script. Also, if the warning notice text is wrapped around the script, this option removes it. The option is only available if the text is read-only. \bold{Add warning:} This option wraps the warning notice text around the script and makes the whole thing read-only. An author can then see how the script will appear to a user. This option is only available if the warning notice is absent.} \leftindent{ }\section{Preferences} \leftindent{\bold{NessUseDialogBoxInsteadOfWarning:\italic{ on}} If this option is off, every script is wrapped with a warning notice describing the possible consequences of allowing a Ness to execute and providing options to enable it. When you have experience with Ness and understand the (remote, but) potential danger, you can set this preference. Thereafter when Ness scripts appear a dialog box is displayed each time a script is first encountered in a document or application. (Default value is \italic{off}.) \bold{NessPath:\italic{~/nesslib:usr/andrew/lib/ness}} Ordinarily, Ness searches for Ness library function definitions in /usr/andrew/lib/ness. To search in alternative directories, the NessPath preference can be specified with a value of a colon-separated list of directories. In the example value shown, searches for files will begin in the directory 'nesslib' of the user's home directory and will proceed next to the standard system directory. \ Warning: Putting a directory in your NessPath means that Ness programs in .n files in that directory can be compiled and executed whenever referenced. No visible warning is given to you that the files are being called.} \section{Proctable Entries} \description{ ness-dostmt Read a Ness statement seqeunce from the message line and execute it ness-load Read and compile a Ness program file \ nessview-next-error See the source code for the next error nessview-show-origin Show the author and date of last change nessview-scan-for-danger Check for any statements that might be harmful nessview-compile Compile the text in this view nessview-execute Compile Ness and execute function main() nessview-author-mode Change to be an author; remove warning text; make read-write nessview-user-mode Reinsert the warning text and be readonly } \section{Program Author } \leftindent{Wilfred J. Hansen} \section{Related tools} \ \leftindent{Select (put a box around) one of the italicized names and choose "Get Help on Selected Word" from the pop-up menu to see the help file for: \leftindent{\italic{ \helptopic{atk} \helptopic{adew} \helptopic{insets}}}}\leftindent{ You may also read further about Ness in the files in /usr/andrew/doc/atk/ness: \leftindent{\description{nessuser.doc - aid in using applications written with Ness nessauth.doc - aid for authors of Ness scripts nesstut.doc - a tutorial on the Ness language nessman.doc - a description of the language nessfunc.doc - a decription of each of the functions available to Ness nesshack.doc - some nitty-gritty stuff}}} \begindata{bp,538505984} \enddata{bp,538505984} \view{bpv,538505984,1,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538478900}