ð The NewtonScript Programming Language Apple Computer, Inc. Apple Computer, Inc. ALL IMPLIED WARRANTIES ON © 1996, Apple Computer, Inc. 20525 Mariani Avenue THIS MANUAL, INCLUDING All rights reserved. Cupertino, CA 95014 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS No part of this publication or the 408-996-1010 FOR A PARTICULAR PURPOSE, ARE software described in it may be Apple, the Apple logo, APDA, LIMITED IN DURATION TO NINETY reproduced, stored in a retrieval AppleLink, LaserWriter, (90) DAYS FROM THE DATE OF THE system, or transmitted, in any form Macintosh, and Newton are ORIGINAL RETAIL PURCHASE OF or by any means, mechanical, trademarks of Apple Computer, THIS PRODUCT. electronic, photocopying, Inc., registered in the United States recording, or otherwise, without and other countries. Even though Apple has reviewed this prior written permission of Apple The light bulb logo, MessagePad, manual, APPLE MAKES NO Computer, Inc., except in the normal NewtonScript, and Newton Toolkit WARRANTY OR REPRESENTATION, use of the software or to make a are trademarks of Apple Computer, EITHER EXPRESS OR IMPLIED, backup copy of the software. The Inc. WITH RESPECT TO THIS MANUAL, same proprietary and copyright ITS QUALITY, ACCURACY, Adobe Illustrator and PostScript notices must be affixed to any MERCHANTABILITY, OR FITNESS are trademarks of Adobe Systems permitted copies as were affixed to FOR A PARTICULAR PURPOSE. AS A Incorporated, which may be the original. This exception does not RESULT, THIS MANUAL IS SOLD registered in certain jurisdictions. allow copies to be made for others, “AS IS,” AND YOU, THE whether or not sold, but all of the FrameMaker is a registered PURCHASER, ARE ASSUMING THE material purchased (with all trademark of Frame Technology ENTIRE RISK AS TO ITS QUALITY backup copies) may be sold, given, Corporation. AND ACCURACY. Helvetica and Palatino are or loaned to another person. Under IN NO EVENT WILL APPLE BE registered trademarks of Linotype the law, copying includes LIABLE FOR DIRECT, INDIRECT, Company. translating into another language or SPECIAL, INCIDENTAL, OR format. You may use the software on ITC Zapf Dingbats is a registered CONSEQUENTIAL DAMAGES any computer owned by you, but trademark of International RESULTING FROM ANY DEFECT OR extra copies cannot be made for this Typeface Corporation. INACCURACY IN THIS MANUAL, purpose. Simultaneously published in the even if advised of the possibility of Printed in the United States of United States and Canada. such damages. America. THE WARRANTY AND REMEDIES The Apple logo is a registered SET FORTH ABOVE ARE EXCLUSIVE trademark of Apple Computer, Inc. AND IN LIEU OF ALL OTHERS, Use of the “keyboard” Apple logo ORAL OR WRITTEN, EXPRESS OR (Option-Shift-K) for commercial IMPLIED. No Apple dealer, agent, or purposes without the prior written employee is authorized to make any consent of Apple may constitute modification, extension, or addition to trademark infringement and unfair LIMITED WARRANTY ON MEDIA this warranty. competition in violation of federal AND REPLACEMENT and state laws. Some states do not allow the exclusion No licenses, express or implied, are If you discover physical defects in the or limitation of implied warranties or granted with respect to any of the manual or in the media on which a liability for incidental or consequential technology described in this book. software product is distributed, APDA damages, so the above limitation or Apple retains all intellectual will replace the media or manual at no exclusion may not apply to you. This property rights associated with the charge to you provided you return the warranty gives you specific legal rights, technology described in this book. item to be replaced with proof of and you may also have other rights This book is intended to assist purchase to APDA. which vary from state to state. application developers to develop applications only for licensed Newton platforms. 11/95 Contents Figures, Tables, and Listings ix Preface About This Book xi About the Audience xi Related Books xi Sample Code xii Conventions Used in This Book xiii Special Fonts in Text xiii Syntax Conventions xiv Developer Products and Support xv Undocumented System Software Objects xvi Chapter 1 Overview 1-1 Introduction 1-1 Semantic Overview 1-2 Expressions 1-2 The Object Model 1-2 Data Types and Classes 1-3 Scope 1-4 Extent 1-6 Garbage Collection 1-6 How Is NewtonScript Dynamic? 1-7 Basic Syntax 1-8 Semicolon Separators 1-8 In-Line Object Syntax 1-9 Character Set 1-9 Comments 1-10 A Code Example 1-10 Compatibility 1-11 iii Chapter 2 Objects, Expressions, and Operators 2-1 Objects and the Class System 2-1 Classes and Subclasses 2-3 Immediate and Reference Values 2-5 The NewtonScript Objects 2-8 Character 2-8 Boolean 2-9 Integer 2-10 Real 2-11 Symbol 2-12 String 2-13 Array 2-15 Array Accessor 2-16 Frame 2-17 Frame Accessor 2-19 Path Expression 2-20 Expressions 2-22 Variables 2-23 Local 2-23 Constants 2-26 Constant 2-26 Quoted Constant 2-28 Operators 2-29 Assignment Operator 2-29 Arithmetic Operators 2-31 Equality and Relational Operators 2-33 Boolean Operators 2-34 Unary Operators 2-35 String Operators 2-36 Exists 2-37 Operator Precedence 2-38 iv Chapter 3 Flow of Control 3-1 Compound Expressions 3-1 If…Then…Else 3-2 Iterators 3-3 For 3-4 Foreach 3-6 Loop 3-10 While 3-11 Repeat 3-12 Break 3-13 Exception Handling 3-13 Working with Exceptions 3-14 Defining Exceptions 3-15 Exception Symbol Parts 3-16 Exception Frames 3-16 The Try Statement 3-18 Throwing Exceptions 3-19 Throwing an Exception to Another Handler 3-20 Catching Exceptions 3-21 Responding to Exceptions 3-24 Chapter 4 Functions and Methods 4-1 About Functions and Methods 4-1 Function Constructor 4-2 Return 4-3 Function Invocations 4-3 Message-Send Operators 4-4 Call With 4-6 Global Function Declaration 4-7 Global Function Invocation 4-8 Passing Parameters 4-8 v Function Objects 4-9 Function Context 4-10 The Lexical Environment 4-10 The Message Environment 4-11 An Example Function Object 4-13 Using Function Objects to Implement Abstract Data Types 4-15 Native Functions 4-16 Chapter 5 Inheritance and Lookup 5-1 Inheritance 5-2 Prototype Inheritance 5-2 Creating Prototype Frames 5-2 Prototype Inheritance Rules 5-3 Parent Inheritance 5-4 Creating Parent Frames 5-4 Parent Inheritance Rules 5-5 Combining Prototype and Parent Inheritance 5-6 Inheritance Rules for Slot and Message Lookup 5-7 Inheritance Rules for Testing for the Existence of a Slot 5-9 Inheritance Rules for Setting Slot Values 5-9 An Object-Oriented Example 5-11 Chapter 6 Built-In Functions 6-1 Compatibility 6-2 New Functions 6-2 New Object System Functions 6-2 New String Functions 6-3 New Array Functions 6-3 New Sorted Array Functions 6-3 New Message Sending Functions 6-4 vi New Data Stuffing Functions 6-4 New Functions to Get and Set Globals 6-4 New Miscellaneous Functions 6-4 Obsolete Functions 6-5 Object System Functions 6-5 String Functions 6-16 Bitwise Functions 6-23 Array Functions 6-23 Sorted Array Functions 6-36 Integer Math Functions 6-45 Floating Point Math Functions 6-48 Managing the Floating Point Environment 6-65 Financial Function 6-69 Exception Functions 6-71 Message Sending Functions 6-73 Data Extraction Functions 6-77 Data Stuffing Functions 6-81 Getting and Setting Global Variables and Functions 6-86 Miscellaneous Functions 6-89 Summary of Functions and Methods 6-92 Appendix A Reserved Words A-1 Appendix B Special Character Codes B-1 Appendix C Class-Based Programming C-1 What Are Classes Good For? C-1 Classes: A Brief Reminder C-2 Inheritance in NewtonScript C-3 vii The Basic Idea C-3 Practical Issues C-6 Class Variables C-7 Superclasses C-9 Using Classes to Encapsulate Soup Entries C-10 ROM Instance Prototypes C-10 Leaving Instances Behind C-11 Conclusion C-11 Appendix D NewtonScript Syntax Definition D-1 About the Grammar D-2 Phrasal Grammar D-2 Lexical Grammar D-12 Operator Precedence D-16 Appendix E Quick Reference Card E-1 Glossary GL-1 Index IN-1 viii Figures, Tables, and Listings Chapter 1 Overview 1-1 Figure 1-1 A sample data structure 1-4 Listing 1-1 A simple frame 1-3 Listing 1-2 A dynamic example 1-11 Chapter 2 Objects, Expressions, and Operators 2-1 Figure 2-1 NewtonScript built-in classes 2-3 Figure 2-2 NewtonScript code sample 2-6 Figure 2-3 C code sample 2-7 Table 2-1 Characters with special meanings 2-9 Table 2-2 Codes for specifying special characters within strings 2-14 Table 2-3 Special slot names and their specifications 2-19 Table 2-4 Constant substitution work-arounds 2-27 Table 2-5 Operator precedence and associativity 2-39 Chapter 3 Flow of Control 3-1 Figure 3-1 Data objects and their relationships 3-9 Table 3-1 Result comparison for the iterators foreach and foreach deeply 3-10 Table 3-2 Exception frame data slot name and contents 3-17 Table 3-3 Exception frame examples 3-17 Listing 3-1 Exception symbols 3-16 Listing 3-2 The Throw function 3-19 Listing 3-3 Several onexception clauses ordered improperly 3-22 ix Listing 3-4 The onexception clauses properly ordered 3-22 Listing 3-5 Improperly nested try blocks 3-23 Listing 3-6 Nested try block problem fixed using begin and end (shown in bold) 3-23 Listing 3-7 Handling a soup store exception 3-24 Listing 3-8 An exception handler checking the exception frame 3-25 Chapter 4 Functions and Methods 4-1 Figure 4-1 The parts of a function object 4-10 Figure 4-2 functionObject1 dissected 4-14 Chapter 5 Inheritance and Lookup 5-1 Figure 5-1 A prototype frame 5-3 Figure 5-2 A prototype chain 5-4 Figure 5-3 Parent-child relationship 5-5 Figure 5-4 Prototype and parent inheritance interaction order 5-7 Figure 5-5 An inheritance structure 5-12 Chapter 6 Built-In Functions 6-1 Table 6-1 Floating point exceptions 6-65 Table 6-2 Exception frame data slot name and contents 6-72 Appendix B Special Character Codes B-1 Table B-1 Character codes sorted by Macintosh character code B-1 Table B-2 Character codes sorted by Unicode B-7 x PREFACE About This Book The NewtonScript Programming Language is the definitive reference for anyone learning the NewtonScript programming language.