This document is a guide to using Newspeak in the prototype release running on top of Squeak. It acts as a tutorial for the IDE, and to a limited extent, for the Newspeak language as well.
You can read this document sequentially, from start to finish, as a structured tutorial; or, you can just use the FAQ to quickly lead you to specific task oriented sections. If you want to read things in sequence, just begin at the beginning.
Table of Contents/FAQ
How do I open the Newspeak IDE?
How do I open a Newspeak browser?
How do I browse an existing class?
How do I browse senders/implementors?
How do I change the category of a method?
How do I manage a Newspeak window?
What if evaluation raises an exception?
What if I want to get at the platform or IDE namespace from an inspector?
How do I run the Newspeak debugger?
How do I edit the class header?
How do I edit the class comment?
How does the Syntax differ from the Specification, and Why?
How do I deploy an application?
How do I test my deployment code?
Begin at the Beginning
Let’s start by opening the Newspeak IDE. Make sure you’ve installed Newspeak first!
How do I install Newspeak?
On Windows, use the installer. If you have a previous installation, it’s best to uninstall the old one and reinstall. On a Mac, open Newspeak Spur Virtual Machine.dmg, and drag the VM to the Applications folder. Make sure that ns101.image is associated with the Newspeak Virtual Machine. This can be an issue, especially if you have ordinary Squeak installed on your machine as well. On Linux, follow the instructions given in linux-advice.txt.
How do I open the Newspeak IDE?
The directory where you found this document probably includes a file called ns101.image. This is a Newspeak image, and it should be identifiable by its icon, the Newspeak eye (well, it’s big brother’s eye actually):
Click (or double click, as the case may be) on the image file. This will open the IDE; you should see something like this:
The very first thing you should do is save a copy of your image, so your experiments don’t trash the release image you just opened.
At the top of the window, you’ll see a tool bar that looks like this:
The rightmost icon, 
, denotes a drop down menu known as the operate menu.
Choose the option Save Image As … and give the image some other name.
Now we can proceed.
Newspeak currently runs on top of Squeak. If you’re running on Mac OS X or Linux, all IDE windows open up within the main Squeak window. On Windows we use a native GUI binding. Most screen shots in this document show the Windows native binding running on Windows 10 (though some date back to Windows 7).
The screen shot above shows the home page. You can always return to the home page of a Newspeak browser by clicking on the home icon at the top of the browser: 
.
The home page includes links to a variety of useful places, like recently visited classes and packages, the source control page and more. If you look at the list of classes, you’ll see each class has a round icon next to it. The icon tells you which language the class is written in; the current system mixes Smalltalk code with Newspeak. A gray icon
represents Smalltalk. Icons representing Newspeak are labeled with a version number. Golden icons 
represent Newspeak3, which is the currently operational dialect of Newspeak.
Now that we’ve got ourselves a browser, let’s browse some classes.
How do I browse an existing class?
There are several ways to browse an existing class. If you know the name of the class (or some approximation thereof), you can search for it using the search pane in the upper right hand side of the Newspeak browser’s tool bar:
One can also go to the Newspeak source page and look for the class there. We’ll examine both options below.
Searching
You can type multiple search terms, separated by semicolons. The search is case-insensitive, and will find anything that includes the searched strings. You can use * as a wildcard character. If you enclose a search term in double quotes, you’ll only get exact matches.
We’ll search for the class CombinatorialParsing. Type the name of the class into the search pane. This yields a list of classes and a list of method names matching that string.
Every element in the lists is a link, and clicking on it will take us to the corresponding class or method. We can also view one or more of the classes/methods in place, by clicking on the arrow icon to the left of the link. The behavior of the arrow icon is similar to its behavior in the mac finder (or if you use a PC, the plus/minus signs in Windows explorer).
Notice how the links are underlined as you hover over them, just like in a web browser. Click on the link for CombinatorialParsing
The browser now displays the CombinatorialParsing class.
The class presenter has distinct sections for class header information, nested classes, methods and class methods.
Notice the yellow circles in front of each member. These indicate access rights to the member (yellow is the default, for protected; green for public and red for private).
The header information appears at the top with a gray background:
Notice the arrow icon in the top left corner. You can use it to collapse the entire header section:
For now, let’s focus on the nested classes section; this is where most of the content is in this particular class. This is characteristic of module definitions. The slots usually represent the “imports” of the module, and there are typically relatively few module methods.
Each of the nested classes can be either expanded in place using the arrow, or linked to by clicking on the class name. Click on the arrow next to AlternatingParser to see how a nested class can be displayed in context. This is usually convenient with small nested classes.
You should now see something like this:
Now click on the name of the class AlternatingParser. That will take you to a full page display of the class. This is best when dealing with larger classes.
AlternatingParser has no nested classes, but it does have some instance methods. Each of the method names displayed is a link. However, when you click on it, the method opens in place, rather than on a new page.
Clicking on the link again collapses the method display. This shows that link behavior in Hopscotch can be customized. It isn’t very useful to show a method on a separate page. Newspeak methods are usually short, and should never be very long. In any case methods need to be understood in context.
Looking at the method parse:inContext:ifError:, you can see the syntax coloring scheme is deliberately low key. The selector is bold, parameters and local slots are bold gray. The message pattern is followed by an equal sign, and the method body appears between parentheses. This may change in later versions.
Looking more closely at the method link, we see that it is followed by various bits of information:
These elements help answer questions like:
How do I browse senders/implementors?
The number of senders of this message may appear immediately to the right of a method name link. You may see this information being filled in when a browser opens a class it has not displayed before. You do not need to wait for this process to complete. Because gathering this information takes significant time, it is done in the background. The sender information is actually a link.
Another way to get at the sender/implementor information is the speech bubble, 
, which generally denotes references to an entity (who’s talking about me ). In the case of a method, clicking on it brings up a pop-up menu with a list of messages, starting with the method’s selector, and including all messages used inside the method. Choose an item from the menu to get the list of implementors and senders for that message.
Of course, you can also enter a message selector into the search pane. In all these cases, the result is a list like this
How do I delete a method?
At the very right of a method link, you’ll see an icon denoting another drop down menu: 
.
The menu has an option to delete the method.
How do I change the category of a method?
On the right hand side of a method link, to the left of the speech bubble, is the category of the method. Clicking it brings up a menu that lets you choose from all existing categories in the class, or enter a new one.
At the top right of the method section, you’ll notice a set of icons:
The open circle opens up all of the methods listed below. The dot icon does the opposite - it will close all open methods. The rightmost icon (with the number sign) controls ordering. By default, Newspeak methods are ordered by their names. Clicking on this icon will toggle the ordering of the methods between name-based and category based. The circle and dot icons are also used in other presenters (such as the class list) with the same semantics.
Why is some code highlighted in red?
There are two possible reasons: suspect implicit messages or syntax errors.
Implicit messages
The browsers underline suspect identifiers and highlight them in red. For example, if an implicit message is not defined in the surrounding lexical scope, it may be indicate a problem - it may refer to an undefined message. On the other hand, it may be an inherited method. Unlike most other languages, in Newspeak one doesn’t statically know what methods are inherited, because the superclass isn’t statically known - it is determined dynamically by a message send.
The system uses heuristics to try and guess what methods are likely to be inherited. Currently, if any class has been computed based on the class declaration of the method, its superclass is checked for potentially inherited methods. These methods aren’t highlighted.
In the case of a new class declaration, no such run time data is available, and so you may see spurious highlighting. Once you’ve run some code, it will go away. On the other hand, the highlights may indicate typos, or truly undefined methods, such as missing imports.
Syntax Errors
The syntax colorizer analyzes your code as you type. If, at any point, the syntax is malformed, it will mark the downstream code in red.
This concludes our review of browsing methods.
Let’s navigate back to the original class. It’s time we looked more carefully at navigation in the IDE.
How do I navigate in the IDE?
The top of the IDE browser window shows a number of controls, some of which are reminiscent of a web browser. The back and front buttons
behave just as you’d expect. The two little drop down menu icons surrounding these
give you a menu of all the places on the browser stack, below or above the current location. You’ve already seen the home button. Perhaps the most useful feature is the history button:
It acts much like the history feature in a web browser. It takes you to a page that holds your browsing history for this particular browser, latest location on top:
Click on any link on the page to go to that location. You’ll find it just as you left it - with subpanes open, unaccepted edits still preserved etc. This means you can leave any view to go to another, regardless of its state. Interaction with the browser is modeless. It also means that you are never more than two clicks away from any place you’ve browsed - one click to the history, and one click from there to any prior destination.
In the context of an IDE, this feature is actually much more useful than in typical web browsing, because you tend to build up a small working set of places you visit while working on code - a few classes, methods etc. that you keep bouncing between.
How do I erase my history?
After completing a task, you may want to eliminate it from your history to prevent clutter building up. To erase the history, click the Forget All button on the history page.
Or just close the browser and open a new one. You can also clean out individual history entries using the forget link at the right of each entry.
One more thing while we’re on the topic of managing the browser
How do I manage a Newspeak window?
Same as any other window. In Squeak, you’ll find these icons on the right hand side of the window title bar:
The green one maximizes, the orange one minimizes, and the blue one provides a drop down menu. Most of the menu entries are standard, but the browser provides unusual options for inspecting the GUI.
How do I inspect the GUI?
Use the browser’s meta menu, which is marked with this icon: 
.
The meta menu has two options for inspecting the GUI: Inspect Window and Inspect Application. The latter opens a new browser showing an inspector on the original browser application. Usually this option is more interesting, as that is where the application logic resides. The former is similar, but the inspector is opened on the Window object representing the browser window. You can drill down and find what code implements a given GUI element. In addition, many presenters have an Inspect Presenter option in their drop down menu, which opens up an inspector on the presenter object.
Of course, to utilize these, we need to understand how to inspect an object.
How do I inspect an object?
There are several actions that will open up an inspector. Besides the menu options described above, the Inspect Mixin menu item available in the class header presenter will open up an inspector on the corresponding mixin object. However, the most general way to get an inspector on an object is to evaluate an expression in a workspace.
Whichever way you open an inspector, you’re likely to see a view such as the following:
Each slot of the inspected object is listed in the inspector. It is prefixed by an arrow icon that allows you to view an inspector on the value of the slot in context . Following the slot name is a description of the slot value, which is itself a link to an inspector on the slot value. The gray area at the top of the inspector gives a description of the object being inspected, and a link to its class and its enclosing object. Clicking on the class brings up a class presenter on the class, not an inspector on the class object. If you need to inspect the class object, you can do that by choosing Inspect Class from the drop down menu, whose icon, , you can see at at top right.
How do I evaluate code?
The inspector has an interaction pane in which you can evaluate expressions in the context of the object. Type in an expression (3 + 4 in the example below) and select it. Then hit Ctrl-S (or cmd-S on a mac). A link to the result of the expression is added. You can expand it in place with the arrow icon, or follow the link. You can also use the Evaluate button on the right instead of Ctrl-S/cmd-S.
If you don’t make a selection explicitly, the current line will be evaluated. This is useful for short expressions. This design allows you to have multiple code snippets in an interaction pane and evaluate them as needed. After evaluation, the selection is highlighted so you can see what was evaluated
Note: If you split your expression among several lines, make sure you select it in its entirety.
Of course, you can always evaluate code in an ordinary Squeak workspace - but that would be Smalltalk code, not Newspeak code. However, Newspeak module definitions can be instantiated from Smalltalk; they are available as Smalltalk globals. Since they are stateless, nothing ungood can happen.
Actually, there is something ungood that can happen - our evaluation may raise an exception.
What if evaluation raises an exception?
In that case, rather than a link to the result, you get a link to the debugger. Assume that we have a class BlowUp, with the following method
public provokeBug: b <Boolean> = (
^missing: b with: self
)
Calling BlowUp>>provokeBug: from a workspace gives us the following display:
We can look at the exception in more detail by expanding the item MessageNotUnderstood BlowUp>>missing:with: as shown below:
If we want to debug this computation, we need to open a debugger on it.
What if I want to get at the platform or IDE namespace from an inspector?
Sometimes you need to evaluate an expression that involves an object that isn't accessible from the current scope. Perhaps you need to get at a module you didn’t import.
In this situation, you can use a workspace. A workspace is an object in the IDE that gives access to the IDE's top level namespace, as well as to the platform object and its members.
In inspectors, the backtick (`) is allowed in expressions, and evaluates to a workspace. So you can send messages like
` collections (* note the space after the backtick - it has to be there *)
and get at the collections module of the platform, even if you forgot to import it. This won't work in regular code of course - the backtick was chosen precisely because it is not legal Newspeak syntax. And we don't want to undermine Newspeak's modularity by providing such a back door. However, you the programmer are all-powerful during development. You can get anything you need through the workspace.
How do I run the Newspeak Debugger?
You will encounter the debugger if an uncaught exception occurs during execution. If you evaluate an expression that results in an uncaught exception in a Hopscotch workspace or object inspector, the inspector will catch the exception, as described above. The text describing the exception also serves as a link that opens up a debugger page on the stack of the failed computation. Click on the link, to get a debugger in a new window. The debugger displays the call stack.
Each activation frame is expandable to an activation presenter which allows you to see the method in question and the state of the frame. You can see all this in the screenshot below, where we have two activations open - one for provokeBug: and one for the code we evaluated in the workspace. You'll notice that the Newspeak debugger is unusual in that it allows you to simultaneously view multiple frames, such as caller and callee. The debugger will mark the site of the active message send in blue.
The method is shown on the left, and above it buttons that control stepping etc. The debugger will mark the site of the active message send in blue.
The frame state is shown on the right, and includes the receiver, any parameters and local slots, and the contents of the expression stack. Each of these is identified by name, and has a link to an inspector on the value next to it. These links are expandable in place via arrow icons.
Near the top right hand corner of the activation presenter is an evaluator, where we can evaluate expressions in the context of the activation, just like in an object inspector.
Evaluating an expression produces a link to the result. To the right of that link will be another link, return it. If you click on it, the object in question will be returned as the result of the method, irrespective of its normal course of computation.
You may use the method presenter on the left as you usually would; you may edit the method and save the changes for example. This will discard all activations above the edited method, and restart the method at its beginning.
In our case, we can see that the problem is that missing:with: is not defined. Expand the top frame on the stack, to see the doesNotUnderstand: method.
If the activation involves the method doesNotUnderstand:, the drop down menu at the right will have an option to declare the missing method semi-automatically.
You will be transported to a class browser page for the class of the receiver, with an editor open on a new method with the appropriate name. The system will also guess types for the parameters based on the actual arguments that had been passed.
Once you’ve edited the method to your satisfaction and saved it, you can return to the debugger and/or press the Continue button at the top to proceed with the computation.
You may also restart the method using the activation’s menu. This menu also provides the option to unwind recursive calls of a method. This is useful when you have stopped in an infinite recursion; you want to pop all recursive activations off the stack and get back to the very first activation of the method, where you can correct the method and then proceed with execution using the Continue button.
How do I open a workspace?
On the home page, you can click on the link labeled Workspaces. This will take you to the workspaces page. If there are no workspaces yet, one will be created and opened in place. If there is exactly one workspace it will be opened in the same way. Otherwise, you will be presented with a list of all existing workspaces to choose from.
You can create new workspaces by clicking the plus button. Workspaces are identified by cheerful names, such as Workspace_1 etc. You can then navigate to a given workspace by clicking on its link in the workspaces page
A workspace allows you to evaluate code and provides you with access to the IDE’s top level namespace. The IDE namespace gives you access to all top level Newspeak classes loaded into the IDE. It also supports access to the Newspeak platform object via the name platform. In addition, you can use the name ide to gain access to the IDE namespace itself.
Finally, workspaces provide direct access to all the modules the Newspeak platform provides; e.g., the collections module is available via the name collections, the streams module via the name streams etc.
Each workspace has its own unique class. You can access it via the drop down menu located just under the Evaluate button. This allows you to define slots (sometimes known as workspace variables in other systems) for the workspace. Likewise, you can define workspace specific methods or even nested classes. All of these are treated exactly like members of any other class.
You can also define methods for the workspace class directly in the workspace:
the Methods section at the bottom of the workspace works exactly like it does in a class browser. More on this below.
Back to CombinatorialParsing
Let’s navigate back to the CombinatorialParsing class. We’ve seen how methods and nested classes work, but we haven’t really investigated the class header. The header includes the class comment and slot definitions.
How do I edit the class header?
At the left hand side of the class header section is a link that is labeled as Source. Clicking it transforms the presentation of the header, thus:
One can edit the header source and so add, remove or rename slots, change the primary factory, edit the class comment, edit any initialization code that follows the slot declaration section etc.
You can switch back to the default view of the header by clicking on the Description link.
This concludes the sections dealing with browsing existing code. Now we consider creating new code.
How do I create a new class?
Currently, classes are created within namespaces. The IDE maintains a root namespace (called Root). Currently, the root namespace is only allowed to contain subnamespaces called category namespaces, or just categories. Classes can be added to category namespaces. So the first step in creating a new top level class is finding an appropriate category. If you know the category you want to use, you can find it using the search bar, or you can go to the root namespace where you will see it listed.
Otherwise, you need to create a new category. That also requires you to get to the root namespace.
How do I get to the root namespace?
On the home page, you will see a link marked Newspeak sources. This link leads to the root namespace.
How do I create a category namespace?
In the root namespace, click on the plus icon, which looks like this:
.
This brings up an Add Namespace menu item.
If you click on that, you'll be asked to type in the name of the new namespace.
We'll type in NS101
Accept the category name by clicking on the green icon,
. Accepting
will add the namespace and take you back to an updated view of the root.