In a language implementation, there is likely a representation of the class, that probably points to a mixin and a superclass. For the language implementor, this representation of class is called a class factory object. This object is distinct, from the user accessible object that represents the class in the language. So the term class factory object is used to distinguish it from the class itself, but that is a distinction for the implementor, not the user.

Informally, when speaking from the language user's perspective, we often refer to this user accessible object as the class, or the class object, or the class factory object (all names for the same thing).

So I suppose when talking about the language, we should use the term "class" or perhaps "class object" for this thing.

See the Newspeak specs, section 6.4. Also see 3.5 which discusses methods and what defines them (mixins) as opposed to their declarations (again, essentially source).

• Action: In a new browser tab, open the online Newspeak IDE at https://newspeaklanguage.org/samples/primordialsoup.html?snapshot=HopscotchWebIDE.vfuel
• Result: The Newspeak IDE opens, similar to
  • Note: The "Did you know" section is a ever-changing hint system
• Action: Click "Newspeak Source" in
• Result: A new page opens, showing Newspeak classes, similar to
  • Note on the result: In the result, you should NOT see classes named CounterApp or CounterUI. If you do, you have most likely run through this tutorial before, and the classes are already in your browser local storage. To clean any local changes saved locally for the online Newspeak, you can clean them in the browser local storage, or click the 3-dot on the class line, and Remove the class.
• Motivation for the next action: We want to build the sample app CounterApp. We choose to build it simply by downloading and compiling existing source files in the Newspeak github repo.
• Action: In the top right of the page (in the same line where we see "Root +") , click the vertical 3-dot button on the far right.
• Result: A popup shows
• Action: Click "Compile File(s)". This will ask us to select files stored on disk, and compile them.
• Result: OS file browser opens, and ask us to select files in the operating system file browser.
• Action: Navigate to the directory where we checked out the Newspeak github repo, OR where we saved the source for the .ns files (see Prerequisites of this section). Select CounterApp.ns and CounterUI.ns
• Result: The classes from the selected .ns files compile, and show in your IDE. In your class list (the list under Root +), you should now see a section similar to this
  • Note 1: We have loaded the code of the CounterApp.ns and CounterUI.ns classes into Newspeak by running "Compile file". Alternatively, we could have added the classes through the IDE by clicking the "Root-+" button and typing or pasting the code in. Instead, we choose to load pre-existing files at the moment to concentrate on the process, not the code.
  • Note 2: click the CounterApp or CounterUI link. This shows the corresponding class.
  • Note 3: The CounterApp shows links to [deploy] [configuration] [run] [debug]. Why do only the "app" classes such as CounterApp (and no other classes) show the [deploy] [configuration] [run] [debug] links in the Newspeak IDE? The IDE decides to show those links based on the presence of a convention method #packageUsing: manifest. See Newspeak modules API summary for what makes a module an App, a Library, or a TestConfiguration, and how the IDE handles the API.
• Action: To save the classes we added, (CounterApp or CounterUI) in the browser local storage explicitly "now", click the diskette "Save" button
• Result: The two classes are stored in the browser local storage. To read more about details of the browser local storage, see Chapter Saving changes in Newspeak.
• Action: click the [run] link beside the CounterApp. This runs the code in the app (specifically, the CounterUI code).
• Result: The counter app opens and runs in the same browser tab; it should look like this: The code presents a counter (integer), and 3 buttons, which actions are to "increment", "decrement" and "reset" the counter.
• Action: click "increment"
• Result: counter increments by one.
• Note: We can click [debug] instead of [run] and a debugger will open.

Summary:

• We have shown how to code, run, and debug, a Newspeak app CounterApp in "development mode", inside the online Newspeak IDE.
• Newspeak online is similar to (but we dare say superior to) running, in "development mode", a Java, Android or Flutter application in IntelliJ, Eclipse, Visual Studio, Atom, Emacs, vi, or any IDE.
• Your changes are always stored, as long as you "Accept". See Chapter Saving changes in Newspeak for saving changes details.

Next:

• Let's pretend the CounterApp is useful, usable, and production ready.
• How do we deploy it for us to use it as a browser app "in production mode"? Read the Chapter Deploy CounterApp as standalone app into local Newspeak webserver section.

Top level classes in the IDE are crucial because their instances are Newspeak modules. A Module can play a role of an Application or Library.

I the IDE, click on the "Newspeak Source" button. We see the word Root on top left, and below, a list of class names.

First: what is the "Root" on the top? According to documentation, this is the IDE's top namespace - Root is the name of the namespace.

In Newspeak, each class in the screenshot above (AccessModifierTesting, and below) is called a top level class, and it belongs to the Root namespace of the IDE. Each instance of a top level class is referred to as a module, see Discussion of Modules.

In software in general, Modules are related to namespaces in a way that we cannot precisely define here. See Discussion of Namespaces as well. But we can say this about modules: Modules are meant to be artifacts providing some useful non trivial functionality, without needing any help - apart from the help of "dependencies" - that is, help of other modules intended to provide some "sub functionality". There must be a way to package and distribute modules.

In Newspeak, modularity is one of the key concepts. Modules, the key constructs of modularity, are based on class nesting.

Lets again quote from Modules as Objects in Newspeak:

In Newspeak, nor is there a global namespace. Modularity in Newspeak is based exclusively on class nesting. There are no separate modularity constructs such as packages. Top level classes act as module definitions, which are independent, immutable, self-contained parametric namespaces. They can be instantiated into modules which may be stateful and mutually recursive.

Newspeak uses the following definitions (from the section Newspeak terminology):

• Module declaration is the source code of any top level class
• Module definition or Module class is any top level class object. We will use the terms interchangeably depending on context.
• Module or Newspeak module is an instance of any top level class.

So, an instance of any class shown on the top level in the IDE is a module.

Newspeak Module is not only an empty new term. It turns out, that, by nesting other classes, modules also satisfy what we normally want from software modules: they are self-contained elements of data and functionality which can be distributed or executed, given expected API. To understand more about how expected API determines a module's role, see Newspeak modules API summary. In addition, Newspeak modules cannot cross-access each other when deployed - unless one module explicitly requests another module or module class during packaging and building.

Namespaces in softwware in general provide grouping and organization of artifacts used in programs (packages, classes, or functions). A Java namespace example would be "org.mypackage". All classes in that package belong to the namespace "org.mypackage". Python concept of a package is similar.

Most platforms and languages have a concept and need for a global namespace. How can we describe it? Perhaps a good high level description of a global namespace would go like this: In a program, we want to use other programs, classes, functions, or what have you, created by other developers, at compile time or runtime, depending on the platform. If our Java program is in the "org.mypackage" and a class "org.mypackage.MyClass wants to use "org.apache.SomeClass", then at compile time or at runtime, the platform (Java, but e.g. Python is equivalent) has to find "org.apache.SomeClass". How does it do that? By looking through CLASSPATH or PYTHONPATH. The CLASSPATH or PYTHONPATH play the role of the global namespace! All other namespaces, such as "org.apache" belong to the global namespace. In a Java or Python program, any class and it's instance at runtime has access to artifacts on the CLASSPATH or PYTHONPATH. For example, this code

// In org.mypackage.MyClass: 
Object newObject = Class.forName("org.apache.SomeClass").newInstance();

Creates an instance of "org.apache.SomeClass" at runtime by finding it on CLASSPATH - on the global namespace of Java. As long as the classloader can find "org.apache.SomeClass" on the CLASSPATH, and SomeClass has the default constructor, an instance can be created - without "org.apache.SomeClass" ever being imported to the code. Instances of classes in "org.mypackage" can create instances of classes in "org.apache" and vice versa, without importing each other. This is why the availability of the global namespace harms modularity, as it enables "hidden dependencies" like the one described in this short Java example!

The Newspeak language does not have a global namespace but the Newspeak IDE does have a global namespace - the Root on top of the IDE we have seen in the previous chapter. There is some discussion regarding why that is in Namespaces and existence of global namespace in the IDE.

The consequence of no global namespace in the language is that, at runtime (outside of IDE), a Newspeak module class must declare it's dependency on another module class (or module) explicitly, by storing the dependency module definition (or dependency module) on it's module slot! This storing of a dependency on a slot can be looked at as "importing" the dependency. Example of code where showing all classes needed at runtime are "imported" by holding on to them on module slots:

• In 4. Hello World Application using 3rd party dependency the HelloTranslatorLib holds on to the HelloTranslator
• In 4. Application module: API of module that needs to be distributed as an App TranslatorWithDepApp holds on to the TranslatorWithDep, and TranslatorNoDep.

The dependency management goes deeper: A distributable module (Application or Library object), when instantiated and serialized on the source system, 'carries along', ALL imported dependencies on it's module slots - classes or instances of other classes from it's slots. After deserialization on the target system, it has all the code and objects it needs to work on the target system. (The Platform object is an exception: it is assumed to exist on both the source the target platform with same API, and it is not a part of the serialized artifact.)

For the more complete language discussion of what a namespace is, and why a global namespace is not needed in the Newspeak language, see https://gbracha.blogspot.com/2008/12/living-without-global-namespaces.html.

The existence of the Root namespace in the Newspeak IDE describes one of my surprises - although I realized only later that I should be surprised. I should have been surprised because there are many places in the Newspeak documentation describing that "Newspeak has no global namespace". So I was wondering why this "Root", is not a global namespace? Turns out that it is! But there is an important distinction, the Newspeak language does not have a global namespace while the Newspeak IDE does - it's name is "Root".

Next we can ask, why does the Newspeak IDE need a global namespace (Root), while the Newspeak language does not have one, in fact very intentionally does not have one? The reason is, when working in the IDE, we want cross-access between the module classes (the top level classes). At runtime, that is, after packaging and deployment of any Newspeak module (outside the IDE), only the modules intended to be used by other modules should be available! Modules cannot freely cross-use each other, because there is no global namespace to find each other (or each other's class). If a moduleA needs to use moduleB, moduleA must explicitly ask to include moduleB's definition (the class of moduleB) at the packaging stage. See also the text and links in Dependencies and modularity: Important but hard to "get" at first.

This section starts an IDE-guided step by step discovery of some core aspects we encounter when we first dig into the IDE and the classes on top: Newspeak class structure, app and library API, platform and manifest.

Let us expand each top level class in the "sources" screenshot above. We expanded two classes (named ActivationMirrorTestingConfiguration and AliensForV8) in the screenshot below:

Continue reading what we can learn from looking at the expanded classes.

Let's examine the structure of top level classes in the Root list etc.

Let's drill into the ActivationMirrorTestingConfiguration as an example. Clicking on the module name link, an ObjectPresenter presents an instance of the class. Why to present an instance, and not a class? The motivation is liveliness, spoken about in many places here. Anyway, this is what we are shown:

The structure is described below:

1. The line starting with self shows the instance.
2. There is a collapsible class name section for the class, ActivationMirrorTestingConfiguration with two sub items
   • on top there is the #packageTestsUsing: manifest. This is a method which can be viewed as the "core" or "primary" constructor. In Newspeak, the method is called the Primary factory method, or short Primary factory.
   • a list of Slots. Slots are like "member variables". Slots can only be created in the primary factory method!
3. a list of Classes. Those are nested classes of the class ActivationMirrorTestingConfiguration
4. a list of Instance methods. Those are methods we can call on instances of ActivationMirrorTestingConfiguration
5. a list of Class methods. Those are methods we can call on the class ActivationMirrorTestingConfiguration. They are called factory methods, and they serve as "alternative constructors".

There is a plus ("+ ") symbol in the header of some of them. The reason there is no plus ("+ ") symbol beside slots, is that slots can only be added in the code of the primary factory method. Add a slot from the primary factory method code, and the added slot name will show in the IDE.

We mentioned the methods on the first line of the class declaration such as class ActivationMirrorTestingConfiguration packageTestsUsing: manifest are termed the primary factory methods.

The core role of a primary factory method is to produce instances (and declare and initialize their slots). The difference between a primary factory method and a factory method or an instance method is that ONLY primary factory method can declare in initialize slots!

Newspeak language implementation detail: We also mentioned that the primary factory methods are methods on special objects, the 'class factory object'(s). One such special object is created for each class declaration: for example, when a class declaration AMyClass new = ()() is loaded or saved in the IDE, one instance of the 'class factory object' named AMyClass is created. The role of the special object AMyClass is to produce instances of class AMyClass.

The platform objects (objects that represent the Newspeak system), and possibly the dependencies (classes that need to be "imported" from the manifest) are passed to the primary factory method and held on slots. From there, they are available to all nested classes and nested objects of the top level instance!

The primary factory method names on the top level classes have eerily similar signatures. I was asking myself why, what do they have in common. So I listed examples of the primary factory method names. Here is the list of the primary factory methods on some top level classes:

class AccessModifierTesting                 usingPlatform:       platform  testFramework: minitest = (| etc
class AccessModifierTestingConfiguration    packageTestsUsing:   manifest = (| etc
class ActivationMirrorTesting               usingPlatform:       platform minitest: m = (| etc
class ActivationMirrorTestingConfiguration  packageTestsUsing:   manifest = (| etc
class ActorsForPrimordialSoup               usingPlatform:       platform = (| etc
class AliensForV8                           usingPlatform:       platform = ( etc
class Browsing                              usingPlatform:       platform ide: webIde = ( etc
class Collections                           usingPlatform:       platform = ( etc
class CollectionsForPrimordialSoup          usingInternalKernel: ik = ( etc
class CombinatorialParsing                  usingPlatform:       platform = ( etc
class RuntimeForV8                          packageUsing:        manifest = ( etc
class Streams                               usingPlatform:       platform = ( etc

We can see that the primary factory methods accept, at first position, one of 2 arguments

• platform
• manifest

If the constructor first argument is platform, the constructor name always starts with

• #usingPlatform: platform

If the constructor first argument is manifest, the constructor name is always one of

• #packageUsing: manifest
• #packageTestsUsing: manifest (for tests only)

Clearly, platform and manifest, must be significant!

What are those objects? And what do they contain, why are they significant, and what role do they play in Newspeak?

TL;DR: Recall that a module is an instance of a top level class in IDE. A module can be classified ad General, Application, or Library module - see the Newspeak modules API zoo.

• manifest is used by Application and Library modules for packaging (creation and serialization for distribution). The manifest is passed to the Application and Library primary factory. The primary factory pulls (imports) from the manifest all class declarations the instance depends on. All imported classes are stored on the Application and Library instance slots, in which they are serialized and distributed. This allows any Newspeak Application or Library to be a self-contained package (serialized instance), which includes everything it depends on.
• platform is needed at runtime whenever an instance needs access to another module (top level class). In Newspeak, the only way for module to gain another module is through platform. Also see the section Modules: Application, Library, TestConfiguration, General.

Why are the platform and manifest objects so important to appear again and again in the top level classes' factory parameters, as seen in Primary factory methods ?

The answer is somewhat common for manifest and platform, so we describe their role in this common section.

The common need for both manifest and platform stems from modularity. But what does that mean?

In Newspeak terminology, we saw that the modules are DEFINED AS instances of top level classes.

And we saw that there is no global namespace in Newspeak. Modules need other objects (dependencies) to do useful work. In Newspeak, for a module to "contain" ANY dependency, such dependency must be on the module instance slot (slot is like a member variable). Also, at the point of the module construction we MUST supply such dependency. Because only the primary factory can define slots, the module primary factory must be passed everything the module needs from outside.

This is where platform and manifest come in. They are "special" in the sense that they supply objects and classes needed by the module. But each is needed at a special point of the module lifecycle:

• The manifest object is needed at packaging step on the system where we create the package: manifest is passed to the module packaging method such as #package(Something)Using: manifest which packages dependencies that need to be carried over from the system we are packaging on, to the module artifact that is copied to the deployment platform.
• The platform object is needed on the deployment step on the deployment system, to instantiate the module by #(buildSomething)usingPlatform: platform or perform the module work and passed there to the runtime method such as or main: platform args: args.

We can reword the above as follows:

We already know that any Newspeak object can have only one "slot declaring constructor" (called primary factory) in it's API. But, as a module needs both platform and manifest, how can we ensure a module has both available? This is done by convention methods, that are either a primary factory or a regular instance method, depending whether the module is an App, Library, and Test configuration module OR a General module.

• App, Library, and Test configuration modules (but not "General modules") have a primary factory passing a manifest in it's API. This primary factory is named similar to #package(Something)Using: manifest. This factory is called on the system where we create the package to "import" objects and/or their classes during packaging (by placing them to the package artifact which can be delivered over to the runtime system).
• Any "General" modules (not App, Library, or Test configurations) have a factory passing a platform in it's API. This primary factory is named similar to #(buildSomething)usingPlatform: platform. This factory is called on the runtime system for module instantiation. An App, Library, and Test configuration module (where the primary factory is already taken by presence of method passing platform such as #package(Something)Using: manifest) would typically also have this method in it's API, but NOT as a factory, rather as an instance method.

To read more details about which method is used on which module type, and why, follow the next section Modules: Application, Library, TestConfiguration, General.

In a nutshell,

• We need manifest classes for packaging. Manifest provides the classes needed to "bring along" (import) in the package. Those "bring along" or "import" classes may not exist on the end-user system, so they need to be added to the package!
• We need platform for execution. Platform provides instances of "system classes". Those "system classes instances" are assumed to exist on the end-user system, so we do not need to bring them along in the package!

In computing, any program in most languages on most Operating systems must be able to start execution, then load or link libraries, then use them; in addition, any program should be packageable for distribution. We term each such ability a role. In computing, we tend to separate artifacts into (executable) Application and (linked) Libraries. We can itemize such roles as follows.

1. An Application must be able to start execution on the platform to which it is targeted (here, platform in the sense of "Linux platform", "Android platform", "Windows platform", and in our situation, the "Newspeak platform").
2. A Library must be able to be load and link other libraries, at least in principle, by the caller Application or another Library on that platform. The library used by an Application or another Library is often called a dependency. The term used implies that the Library is found and connected to the Application or Library which is using it. We can call this ability buildDependencies
3. In addition, we should be able to package both the Application and the Library for distribution (deployment). Packaging includes instantiation and serialization.

So an Application needs to provide a facility (API, method) to perform /role/s 1 and 3. A Library needs to provide a facility to perform /role/s 2 and 3.

From the generic /role/s above, both Application and Library need some way to perform the /role/s. Methods perform /role/s, so we need some "convention methods" to perform the roles 1, 2, 3. Such "convention methods" represent a public API, described in the following section.

Following the basic /role/s from the previous section 7.6.1 in mainstream computing, we need "convention methods" to perform the /role/s 1, 2, 3 in the previous section. We choose to name such "convention methods" as follows: (the names are arbitrary, but conventional, and represent the APIs understood on the platform)

• For an App:
  • To perform role 3, instantiateForPackaging, let's call the method #package.
  • To perform role 1, start execution, let's call the method #main
• For a Library:
  • To perform role 3, instantiateForPackaging, let's call the method #packageLibrary
  • To perform role 2, buildDependencies, let's call the method #build

A mainstream system has the advantage of access to a global namespace - generally a filesystem via a PATH, CLASSPATH, PYTHONPATH or similar. We discussed that earlier as well. Inside any of these methods, during execution, the program can look and find various artifacts it needs on the platform. If we start the method equivalent to "#main" in Python, inside #main there may be a line of code such as from graphics import Rectangle. So we need the Rectangle class. No problem, we go to the classpath, find the namespace graphics, there lives the module graphics, and the class Rectangle is there. We load it and continue.

In Newspeak, everything is done via objects. So Application and Library must be an object. Further, Newspeak starts all operations on the instances of top level classes, that is, on modules. For terminology, see Newspeak terminology, also Discussion of Modules.

But Newspeak cannot load anything globally. If the API for the Application and library was as defined above in Application and library API in computing, applications would not run as there would be no way to bring anything from a construct such as the CLASSPATH. In more detail if the App's #main method defined above was to run, and Newspeak would discover the equivalent of "import" (which is slot creation in primary factory methods), it would not be able to find the "imported" dependency module. It does not have the global namespace or access to the PATH, CLASSPATH, PYTHONPATH or similar.

The solution is, during instantiation of Newspeak Application and Library objects, all the runtime dependencies (or rather their classes) are passed to the primary factory methods and stored on slots, to be "carried along" in the objects for serialization and distribution. The dependencies are passed to the factory methods in the manifest object, which has all the top level classes in it. See The manifest object.

Once an Application and Library object exists, it is serialized on the source system, and sent to a different (target) system where it is deserialized. At that point, on the target system, it needs to be used to be useful. Newspeak defines methods for such use. These methods accept an object which is TYPICALLY NOT part of the serialized instances: The platform object. It encapsulates the common capabilities of the Newspeak system on all systems (platforms, hence the name). See The platform object.

Nespeak extends the signatures of /role/s 1, 2, 3 from previous chapter to provide the "carry over" (imported) classes from manifest, and system classes from platform, Newspeak uses the following signature names:

• For an App:
  • To perform role 3, instantiateForPackaging, Newspeak uses the primary factory method #packageUsing: manifest.
  • To perform role 1, start execution, Newspeak uses the instance method #main: platform args: args
• For a Library:
  • To perform role 3, instantiateForPackaging, Newspeak uses the primary factory method #packageLibraryUsing: manifest
  • To perform role 2, buildDependencies, Newspeak uses the instance method #buildUsing: platform

These four methods are core "convention methods" for all Newspeak modules which we want to behave as either Apps or Libraries.

See also How do I bring dependencies into modules to be distributed?

This section is a summary and reference of Application, Library, and Test configuration modules API in Newspeak. It is sort of the pinnacle of the parent section about Apps and Libraries.

As explained in the previous section, in Newspeak, compared to a mainstream platform which has access to global namespace, we have to change the API signatures described in Application and library API in computing by passing the platform and the manifest object. We also change the signatures to match actual Newspeak names.

Here are the APIs which define whether a Newspeak module is an App, a Library, a TestConfiguration, or a General module. The /role/s 1, 2, 3 refer to the /role/s (roles) in Application and library API in computing. Please note that Newspeak is not using the terms "App module", "Library module", "General module", or "TestConfiguration module". I find such classification of modules useful though.

• Newspeak Application module is defined by the presence of:
  • Primary factory method #packageUsing: manifest which performs role 3, instantiateForPackaging.
    • Implementations should
      • pull needed classes from the manifest and place then on slots. optionally instantiate the classes from manifest unless they need platform.
      • instantiate Libraries from manifest and store resulting objects on slots using a3RdPartyDependency = A3RdPartyDependency>>#packageLibraryUsing: manifest.
  • Instance method #main: platform args: args which performs role 1, start execution.
    • Implementations should instantiate, from slot classes and platform objects, all object needed to run the app, then call methods on them which perform "running the app"
• Newspeak Library module is defined by the presence of:
  • Primary factory method #packageLibraryUsing: manifest which performs role 3, instantiateForPackaging.
    • Implementations should do the same as Application does in #packageUsing: manifest - see above.
  • Instance method #buildUsing: platform which performs role 2, buildDependencies
    • Implementations should build, then return a working instance of the module we want to distribute, NOT the Library instance on which this #buildUsing is defined!! See example in How do I bring dependencies into modules to be distributed?
    • Important note: If we want to distribute an existing module MyModule1 (this may or may not be a library module!), we have to either:
      • Convert MyModule1 to MyLibrary1
      • create a separate top level Library Module, MyModule1Lib for the purpose of distributing MyModule1. The #buildUsing: implementation we are talking about here, is the "MyModule1Lib>>#buildUsing:" method! - NOT the "MyModule1>>#buildUsing:" method, as this may not even exist on MyModule1!
• Newspeak TestConfiguration module by convention ends with "Configuration", and is defined by the presence of:
  • Primary factory method #packageTestsUsing: manifest which performs role 3, instantiateForPackaging
    • Implementations should put on slot the class of the Module being tested.
  • Instance method #testModulesUsingPlatform: p minitest: m which performs role 2, instantiate,
    • Implementations should call return instance of the tested class. Example: ^{AccessModifierTesting usingPlatform: platform testFramework: minitest}
  • Note: Tests, by convention, need two classes to be created. If class MyTestModule has the test methods, MyTestModuleConfiguration must be created. This is the class we are talking about in this section. There are no "convention methods" on the test module MyTestModule.
• Newspeak General module is any other module - any module that does not have any of the above API. General modules do not have any convention API name.
  • However, we often find they have a primary factory method named similar to #usingPlatform: platform [and: otherObjects] which create a working instance. Note that the [and: otherObjects] portion is completely free, it can be named differently.
    • These modules can for example be
      • modules we distribute using the Library Distribution module
      • tests we run using the TestConfiguration module

Note that on Application and Library modules, the methods which perform the packaging, are primary factory methods (manifest is passed to them), while the methods which perform execution or build are instance methods (platform is passed to them). The reason is, a primary factory method is the only method which can store stuff in slots! So any classes needed to be "carried along" for packaging (pulled from manifest then "imported" on the target platform during construction), must be placed on slots during the primary factory method call.

Note that the IDE uses the presence of certain methods to show appropriate action links. For example,

• If the method #packageUsing: manifest exists in the module, IDE shows links to [deploy] [configurations] [run] [debug]
• If the method #packageTestsUsing: manifest exists in the module, IDE shows links to [run tests] [show tests]

TL;DR: This section shows a table of Newspeak "Module type"s in rows, and "convention method" signatures each "Module type" must provide. Given a "convention method" signature, we know the role or /role/s the method performs. The table is a summary of conclusions of the above section Newspeak modules API summary. For motivation of the need for "convention methods", see the top section 7, in particular it's subsection Modules: Application, Library, TestConfiguration, General,

In general computing there are artifacts, performing /role/s of applications, libraries, and tests. In Newspeak, equivalents of such artifacts are uniform: they are all instances of a specific module. We say that a module instance has a "Module type" in Newspeak, if the module instance has all required "convention method"s for all /role/(s) required by the "Module type".

Terminology: "Module type" is not a formal term in Newspeak. We use the term "Module type" to group module instances according to their "convention methods" - in other words, according to their role/s. Also, in text, we use the brief /Application module instead of Application module type, General module instead of General module type etc.

The table below summarizes, for each "Module type" in Newspeak, the "convention methods" names and the /role/(s) each such method performs.

Notes:

• The headings for "Module type" Library, App, and TestConfiguration are separated from the headings for "Module type" General, and Test as the /role/s differ:
  • The modules of type Library, App, TestConfiguration require multiple roles, provided by two required "convention method"s for each type.
  • The modules of type General and Test only requires the /role/=instantiate, provided by only one required "convention method" for each type.
• For any Application module: When we click the [run] button in the IDE, the IDE calls the Application's primary factory method #packageUsing: manifest, then the instance method #main: platform args: args which runs the app in the IDE. Similarly, when we click on the [deploy] button in the IDE, the same methods are (eventually) called, followed by calling serialization methods, which serialize the instance to bytes and save them as .vfuel file.
• A Library module and an Application module play a similar role. However, an Application module is intended to be packaged, distributed and executed as a standalone App, while an Library module is intended to be packaged, distributed and included in Application modules or other library modules.
• For any General module: The method signatures ARE NOT FIXED BY CONVENTION, they are only softly conventional. That helps humans to distinquish their invocations from nested classes. The signature #usingPlatform: platform [andModule: m1] is an example of a primary factory method which is passed the platform and a dependency which is module m1.
• TestRunner.ns is later packaged(instantiated), then called main:args: which runs Test instances returned from #testModulesUsingPlatform: platform minitest: m

TL;DR: This section provides some guidance of how to code each module type, and convert between them. Conversion is sometimes needed when a General module grows useful and we want to convert it to an Application or Library module.

General module is the most simple case. If our module does not need any dependencies, not even from common classes such as collection:

We need to:

• provide a primary factory method #new

If our module need some other module from IDE, such as collections, we have to pass it the platform object, and potentially other objects or classes our module depends on.

We need to:

• provide a primary factory method #usingPlatform: platform
• OR if another module is needed, provide a primary factory method such as #usingPlatform: platform andModule: translator

API for a module intended to be distributable as a library: In Newspeak, this means such module must be both packageble and distributable - the roles of "packageble" and "distributable" are achieved by implementing the 2 methods below. We call such modules informally Library modules.

In the previous section, we introduced a general module TranslatorWithDep. If we needed this module to be used as a library we could use one of two methods:

1. we either "convert" TranslatorWithDep into a library,
2. or we add a "wrapper library", TranslatorWithDepLib, which will be the module used for distribution.

In this example, we show the second method - we add a "wrapper library", TranslatorWithDepLib for TranslatorWithDep in two steps

1. We add a separate module - the wrapper library with a descriptive name (to make clear it is a library), TranslatorWithDepLib
2. In the new TranslatorWithDepLib, add the following API methods:
   • primary factory method #packageLibraryUsing: manifest, which allows to "import" the TranslatorWithDep and the other needed dependency TranslatorNoDep
   • Instance method #buildUsing: platform, which allows dependencies to be pulled at construction time

Note that in this case, TranslatorWithDepLib#buildUsing: platform must not be added any other arguments. Any "carry along" (imported) classes that may be needed at build time, must be saved on slots in the TranslatorWithDepLib#packageLibraryUsing: manifest primary factory method. See also Newspeak modules API zoo.

This next step describes an example of a module which is intended to be distributable as an App. In Newspeak, this means such module must be both packageble and runnable - the roles of "packageble" and "runnable" are achieved by implementing the 2 methods below. We call such modules informally App modules.

If we need our module TranslatorWithDep to be packagable as an App:

1. Generally, add a separate module with a descriptive name - to make clear this separate module is an App, end the name with the string 'App'.
2. In this separate module, provide the following API:
   • primary factory method #packageUsing: manifest
   • Instance method #main: platform args: args

Note 1:

We sometimes see Newspeak Application modules lacking the #main: platform args: args method. Such modules are used as library modules.

Note 2:

Compare the parallel role between the following methods for a Library module and an Application module:

The primary factory methods for Library and Application have similar names, both serve to package the library or the app on the "source" system.

The instance methods serve to build (for Library) or execute (for App).

If an Application uses a Library, the library's (build) #buildUsing: platform would be called in the App's #main: platform args: args method to build (create) the library's instance.

This section will show several versions of a 'Hello World' program in Newspeak. Each version uses a different method. The initial versions are due to Gilad Bracha's answer on the Newspeak group https://groups.google.com/g/newspeaklanguage/c/Cq2Ej0_THew

All 'Hello World' programs are created in the Newspeak online IDE at https://newspeaklanguage.org/samples/primordialsoup.html?snapshot=HopscotchWebIDE.vfuel, then following the steps.

Workspace is like the command line or REPL in Newspeak. We can send 'Hello World' from there as a String>>#out message.

Steps to run Hello World from Workspace

• Open Workspace
• Type there (including quotes) 'Hello World from Workspace' out
• Select the text
• Press "Shift+Enter" - this takes the selected text and evaluates it's expressions. The single expression is the message #out send to the string object.
• Notice that 'Hello World from Workspace' appears both right below the line, and also at the bottom of the page. The text at the bottom of the page was appended at the end of the DOM. We will see text showing at the bottom of the page again in all non-Application examples.

TL;DR: In this section, we will build a Hello World which is a module (an instance of top level class as we know already). The code for this module is already in https://github.com/mzimmerm/newspeak-doc/tree/main/newspeak---a-few-notes-code/hello-world/2-as-general-module. To skip the coding details above, we can download the .ns file(s), then "Compile file(s)" to load the fully finished code from there; the loaded class will appear in the IDE.

The Newspeak modules API summary section would classify this module as "General" module, because it does not have any of the special "convention methods" in it's API. The only method of this class is it's default primary factory method #new.

Continuing with the painfully detailed steps to create the Hello World general module in the Newspeak IDE:

• In "Newspeak Source", on the top left, click the "+ " button next to the link "Root"
• In the popup, select "Add Class"

• Replace the text under "Defining a new class" with

  class HelloWorldGeneralModule = (
  (*
   If we Accept this class declaration,
   or if we click on the class link,
   the "Hello World" string shows on the bottom.
    - How did it get there?
      - After click on the class link, the IDE prepares some things to present the class.  In the IDE, the class is presented inside an instance of the class.  So, the IDE creates an instance of the ~HelloWorldGeneralModule~, by invoking the implicit ~HelloWorldGeneralModule>>#new~ primary factory method.  The method body is executed, calling ~'Hello World ' out~.  ~#out~ is a method on String; it is implemented in the Wasm version to append a ~<div>'Hello World '</div> element to the IDE's HTML document body, thus displaying the string at the end of the IDE's page.
      - Similarly, every time just click on the > expand action to the left of the class name, a new instance is created by the IDE, causing one more 'Hello World' to appear.
  *)
  
  'Hello World ' out
  ) (
  ) : (
  )
  

• Click the "Accept"
• Now the class link "HelloWorldGeneralModule" will appear in the list of classes
• Click on the class link, and the class presented appears
• What happened?
  • First of all the "Hello World" shows on the bottom again.
  • How did it get there?
    • After click on the class link, the IDE prepares some things to present the class. In the IDE, the class is presented inside an instance of the class. So, the IDE creates an instance of the HelloWorldGeneralModule, by invoking the implicit HelloWorldGeneralModule>>#new primary factory method. The method body is executed, calling 'Hello World ' out. #out is a method on String; it is implemented in the Wasm version to append a ~<div>'Hello World '</div> element to the IDE's HTML document body, thus displaying the string at the end of the IDE's page.
    • Similarly, every time just click on the > expand action to the left of the class name, a new instance is created by the IDE, causing one more 'Hello World' to appear.

This concludes the section on General Module class. Before the next step, please reload the page, and select the third option to start fresh. Alternatively, remove the class HelloWorldGeneralModule. It's presence would repeatedly output "Hello World" at the end of the page body. Class deletion can be done by clicking on the three dot popup menu beside the classname, and selecting "Remove HelloWorldGeneralModule"

For a more complex example of a general module, see 1. General module with NO dependencies: API of module with no dependencies

TL;DR: In this section, we will build another Hello World version which is a full blown but rudimentary Newspeak Application. The code for this module is already in https://github.com/mzimmerm/newspeak-doc/blob/main/newspeak---a-few-notes-code/hello-world/3-as-app/HelloWorldApp.ns. To skip the coding details above, we can download the .ns file(s), then "Compile file(s)" to load the fully finished code from there; the loaded class will appear in the IDE.

We now create a class that behaves as a Newspeak Application (as opposed as a general module in the previous section). We need to give the module class two specific "convention methods" described in the sections Newspeak modules API summary and Newspeak modules API zoo.

Here are the steps to create the HelloWorldApp Application in the Newspeak IDE's

• As shown in the previous section, click the "+ ", paste the following class to the IDE, and click the "Accept" button.

  class HelloWorldApp packageUsing: manifest = () (
    public main: platform args: args = (
      (* 
      - In the IDE, we should see this class in the top classes list.  However, (as opposed to previous example ~HelloWorldGeneralModule~), this class has the links *[deploy] [configurations] [run] [debug]* beside it.  This shows as a result of the presence of the convention ~#packageUsing: manifest~ factory method.  The tools (the IDE) understand this message and use it to show actions that can be done with an App: run, debug, deploy, show available configurations.  In addition, the presence of the ~#main: platform args: args~ instance method makes the module runnable as a standalone Application.
      - Click the *[run]* link to run the app inside the IDE.  The IDE calls first the ~#packageUsing: manifest~, then the ~#main: platform args: args~ which runs, and the text 'Hello World from HelloWorldApp' will be appended at the end of the page, as described in  ~HelloWorldGeneralModule~.
      *)
  
      'Hello World from HelloWorldApp' out.
    )
  ) 
  

• In the IDE, we should see this class in the top classes list. However, (as opposed to previous section HelloWorldGeneralModule), this class has the links [deploy] [configurations] [run] [debug] beside it. The links shows as a result of the presence of the convention factory method #packageUsing: manifest. The tools (the IDE) understand this message and use it to show actions that can be done with an App: run, debug, deploy, show available configurations. In addition, the presence of the #main: platform args: args instance method makes the module runnable as a standalone Application.
• Click the [run] link to run the app inside the IDE. The IDE calls first the #packageUsing: manifest, then the #main: platform args: args which runs, and the text 'Hello World from HelloWorldApp' will be appended at the end of the page. This is similar but not the same as in the General module version 2. Hello World from general module. Here, unlike the General module version, the text is NOT appended when clicking on the class link. That is because, in this Application version, the text out message is in the #main: platform args: args method, which runs after clicking the [run] button. In the General module version, it is in the primary factory, which the IDE runs as it constructs an instance of the class on click.

Next, we will show how to deploy our HelloWorldApp as a standalone Application.

From the section 6.4 we know an Application can be packaged and deployed standalone into a local Newspeak webserver.

Follow steps below to create a deployable app HelloWorldApp.vfuel, then deploy it in a local Newspeak installation.

• Action: In the class list, find the HelloWorldApp again, and click the [deploy] to the right.
• Result: a popup showing deployment options, starting with asVictoryFuel:
• Action: Select asVictoryFuel. We choose the faster option 'asVictoryFuel' because our Application does not have GUI. Otherwise, we would select 'asVictoryFuelWithMirrors'
• Result: After a long wait, a file named HelloWorldApp.vfuel is created, and asked to be saved.
• Action: Save the file HelloWorldApp.vfuel on our disk to the directory where local Newspeak was deployed - for example $HOME/software/newspeak/my-serve-http/servable
• Result: Assuming you installed you local Newspeak webserver as in e 6.3, the app is now deployed to the local Newspeak webserver!
• Action: Navigate to http://localhost:8080/primordialsoup.html?snapshot=HelloWorldApp.vfuel
• Result: We see the output of the standalone-running app

This concludes the section on Application Module class. We have shown how to create an App, run it in IDE, create a deployable .vfuel file, then deploy the Application standalone in local Newspeak webserver.

For a more complex example of an Application module, see 4. Application module: API of module that needs to be distributed as an App

TL;DR: This section builds, step by step, a Hello World Application named HelloWorldAppUsingLib. The goal of this section is to show how to use a 3rd party Library named HelloTranslatorLib in an application. All code is in https://github.com/mzimmerm/newspeak-doc/tree/main/newspeak---a-few-notes-code/hello-world/4-as-app-using-translator-lib-as-3rd-party-dependency. To skip the coding detailed steps, we can download, then "Compile file(s)" to load the fully finished code; the loaded classes will appear in the IDE. Then you can browse, [run], or [deploy] the Application. Running the Application produces the text translated to German:

But continuing with the step by step process:

Let's pretend our Application wants to use a Newspeak module produced by a 3rd party (3rd party to us). Call the 3rd party the TranslatorCorp. Let's pretend TranslatorCorp provides the module HelloTranslator, packaged as HelloTranslatorLib.

TranslatorCorp would implement and package their modules as follows:

class HelloTranslator = ()
(
    public translate: text = (
      text = 'Hello World from HelloWorldApp' ifTrue: [^ 'Hallo Welt von HelloWorldApp'.].

      ^ 'unable to translate'.
    )  
)

class HelloTranslatorLib packageLibraryUsing: manifest = (

    (* Library (distribution) class provides packaging and building of the HelloTranslator module *) 
    | 
    HelloTranslator = manifest HelloTranslator. 
    |
)
(
   public buildUsing: platform = (
     |helloTranslator|
     helloTranslator:: HelloTranslator new.

     ^helloTranslator.
   )
)

Note that for every module the TranslatorCorp wants to distribute (such as HelloTranslator), they need to create a library module for packaging and disctribution(such as HelloTranslatorLib)

The HelloTranslator, hence the HelloTranslatorLib

• could have used (depended on) other module HelloTRanslatorHelper developed by the TranslatorCorp
• and also depend on a module LanguageSelectorLib developed by another entity LanguageCorp (so LanguageCorp is "3rd party to TranslatorCorp).

Then, the TranslatorCorp would work in their helper module and the LanguageCorp's module as follows:

class HelloTranslatorLibWithMoreDependencies packageLibraryUsing: manifest = (

  (* This version of HelloTranslatorLib is not ready yet due to missing
     HelloTranslatorHelper and LanguageSelectorLib.
     Use the above version in your IDE experiments
  *)
  | 
  HelloTranslator = manifest HelloTranslator.
  HelloTranslatorHelper = manifest HelloTranslatorHelper.
  LanguageSelectorLib = manifest LanguageSelectorLib packageLibraryUsing: manifest.
  |
)
(
  public buildUsing: platform = (
    |defaultlanguageSelector helloTranslator|

    defaultlanguageSelector = LanguageSelectorLib buildUsing: platform.

    helloTranslator = HelloTranslator
                        helpedBy: (HelloTranslatorHelper new)
                        with3rdPartyLanguageSelector: defaultlanguageSelector.
    (* or #usingPlatform:helpedBy:with3rdPartyLanguageSelector: if platform was needed *)

    ^helloTranslator.
  )
)

Either way, we would develop our Application by packaging the 3rd party dependency and storing it on slot as helloTranslatorLib, then at runtime, build instance of the helloTranslator using the packaged helloTranslatorLib, and last, calling the method on helloTranslator which performs the translation:

This is how the Application HelloWorldAppUsingLib would look.

class HelloWorldAppUsingLib packageUsing: manifest = (
  |
  helloTranslatorLib = manifest HelloTranslatorLib packageLibraryUsing: manifest.
  |
)
(
  public main: platform args: args = (
    |helloTranslator|
    helloTranslator:: helloTranslatorLib buildUsing: platform.

    (helloTranslator translate: 'Hello World from HelloWorldApp') out.
  )
)

As shown in the previous section 3. Hello World from Application, we can click [run] to run the Application from the IDE, or package it a ".vfuel" file, and distribute to run as a standalone Application from a local Newspeak webserver (or as an Electon based on Android, iOS, or desktop, but this is not shown yet).

A simple DOM-manipulation in Newspeak.

Load and run the application https://github.com/mzimmerm/newspeak-doc/blob/main/newspeak---a-few-notes-code/hello-world/5-as-general-module-to-dom/HelloDOM.ns

This version, when run, completely replaces the body of the IDE page with a formatted Text of the Application.

This concludes the 'Hello World' sections, as well as the broader section Newspeak: An ide-driven journey leading to Hello World.

TL;DR: This section describes the simplest setup - in fact, this is a "no setup, no installation" method. We only need a browser and internet access. This is the recommended method to start with Newspeak.

• Action: Navigate your browser to Newspeak online at https://newspeaklanguage.org/samples/primordialsoup.html?snapshot=HopscotchWebIDE.vfuel,
• Result: You should see a page similar to this

Notes:

• By using this page, you are now using the Newspeak IDE
• click the "Newspeak Source" link to view code, edit edit code and manipulate code.
• Your changes will be stored in the browser local storage.
• A more detailed description of what we can do with Newspeak is in the introduction section 6.1

This method downloads a pre-packaged Newspeak, and allows you to start your local Newspeak webserver, which starts the pre-packaged Newspeak. This method is described in detail in the "hands on" section 6.3. Follow the steps there.

Differences of this installation from using Newspeak online described in Installation method 1 (online, no local installation)

• If we install using this method 2 (local Newspeak webserver):
• Pros:
  • No need for internet access
  • Your version does not change if you need stability (this may be a cons too)
• Cons:
  • We have to run our own Newspeak server, and reinstall to care of any updates or bugs fixed.

To install using this method, download the available versions for Windows and Mac, see https://newspeaklanguage.org/downloads.html, section "Downloadable IDE App".

Electron is basically Chromium underneath. It's just set up to read from a page that's built in to the app. So no server needs to be started. It starts with starting the app.

An advantage of Electron that I have seen is a better integration with OS File access dialogues. It doesn't insist on using a downloads directory for everything (and while browsers let you set the directory, they don't let you change it on the fly, on a file-by-file basis).

This method is described in the "Just in Case" section in https://github.com/newspeaklanguage/newspeak.

As this method produces an equivalent that is already downloadable, this is only if we want to dig in more details, but not going all the way to doing all the steps in Installation method 4.

If the build isn't working for you there is one option that hasn't been discussed, which is relevant to Linux folk who don't have an Electron app. You can get the web IDE vfuel file at:

https://newspeaklanguage.org/samples/HopscotchWebIDE.vfuel

BUT … this isn't enough because you need a bunch more stuff, such as primordialsoup.html, primordialsoup.js, primordialsoup.wasm. If you run that, you'll find that you also need a longish list of .png files for the various images used by the IDE. Here they are (probably a few that are no longer used too).

accept16px.png hsHistoryDownImage.png accept16pxDown.png hsHistoryImage.png accept16pxOver.png hsHistoryOutImage.png arrowGreenLeft.png hsHistoryOverImage.png arrowGreenRight.png hsHomeDownImage.png arrowOrangeLeft.png hsHomeImage.png cancel16px.png hsHomeOutImage.png cancel16pxDown.png hsHomeOverImage.png cancel16pxOver.png hsNewDownImage.png classPresenterImage.png hsNewImage.png classUnknownImage.png hsNewOutImage.png clearImage.png hsNewOverImage.png conflictRed.png hsRefreshDownImage.png disclosureClosedImage.png hsRefreshImage.png disclosureMinusImage.png hsRefreshOutImage.png disclosureOpenImage.png hsRefreshOverImage.png disclosurePlusImage.png hsReorderDownImage.png disclosureTransitionImage.png hsReorderImage.png downloadImage.png hsReorderOutImage.png editImage.png hsReorderOverImage.png findImage.png hsToolsDownImage.png findSquareLeftDownImage.png hsToolsImage.png findSquareLeftImage.png hsToolsOutImage.png findSquareLeftOutImage.png hsToolsOverImage.png findSquareLeftOverImage.png itemBothOverride.png helpImage.png itemDeleteImage.png hsAddDownImage.png itemMenuImage.png hsAddImage.png itemReferencesImage.png hsAddOutImage.png itemSubOverride.png hsAddOverImage.png itemSuperOverride.png hsBackDownImage.png languageJS.png hsBackImage.png languageM.png hsBackOutImage.png languageNewspeak3.png hsBackOverImage.png languageSmalltalk.png hsCollapseDownImage.png menu16px.png hsCollapseImage.png menu16pxDown.png hsCollapseOutImage.png menu16pxOver.png hsCollapseOverImage.png menuButtonImage.png hsDropdownDownImage.png metaMenuDownImage.png hsDropdownImage.png metaMenuImage.png hsDropdownOutImage.png metaMenuOutImage.png hsDropdownOverImage.png metaMenuOverImage.png hsExpandDownImage.png operateMenuDownImage.png hsExpandImage.png operateMenuImage.png hsExpandOutImage.png operateMenuOutImage.png hsExpandOverImage.png operateMenuOverImage.png hsFindDownImage.png peekingeye1610.png hsFindImage.png privateImage.png hsFindOutImage.png protectedImage.png hsFindOverImage.png publicImage.png hsForwardDownImage.png repositoryGit.png hsForwardImage.png repositoryMercurial.png hsForwardOutImage.png saveImage.png hsForwardOverImage.png tinySubclassResponsibilityImage.png

You can place it all in the directory of your choice and serve from there (the serve.sh script wants it in the repo, in the out directory). It seems easier to build, but I'm putting it out there.

How to update the IDE? The answer differs depending on what version you are using.

Could there be situations we do not want to simply reinstall the local Newspeak webserver? Perhaps one example of such situation is that we run our local Newspeak webserver with changed files, and we want to patch a class that has a known fix, without reinstalling the local Newspeak webserver and losing changes.

To describe a concrete (somewhat artificial) situation: Let's say that on Github, there is a bug fix or change in a 'system' class, Browsing.ns, and we want to update this single class locally. We can identify changed files or files with fixes, and compile them in (that is, start using them in) the local version, using the following process:

• Look for files committed on Github.
• Find files changed since your last local install - let's say file Browsing.ns changed today to fix a bug. As your local server uses the servable.zip file, Browser.ns is already compiled in your local vfuel.
• So from the browser IDE, http://localhost:8080/primordialsoup.html?snapshot=HopscotchWebIDE.vfuel from the 3-dot I "compile" the new version of Browsing.ns
• Save the changes from IDE (clicking the save diskette image)
• You can confirm that your changes were "Compile"d, by exporting of Browsing.ns (click the "Save to file" button to export the code).
• The result of the above process is your local server are now using the github-fixed Browsing.ns.

How is the browser local storage handled, and how is lastSaved different from backup? Here is a detail description of how changes are saved and restored:

• After making a code change or addition, to keep your change, you have to click the "Accept" button . Clicking "Accept" saves the changes in local storage under the key backup.
• while
• Clicking the "Save" button , at any time after "Accept" , saves the changes under the key lastSaved (the changes under backup are added and merged in to the changes under lastSaved). Once saved using the "Save" button, changes are stored "forever", unless you reset browser local storage for the site. So the steps "Accept" , and "Save" are sort of like two phase commit.
• We need to clarify, that making a change, followed by just clicking "Save" without a previous "Accept", nothing is saved.
• You can view the changes made, in the browser debugger. For example, in Chrome or Chromium:
  • Press F12 to open Chrome debuger.
  • Then click the "Application" tab.
  • In the "Storage" section expand "Local Storage".
  • You can see our changes in the appropriate URL, both under the key lastSaved and the key backup.
• How does the/lastSaved/ and backup system work on browser restart? On restart, the Newspeak system checks to see if there are any changes under the key backup and/or under the key lastSaved. If lastSaved changes exists, Newspeak checks if there are any subsequent changes under backup. If not, we use the lastSaved version. If there are unsaved changes (backup entry is not empty), a dialog will come up asking you how to proceed:
  • This message tells us, we did make code changes, then clicked "Accept" , without pressing "Save" , and reloaded the page. In other words, changes are stored under the key backup but not(yet) under lastSaved. In most situations, pressing Restore from backup is the best choice. Your code will load the changes from the backup key, and contain all your changes. At any time, you can click "Save" and merge the backup changes to lastSaved. After, the question above will not be asked until you made new changes and "Accepted" them.
  • For search purposes, here is the text of the message: "You have backup changes that are newer than your last save. Do you want to restore these changes, or load from the last save?"
• Note: There is a fine point we should make. Crudely, we can say that "the Newspeak IDE is the file HopscotchWebIDE.vfuel interpreted by the browser when pointing to the URL https://newspeaklanguage.org/samples/primordialsoup.html?snapshot=HopscotchWebIDE.vfuel. This is the default "vanilla" Newspeak IDE available online on a server. However, we need to realize that the browser immediately downloads and caches this file. Changing anything in Newspeak (adding a class, typing to the Workspace), causes the changes to be saved locally in the browser. As long as we accept changes, closing the browser, and visiting the same online URL again, will display the site as we left it - with the local changes "added" to the vanilla Newspeak IDE on the server! Which local changes are "added" (backup or lastSaved or both), is determined by your answer to the dialog above.
• Caveats: There are a few caveats - a few classes are exempt from this "backup" and "lastSaved" method, due to bootstrap issues (things like KernelForPrimordialSoup and HopscotchWebIDE). If you tamper with these - save the class explicitly! Also, web storage can surprise you on mobile platforms, where things can be thrown out after a certain amount of time (7 days on iOS?) and the system as a whole may exhibit bugs.

During development, any code additions and changes we make, are saved in-browser in the browser local storage, as described in 10.2.1. But if we do clear the browser local storage, our changes will be lost. While the browser local storage can be backed up as part of browser configuration, restoring it is cumbersome.

Consequently, saving our work (source code) outside the browser as text files is valuable.

Current approach to saving our work during development (as text files)

Until source control is integrated into the IDE, the current approach is to `export` ("Save to file") each class we changed into a directory on your system as a file with .ns extension. We can also create a code repository in the directory with the .ns files.

How For how to access the "Save to file" and "Compile File(s)" buttons, see TL;DR in section Chapter Saving changes in Newspeak

Note: To 'import' the saved text *.ns files back to the Newspeak IDE, click on the "Compile File(s)", as also described above.

We often ask "how is this class used"? "What is the result of calling one of it's methods"? Answer can be provided by any of the following mechanisms:

• Reading the class code and deriving a result (in our head).
• Finding a test for the class and the method and analyzing it's code and results.
• Writing a simple example program using the class and method. In Smalltalk and Newspeak, this is done by navigating to "Workspaces" and writing some code - instantiating the class, passing it's factory some arguments, and calling the method you are interested in.
• Right in code: Exemplars provide a class-author supplied mechanism to instantiate the class and run it's methods, as if a user was doing that in the Workspace

Gilad Bracha's blog post https://blog.bracha.org/exemplarDemo/exemplar2021.html?snapshot=BankAccountExemplarDemo.vfuel

Gilad Bracha's BankAccount video https://www.youtube.com/watch?v=qKWPSvcF0zA

A class with exemplar can be found at BankAccount in Newspeak sources.

There are several exemplars pulled from the code link above:

(* :exemplar: BankAccount balance: 100 *)
(* :exemplar: deposit: 100 *)
(* :exemplar: withdraw: 100 *) 

The string after :exemplar is expected to be valid Newspeak code.

We can also guess that the :exemplar: code provides a way to instantiate the class and run some methods on it - basically mimicking what we would do in a workspace if we wanted to explore the class instance's behavior.

From the source we can also see the :exemplar: comment is placed before the = sign in a factory or method declaration - that is the only place where the parser is looking for exemplars.

A sample code with an exemplar:

class BankAccount balance: b <Integer>
(* :exemplar: BankAccount balance: 100 *) = ( .. factory code .. )

To make the :exemplar: stand out more, we can format the code so that the comment with exemplar occupies it's own line. The formatting above is "normative" though.

class BankAccount balance: b <Integer>
(* :exemplar: BankAccount balance: 100 *)
  = ( .. factory code .. )

The role of exemplars is two-fold:

1. Provide lively code in the IDE. By adding appropriate exemplars for a class, the IDE, when browsing the class, will use the exemplars code to create the class instance. Once an instance exists, it can call methods on it.
2. Provide code examples of class instantiation and running it's methods.

If a class such as the BankAccount provides an exemplar for the primary factory method, an instance of the BankAccount is presented in the IDE UI; the BankAccount class presenter is also shown, embedded in the instance.

Inclusion of an exemplar allows the IDE to create a live instance, present it's browser, and allows the user to interact with the live instance.

If a class such as the BankAccount does not provide exemplars, only the BankAccount class presenter is shown in the IDE UI. See the section below.

This section is edited from the Google Groups posts around https://groups.google.com/g/newspeaklanguage/c/cPG5Q6NOwiA/m/fSuol8w_AQAJ

This section describes access control in Newspeak.

The main backround source for this section is the online presentation Can Beautiful Languages Do Access Control?. The text here is based on and borrows from the above, but may introduce terminology that is not part of the presentation.

Access control is a set of rules for class and object members (accessed items).

The access control rules decide whether an expression (a line of code), will be accessible (can be executed) at runtime.

The rules take into account

1. Access modifiers "private" "public" and default (protected) on the accessed items;
2. Wheather the accessed items are declared in the same class, nested class or enclosing class of the expression for which the rules evaluate access. In other words, access control rules interact with the lexical structure (nesting) of the classes involved: classes where the code is located, in relation to the classes which are used in the code.
3. Whether the accessed items are declared in the same class or an inherited class. In other words, access control interacts with inheritance.

Clearly, access control rules are not trivial. This section attempts to explain them, and provide some practical examples.

Every expression in Newspeak is a message send. So let us describe what is meant by the term "Access" or "Access rights" of objA to access objB or objA to send message msg to objB.

• Newspeak classes can be nested and also inherited.
• Newspeak classes can have the following members: slots, methods, nested classes.
• Each member may have access modifiers keywords: public, private. No modifier means protected.
• "Access control" describes how objects can access ("have the access rights to") other objects and other objects' members.
• The access rights are determined by rules which navigate in three independent "dimensions"
  • The "accessibility dimension": Points on this dimension are access modifiers: public, private, protected (default, no keyword)
  • The "lexical dimension" : Points on this dimension are enclosing and nested classes
  • The "inheritance dimension" : Points on this dimension are classes on the inheritance chain
• In a Newspeak's (class based) system of objects, each object may contain slots, methods, and nested classes.
• Because in Newspeak runtime, any operation is a message send, we can speak of the following:
  • At runtime, in Newspeak's system of objects, object objA may or may not be able to reference (see) another object objB.
  • If objA is not allowed to reference objB, a security exception results.
  • If objA can reference objB, we say that objA has access (or access rights) to objB. Further, if objA has access to objB, assume there is a method, slot, or nested class named memberB declared on objB. Even though objA has access to objB, objA still may or may not be able to send the message memberB to objB (execute objB memberB). If objA has the ability to send message msg to objB, we say that "object objA has access to memberB on objB"

Combined, we say that objA has access (or access rights) to send a message memberB to objB, if a message send objB memberB is allowed to execute at runtime from some place in code of objA.

Slides in this presentation serve as a core source for the rules that define accessibility:

Can Beautiful Languages Do Access Control?.

This section goes over access control rules described in the above slides.

The core slides are slides 61, 62, 63. They describe how Newspeak code in a class accesses members (classes, slots, methods) above and below the class in the nesting hierarchy and the member members, depending on the accessed member's public, private and protected status.

• Newspeak virtual call lookup does NOT use the 'comb rule'
• Newspeak virtual call lookup uses the 'lexical chain first, inheritance chain second' method
• The reason for the choice is described in and after the slides 'A Problem' and 'When code evolves'.
• So virtual method call lookup in summary:
  • Newspeak gives priority to lexically visible declarations
  • But once a lexical level has been selected, inheritance chain is used. Inheritance can have an effect; lexical declaration can be overridden

From the IDE:

• in "Newspeak Source"
• click on the "+" beside Root, in the popup, choose "Add Document"
• give the document a name
• click the "Accept" checkbox.

So far this is equivalent to creating and adding a class, except here we choose "Add Document" rather than "Add Class".

The newly created document named AMyDocument may look similar to this

Above is the state after we clicked the ">" widget just above the document text - this revealed an editor line:

To save the document HTML, click on the "download" button in the above line.

The document AMyDocument will save an HTML file with the document contents stored in a top-level <div> element. The top-level div class name "ampleforthDocumentClass" is known to Newspeak, which can use it to convert this html back to a Newspeak object, from the top-level div attribute "classBody".

The contents of AMyDocument.html is shown below:

<!-- this first div with class ampleforthDocumentClass does not display anything : it contains code for the class AMyDocument.
     It has no methods, but it could have.
  -->
<div class = "ampleforthDocumentClass" name = "AMyDocument" classBody = "() (
) : (
)
"
</div>

<!-- this second div with class ampleforthDocumentBody displays the document -->
<div class = "ampleforthDocumentBody">
  <body>
    <div class="self_ampleforth" contenteditable="true" style="border: 2px solid blue; resize: horizontal; overflow: auto; overflow-wrap: break-word; width: 40em;" onkeyup="updateRawHTML()">
      <h1>This is a blank document - testing saving as HTML.</h1>
      <div><br></div>
      <div>Body here.</div>
      <div><br></div>
      <div>- item 1</div>
      <div>- item 2</div><div>
      <br>
      </div>
      <div>The list above is just a bunch of divs.</div>
    </div>
  </body>
</div>

<!-- the remaining script elements contain support for loading this file if converted to vfuel (??) -->
<script type="text/javascript">
      function scheduleTurn(timeout) {
        if (timeout >= 0) {
          setTimeout(function() {
            var timeout = Module._handle_message();
            scheduleTurn(timeout);
          }, timeout);
        }
      }

      var Module = {
        noInitialRun: true,
        noExitRuntime: true,
        onRuntimeInitialized: function() {
          var url = new URLSearchParams(window.location.search);
          var request = new XMLHttpRequest();
          request.open("GET", url.get("snapshot"), true);
          request.responseType = "arraybuffer";
          request.onload = function (event) {
            var jsBuffer = new Uint8Array(request.response);
            var cBuffer = _malloc(jsBuffer.length);
            writeArrayToMemory(jsBuffer, cBuffer);
            Module._load_snapshot(cBuffer, jsBuffer.length);
            _free(cBuffer);
            scheduleTurn(0);
          };
          request.send();
        },
        print: function(text) {
          if (arguments.length > 1) {
            text = Array.prototype.slice.call(arguments).join(" ");
          }
          console.log(text);
        },
        printErr: function(text) {
          if (arguments.length > 1) {
            text = Array.prototype.slice.call(arguments).join(" ");
          }
          console.error(text);
        },
        setStatus: function(text) {
          console.log(text);
        },
      };
    </script>
    <script async type="text/javascript" src="primordialsoup.js"></script>
    <script src="CodeMirror/lib/codemirror.js"></script>
    <link rel="stylesheet" href="CodeMirror/lib/codemirror.css"></link>
    <script src="CodeMirror/addon/display/autorefresh.js"></script>

Opening the file AMyDocument.html straight in a browser tab (as Ctrl-O, NOT in the contents of Newspeak IDE), displays the pure HTML contents correctly - assuming any resources it references are available. It would not display any "live" elements that would require calling methods

The file AMyDocument.html:

• contains the document class and methods - but using the methods requires a running Newspeak system, NOT just the browser which only displayes the HTML.
• can be fully instantiated as a Newspeak Document by loading it (compiling it) into a running IDE (which does NOT contain the class AMyDocument). This can be done by clicking the "Load document(s)" on the 3-dot menu in which puts the document class back to the IDE
• also somehow, can be instantiated and run by creating a vfuel from it??

Blogs

• sourced on https://github.com/gbracha/gbracha.github.io
• run URL on https://blog.bracha.org/

TL;DR: CounterAppWithDependencies is an example of an Application which uses a dependency, the General module ATranslation. We can download and save the code files from https://github.com/mzimmerm/newspeak-doc/tree/main/newspeak---a-few-notes-code/counter-app-with-dependencies. We use "Compile file(s)" to load the saved files; the loaded class will appear in the IDE. Then we can browse, run, or deploy the Application. This version is in Czech:

Note: In this CounterAppWithDependencies example, the translation class ATranslation was written by us, as a General module, NOT a library. We have another example 4. Hello World Application using 3rd party dependency where the translation class HelloTranslator is wrapped in a Library module HelloTranslatorLib - this mimics a situation where HelloTranslator may NOT be written by us, but by another 3rd party, who packaged packaged HelloTranslator in HelloTranslatorLib for distribution. As a result, the Hello World example is slightly different.

This example Application is in another chapter, as it was developed based on a detail IDE and debug based discovery of Hopscotch UI in that chapter. View it at Using Hopscotch discovery a Model-Presenter-Subject Application, the CheckedItemApp

• Is instance of a top-level class
• Modules (top-level class instances) are invisible to each other?
  • Exactly. This is the result of one Newspeak fundamental design ideas, that make it very different from Smalltalk: "There is no global namespace."
• It has no access to anything except a few basic classes inherited form Object, and whatever is passed into its factory (it need not be platform). The arguments to the factory are capabilities, in the sense of the object-capability security model (ocap). Now to actually build things, you use the IDE as a global namespace to collect the various pieces you need.

• The platform object reifes the set of standard libraries that one expects to have at any destination.
  • In a sane world, this would be the complete story. Alas, we live on Earth instead. We can't expect every device to have Newspeak installed. Therefore, we may need to package an application with additional elements, such as the Newspeak platform and a Newspeak VM. We also need to accommodate different packaging formats and technologies, such as operating systems and web browsers.
• It is a also a message supported by the workspace. It returns an object also termed 'platform'.
• Is there a way to list what variables are there?
  • Yes: type platform and evaluate it (make sure you select 'platform' or type it on a new line, so you don't end up evaluating other stuff in the workspace). Then click on the link, which iwll take you to an object presenter (aka object inspector) on the platform object.
• The platform object also provides the API for all things supported by the infrastructure (systemPlatform) where it is running. This APIs should be implemented by all systemPlatforms where Newspeak runs on. But it does not lock you in - that's why you have the option of accessing systemPlatform-specific stuff, by going through an accessor method. On the WASM system, that accessor is #js, and it gives you access to Javascript. So it is also something that gives you the only connections to the world outside Newspeak.

• Q: It is usually used in factory method slot declarations, such as

  class AClass usingPlatform: platform  = (
    |
    (* imports *)
    private Map = p collections Map.
    private Presenter = p hopscotch Presenter.
    |
  )
  

  Why do you not just store the Platform object itself in a slot, and only ask it for these other objects when you need them?

  • A: You could do that, but that would be bad coding style. Newspeak is largely about modularity; this is a big part of that story. The code above acts (as the comment says) as a series of imports of classes that the module depends on. If you store the individual modules as above then you (and the system) know, looking at the factory, exactly what the module's dependencies are. If you store the entire platform, you don't know what you're using; it's like a Java program (or a Smalltalk program, for that matter).
• Improved platform story. You might have noticed an annoying quirk in the various GUI apps, where the app has to set up a Hopscotch-enabled platform in its #main:args: method. This deviation from Goodthink has been eradicated. The old HopscotchForHTML5Runtime class is gone. Instead, RuntimeForHopscotchForHTML provides a proper platform that one can deploy Hopscotch apps to, and these apps no longer need to anything special/convoluted to use Hopscotch. The apps and build script have been updated accordingly.

• The Newspeak IDE provides a global namespace, which is of course a real object that you can pass around. That object is a manifest.
• Manifests and platforms are totally different. Manifests are a development thing - only available in the IDE. Platforms are a deployment thing.

The platform is something that gives you the only connections to the world outside Newspeak.

• The Newspeak language has no global namespace.
• The Newspeak IDE provides a global namespace, which is a real object that you can pass around. That object is a manifest. The section in IDE UI where it is displayed is called "Root".
• Try evaluating ide namespacing manifest in an IDE workspace. This is the global namespace, but it only exists in the IDE. mz - it does not exist when running an application, unless the application author saves the whole manifest on application's slot.
• Of course, you can always override the behavior of a given manifest by wrapping it.
• mz : Each module is also a non-global namespace for it's inner classes. A name (of a slot, method, inner class) in a moduleA will never clash with a name from a moduleB.

• Q: At which step of the lifecycle would the AnApplication>>#packageUsing: manifest and ALibrary>>#packageUsing: manifest method be used (invoked), where, by whom?
  • A: Those "convention methods" should be given to Applications and Libraries to enable a instantiation for packaging. They would be invoked as a step to build an Application or Library object for distribution (answering lifecycle), by the IDE (answering by whom) on the source system (answering where). Their invocation would be followed by serializing the object, which would be saved as a .vfuel file for distribution. We could serialize the object in different serialization and distribution formats, and different assumptions about presence of dependencies on the target system. .vfuel file is the main format. The IDE uses the presence of this method (solely) to determine the module is an Application, and displayes on the class line, the [run][debug][deploy] actions. The action code after clicking on [deploy] -> asVictoryFuel(WithMirrors) starts with invoking this method, followed by serialization of the Application object this method creates.
• During creation of a software artifact, all the dependencies of the artifact have to be made available by getting them to the development site or build site (where the build scripts will run). This is commonly addressed by package managers (mz - e.g. zypper install, apt, flutter pub get, pull dependencies from the web to the "build site" - my system - where I want to create and build my newly-coded package). That much is true in Smalltalk as well. In Smalltalk you put these in your image, which provides a global namespace; in most other systems you put them in the file system, which again, is a global namespace. In Newspeak, you put them in the IDE, which as a global namespace as well. I am hoping to avoid the plague of package managers; the IDE should be able to do this based on some metadata conventions.
• Next, there is the question of how you put together your program from the available artifacts, given the global namespace. This is the domain of build scripts in traditional software. In Newspeak, you can write these scripts in Newspeak itself. These would take a namespace object (we often call a manifest) as a parameter. You'd typically pass in the IDE top level namespace. Of course, you can always override the behavior of a given manifest by wrapping it.
• So you write class with a #packageLibraryUsing: manifest method that takes a manifest and instantiates your library as you wish. The manifest needs have all the code you need. Importantly, the manifest is still under 'end user control' and should contain only top level classes (we can also enforce that) so no state or access to the outside world is provided. Thus, the #packageLibraryUsing: methods are like build scripts, and they can call other #packageLibraryUsing: manifest methods, just like build scripts or makefiles refer to others. The difference being that none of this is hardwired to a specific global namespace.
• The above deserves reiterating: Despite the name, the "#packageLibraryUsing: manifest" methods are like build scripts! mz - And, the "#buildUsing: platform" methods are like loading a module provided by the library into memory and linking it to application! See the next section on #buildUsing: platform
• And if I write software library that depends on 20 or 30 third party libraries, I'll have to write a factory with 30 specific arguments?
  • No, you can aggregate them into an object (a manifest or submanifest, or even something else), and pass that into the #packageLibraryUsing: myManifest. That way clients of your library will not break when you add 31st 3rd party library to your library. Also note that in many cases, you will write factories that take actula module instances rather than classes as arguments.
• The "convention methods" names for a Newspeak Library, are confusing: they use the method name starting with the word "package" for a step which is in traditional software termed "build(script)", and they use the method name starting with the word "build" for a step which is in traditional software termed "loading" or "linking".
  • package(Library)Using: manifest performs work similar to build scripts to build for deployment - factory method
  • buildUsing: platform perform work similar to loading and linking - instance method
  • The argument to the factory is the manifest, which is a namespace object where all the dependencies of the application can be found. The factory method of the application is analogous to its build script. To deploy an application, you serialize it (exactly in the sense of object serialization) so that you can then transport it elsewhere, where you can deserialize it, obtaining a live object; then you call #main:args: and run it. Again, it's just like shipping executable. Deserializing is like loading.

• At which step of the lifecycle would the "#build: platform" method be invoked?
  • A: When loading an application.

Details:

The #buildUsing: platform was proposed specifically for the library distribution scenario rather than the application distribution scenario. It's role is analogous to #main:args. You distribute the library, as you distribute the application, as an object with its dependencies (excluding the platform), all serialized.

1. You produce (build) the application (respectively library) object using #packageUsing: (resp. #packageLibraryUsing:).
2. You then instantiate the application (respectively module object provided by the library object) using #main:args: (resp. #buildUsing:).

At that the first stage (dev time on source system) you provided a manifest, a global namespace of the classes you need. At the second stage (load time on target system) you provide a platform that ties this code to the standard libraries that provide access to real world capabilities.

Alice sells a module of type AlicesModule. Alice codes up a Library of type AlicesModuleLib as a wrapper for her module of type AlicesModule. Bob is building an application of type BobsApp which wants to use AlicesModule.

I will drop the word "type" below, and use lowercase for objects, Uppercase for classes.

The lifecycle of a library alicesModuleLib providing the module alicesModule would be:

I only have questions on

• Items 1.8. and 2.1. : Would this be in principle intended as a sharing mechanism of libraries? Or a different peer to peer method?
• Items 2.1 (again), 2.2 and 2.3. and 2.3 : How are object deserialized from vfuel instantiated and included in IDE? Are there examples in the Newspeak IDE code?

I do not have any questions on the other items, in fact I would be unhappy if I got those other items wrong :) but would be happy to know I got those wrong.

Thanks todo-00-last - ask the above on newspeak list, also comment on conflicting naming as mentioned above.

• package(Library)Using: manifest performs work similar to build scripts to build for deployment - factory method
• buildUsing: platform perform work similar to loading and linking - instance method

Also see Application and library modules in Newspeak

They all show if and only if the the class has the "#packageUsing: manifest"

[run tests] and [show tests] are displyed iff the class has a #packageTestsUsing:manifest class method. Again, a convention indicating that the class is a test configuration.

• Can the 'program package' in Newspeak be something else than a vfuel file?
  • A: Yes. Example: you compile the application into Javascript. This too is a way to serialize the application object. Or you might want to deploy your code as an Electron app, packaged as a MacOS application or a Window application, and these may each have variations (are they to be signed for app store use?; are they to include the Newspeak code as vfuel along with a WASM VM, or as Javascript? etc.). More on this below.
  • As noted above, there are any number of formats. At the very core, there is a serialized Newspeak object. For a CounterApp, this would be 100Kb. But because we ship the ~platform code in a vfuel, we get to about 1Mb. Once we add the engine (300K WASM) and other resources, things grow further, and we are distributing something like zipped directory (e.g. server.zip on the downloads page). If we wrap that in an Electron app, and wrap that in a MacOS app, we have 70Mb zipped, or 175Mb unzipped, because we now are shipping Chromium as well.

• I can place .vfuel under a webserver and run the CounterApp, but can I, for example, export some other artifact (zip file with binary or source?) that is later loaded into another persons Newspeak IDE?
  • A: In principle, yes, there are other ways to serialize an application. In earlier versions, we would serialize an app without the platform code. This results in very small files (say 100Kb, depending on the app). The IDE (this was the old Smalltalk based system) would deserialze the app object into a regular Newspeak object in memory. In an ideal world, this is all you would need. Alas, this requires a Newspeak engine to be useful, and we cannot realistically assume this. So, the current vfuel files include the entire platform code in them. Now, since many apps do not require features such as reflection, and reflection tends to greatly increase the footprint of the vfuel file (because we must include source code as well as the mirror module) we have options to create vfuels with or without mirrors. The idea of deployment/serialization configurations is to generalize this, so one can describe deployments of varying kinds. This is not really properly supported yet. But you can see that there is a large number of combinations (JS or WASM; GUI or non-GUI; mirrors or no mirrors; MacOS, Windows, ChromeOS, iOS, Android; Electron or PWA) not all of which are valid of course.

The process of coding a Newspeak Application is described in several example in this document, one example is Code, run, and debug the CounterApp in Newspeak. It is also described more succintly in the 'Hello World' programs section 3. Hello World from Application.

Once the app is "coded", There are two options of producing the app's deployable package (a .vfuel file)

1. From the IDE: There is a 'deploy' option that the IDE displays for apps. This option is slow but simple, and we can deploy small apps that way. The process of building an app, the creating a deployable .vfuel package. This process is described fully in Chapter Deploy CounterApp as standalone app into local Newspeak webserver.
2. From a script: Slightly more complex to install, but works faster. You use a script that runs the C version of the PSoup VM to do the deployment. This is faster, more reliable and produces smaller deployments. This is done by Step 7 of the script in Newspeak: Script which builds deployable vfuel files.

In either case, .vfuel file is produced. We can then serve that file in a webserver, and run your app.

This .vfuel can then be deployed into a locally installed or a globally installed webserver.

• For instructions on how to install the server see Simple methods to install and run Newspeak
• For instructions on how to deploy a sample app, in particular the CounterApp, see 6.4.

Hopscotsch is the Newspeak module used to write UIs in Newspeak. The version of Hopscotch used in today's (year 2021) Newspeak is called Hopscotch for HTML5. It is implemented in classes nested in the module's class (top level class) named HopscotchForHTML5.

The intent of this chapter is to discover things about HopscotchForHTML5 mostly by browsing it's code in the IDE, plus some previously developed intuition :)

I am trying to make the process of this chapter to be like discovering things about nature by observation. In our discovery, observation = browsing code only the Newspeak IDE. By observing, we should be able to extract knowledge and make generalizations and predictions. In our discovery, extract knowledge = understand the core API; make generalizations and predictions = be able to write a simple UI Application of our own.

Note: One important discovery tool is missing - in the current Newspeak, debugging anything in the UI is impossible, due to some known bugs.

In other words, during our discovery process in this chapter:

• Most of the information should come from browsing through the Newspeak IDE in the top level class HopscotchForHTML5.
• The end goal of our process is to write a simple Newspeak Application with UI in Hopscotch. This simple Newspeak Application is developed in chapter Using Hopscotch discovery a Model-Presenter-Subject Application, the CheckedItemApp.
• There was also the benefit of previously looking at the CounterApp (aka cheating), but as much as possible, we are trying to extract everything we need from the "first principles" of browsing the Newspeak IDE top level class HopscotchForHTML5.

Two most important nested classes in HopscotchForHTML5 are Subject, Presenter. This statement did not come necessarily from observation (although we could claim that), but from a bit of a "previously developed intuition", as well as from the paper "Hopscotch: Towards User Interface Composition" by Vassili Bykov, 8 pages https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.478.1098&rep=rep1&type=pdf. Note that the paper is about the original Hopscotch, not the HTML5 specific version. But I feel the core of the two versions seems close enough to start with the paper.

So this chapter makes a reasonable assumption that the Subject and Presenter classes are of core importance in building UIs in Newspeak. Further, opening class Presenter in the Newspeak IDE, we see that it has a parent class Fragment. Fragment is new to the new version HopscotchForHTML5 as opposed to the original Hopscotch. Because we consider Presenter important, so must be Fragment.

So, enough meta talk, and let us browse the most important code of classes Subject and Presenter - their primary factory methods. As with any Newspeak class, we should start at the primary factory methods to understand the class. Primary factory method is the only code which defines slots (slots as similar to members in other OO languages). Also we see that Fragment is parent of Presenter. So Fragment must be important; we added it's primary factory method to the constructor summary as well.

public class Subject onModel: aModel = (
  |
	public model = aModel.
  presenterSlot <Presenter>
  public helpActive <Boolean> ::= false.
  |)

public class Presenter onSubject: aSubject <Subject> = Fragment (
  |
  public subject <Subject> ::= aSubject.
  substanceSlot <Fragment>
  public generation <Number> = uiGeneration.
  |)

class Fragment = (
  |
	visualX
	public parent
	public size ::= nil.
	public expansibility ::= 0.
	public compressibility ::= 0.
	decorators
	|)  

From the primary factory methods, it is immediately clear that:

1. For a subject to be created, a model is required. So model must be created before subject.
2. For a presenter to be created, a subject is required. So subject must be created before presenter.

Lifecycle of any Hopscotch UI code:

• We need to instantiate a Model first.
• We need to instantiate a Subject on the model next.
• We need to instantiate a Presenter on the subject last.

This is quite clear from the signatures of those classes primary factory methods - there can be no other way.

A note on Newspeak syntax: while the Subject>>model slot and Presenter>>subject slots are public, they have no setters, so they are final. The value they acquire in the primary factory method cannot be changed. This is because the slots are defined using " = ", for example in public model = aModel. If the " ::= " was used instead of " = " to define the slot model, then the slot would not be final - a setter would exist. But as is, we cannot, even in principle, create the instances of Model/Subject/Presenter with null slots, change the creation order, and set the slots later.

Next two chapters will look into details of Presenter, Subject, and Model classes, and associations between them. The associations may not be important for writing UIs, but they are for understanding the Hopscotch framework.

This chapter is about the Subject class, in particular about three "important parts" we should know to understand the Newspeak UI. Those parts are also important when we write code for concrete implementations of Subject.

Let us show the code for the Subject class, keeping only the "important parts" - each of them is discussed in subchapters below.

From class Subject

(* 1. The primary factory method *)

public class Subject onModel: aModel = (
  |
  public model = aModel.
  presenterSlot <Presenter>
  public helpActive <Boolean> ::= false.
  |
) (


  (* 2. The methods that deal with associating Subject and Presenter instances *)
  
  public createPresenter ^<Presenter> = (
    subclassResponsibility
  )
  public presenter ^<Presenter> = (
    presenterSlot isNil ifTrue: [presenterSlot:: createPresenter].
    presenterSlot generation < uiGeneration ifTrue: [
      presenterSlot:: createPresenter.
      ].
    ^presenterSlot
  )

  
  (* 3. Unimplemented (abstract) methods which a concrete Subject implementation must provide *)
  
  isMyKind: s <Subject> ^ <Boolean> = (
    subclassResponsibility
  )

  
  (* Several other methods *)
)

In the subchapters below, we go over each of the "important parts".

This is the code which creates instances, and should be called from implementations' primary factory methods. The code hold slots for model, the associated presenterSlot and a help slot. For a practical purpose of writing UIs, this is the most important code.

Concrete implementations of Subject, should (in fact must, it is enforced) invoke the Subject's factory as

public class MyConcreteSubject onModel: aModel = Subject onModel: aModel (|pseudeSlots|) (pseudoInstanceMethods) : (pseudoClassMethods)

This should be sufficient for most concrete implementations of Subject.

The full signatures of the unimplemented methods which each concrete Subject implementation must provide are:

• Subject>>#public createPresenter ^<Presenter> should return the concrete Presenter instance which will present the subject. This was also discussed in the chapter above.
• Subject>>#isMyKind: otherSubject ^<Boolean> is repetitive but required. We have a common chapter for this, see The formulaic required repetitive methods of #isMyKind: and #isKindOfX

public createPresenter ^<Presenter> = (
  subclassResponsibility
)

isMyKind: s <Subject> ^ <Boolean> = (
  subclassResponsibility
)

In any concrete implementation of Presenter, those methods must be provided.

In the conclusion of chapter Discovery of the HopscotchForHTML5 class basics we already discovered an important lifecycle any UI code need to perform: Create an instance of a Model first, a Subject next, a Presenter last.

In this chapter The Subject class: primary factory method, instance methods, how Subject knows Presenter we added the following conclusions:

Conclusion 1: As long as the Subject>>#presenter is invoked (on an existing subject instance), two important things happen:

• A Presenter instance is created.
• The bidirectional association between the subject and presenter instances is established.

Conclusion 2: So, when creating UIs, our code must invoke the Subject>>#presenter method, directly, or indirectly by calling some other method that ends up calling Subject>>#presenter.

Conclusion 3: Model can be any object. ConcreteSubject must extend the Subject. Also the ConcreteSubject primary factory method must declare the primary factory method on the superclass Subject - see The primary factory method public class Subject onModel: aModel = (..) ; chapters below come to the equivalent conclusion for ConcretePresenter.

Based on the conclusions 1, 2, 3, we can already write some pseudocode for writing core UI:

intermediary code - do not use yet

|concreteModel concreteSubject concretePresenter|
concreteModel:: ConcreteModel new.
concreteSubject:: ConcreteSubject onModel: concreteModel.
concreteSubject presenter.

Note the last line concreteSubject presenter.: Why did we not use concreteSubject:: ConcretePresenter onSubject: concreteSubject. instead, as seemingly this would achieve the presenter creation anyway?

The answer to this question is as follows: While the latter code is certainly possible to use in principle, we have seen in the overview of Subject APIs above, that Hopscotch provides the method Subject>>#presenter which not only creates the Presenter instance by calling Subject>>#createPresenter, but also wires up the Presenter <-> Subject associations!

Clearly, the framework intents application code not to create Presenter instances directly, but intends for application code to call Subject>>#presenter. However, this call should not be made directly in application code either. In chapter HopscotchForHTML5: Analyzing senders of Subject>>#presenter and why HopscotchWindow>>#openSubject: subject should be invoked instead we provided some long reasoning for the following conclusion:

Conclusion 4: The root level of an application should not create Presenter directly or by calling Subject>>#presenter directly. Instead, application should invoke

HopscotchWindow>>#openSubject: subject

This invocation eventually invokes Subject>>#presenter as intended, but does additional work of placing the creater Presenter instance in the context of the container body.

So we arrived at a summary conclusion.

Summary conclusion: Here is the code for a barebones Hopscotch App

|concreteModel concreteSubject concretePresenter|
concreteModel:: ConcreteModel new.
concreteSubject:: ConcreteSubject onModel: concreteModel.
hopscotchWindow openSubject: concreteSubject.

The last line will create instance of ConcretePresenter by calling ConcreteSubject>>#presenter and open it in a new window where the Application will live! This snippet does not show code of ConcreteModel ConcreteSubject ConcretePresenter, or how we obtain the hopscotchWindow. We will get to that when creating a concrete Application in Using Hopscotch discovery a Model-Presenter-Subject Application, the CheckedItemApp

This chapter is about the Presenter class, in particular about three "important parts" we should know to understand the Newspeak UI. Those parts are also important when we write code for concrete implementations of Presenter.

Let us show the code for the Presenter class, keeping only the "important parts" - each of them is discussed in subchapters below.

(* The primary factory method.
   The constructor also creates the association from Presenter instance to Subject instance
   by keeping the associated subject slot
*)

public class Presenter onSubject: aSubject <Subject> = Fragment (
  |
  public subject <Subject> ::= aSubject.
  substanceSlot <Fragment>
  public generation <Number> = uiGeneration.
  |
) (
  
  
  (* The unimplemented (abstract) method "definition"
     which a concrete Presenter implementation must provide.
     Implementations should return a Fragment - something that shows a UI.
  *)
  
  public definition ^<Fragment> = (
    subclassResponsibility
  )

  (* Further unimplemented (abstract) methods inherited from Fragment *)

  isMyKind: f <Fragment> ^ <Boolean> = (
    subclassResponsibility
  )
  
  (* A few selected methods which allow Presenter instances to create instances of Fragments - Fragments are UI Widgets
  *)

  row: definitions = (
	  ^RowComposer definitions: definitions
  )
  button: label <String> action: block <[]> = (
    ^ButtonFragment label: label action: block
  )
  checkbox: text <String> value: v <Holder> action: a <[:Boolean]> = (
    ^CheckboxFragment text: text value: v action: a
  )
  radioButton: text <String> value: v <Holder> group: g <Integer> action: a <[:Boolean]> = (
    ^RadioButtonFragment text: text value: v group: g action: a
  )
  rectangle = (
    ^RectangleFragment new
  )
)

In the subchapters below, we go over each of the "important parts".

The primary factory method has the exact signature

public class Presenter onSubject: aSubject <Subject> = Fragment (..)

It creates a presenter on subject, and also establishes the association from Presenter instance to Subject instance as slot Presenter>>subject.

The precise signatures of unimplemented methods that each concrete Presenter must provide:

• Presenter>>#public definition ^<Fragment> should create and return the actual "widget" (presentation view)
• Presenter>>#isMyKind: f <Fragment> ^<Boolean> is repetitive but required. It is inherited from class Fragment. We have a common chapter for this, see The formulaic required repetitive methods of #isMyKind: and #isKindOfX

Fragments are UI Widgets.

It is worth realizing there are instance methods on Presenter which can create Fragments (widgets). Such widgets perform

• layout (see method #row: or #column: on class Presenter)
• "atomic" widgets (see method #button: label or checkbox: text

Browse the IDE for more details.

In addition, from the Presenter factory

public class Presenter onSubject: aSubject <Subject> = Fragment (
  |
  public subject <Subject> ::= aSubject.
  substanceSlot <Fragment>
  public generation <Number> = uiGeneration.
  |)

we see that Presenter extends Fragment.

What is Fragment and what is it's role? Let us look at Fragment in a separate chapter.

The goal of this chapter is to discover more about HopscotchForHTML5 and how it relates to HopscotchForHTML5Runtime.

Ok, so we "know" that HopscotchForHTML5 provides the Newspeak UI for the web version. We have seen it defines (as nested classes) the core UI classes Subject, Presenter, and Fragment.

Looking at the top level, we see two related classes, HopscotchForHTML5 and HopscotchForHTML5Runtime. So what is the latter class good for?

Let us get back for a minute to HopscotchForHTML5. We have seen, that is has a ton of slots and classes we would associate with UI elements, such as

(* primary factory method *)
class HopscotchForHTML5 usingPlatform: p images: images ducts: ds = (
  |
  (* Imports *)
  private Color = p graphics Color.
  private Context = p graphics Context.
  private Holder = ds Holder.
  private Font = p fonts Font.
  .. etc ..
  public styleZebraPrimaryColor = Color white.
  public styleZebraSecondaryColor = Color gray: 0.97.
  |)

(* Selected nested classes *)
class ButtonFragment
class DatePickerFragment
.. etc ..
class Subject
class Presented
class Fragment
.. etc ..

We alreary concluded that we will need an instance of HopscotchForHTML5 if we want to build any UI for our Apps.

Analyzing the class HopscotchForHTML5Runtime, we see that:

• It has the primary factory method #packageUsing: manifest. From the Api chapters, for example 4. Application module: API of module that needs to be distributed as an App we know that such top level classes are apps, but, lacking the #main: platform args: args method, such module is used as library module. The primary factory which packages the UI class, HopscotchForHTML5, on it's slot Hopscotch along with other UI-required classes Fonts, Graphics, etc:

  (* primary factory method *)
  class HopscotchForHTML5Runtime packageUsing: manifest = (
    |
    private Fonts = manifest FontsForHTML5.
    private Graphics = manifest GraphicsForHTML5.
    private TextModule = manifest TextModule.
    private Hopscotch = manifest HopscotchForHTML5.
    private Ducts = manifest Ducts.
    private images = Images packageUsing: manifest.
    |
  )
  

• It also has an instance method #using: platform, which calls the primary factory method of PlatformWithHopscotch and returns it's instance. When running the web-based Newspeak, the returned instance is the platform <PlatformWithHopscotch> object, passed to any primary factory of any module that needs a platform,

  public using: platform = (
  	^PlatformWithHopscotch usingPlatform: platform
  )
  

The presence of the two methods clearly shows HopscotchForHTML5Runtime packages all three classes (HopscotchForHTML5, Ducts, images) that we will need to create HopscotchForHTML5 using its primary factory method HopscotchForHTML5>>#usingPlatform: p images: images ducts: ds.

So, the HopscotchForHTML5Runtime packages everything we need for HopscotchForHTML5

In addition, we see that the inner class HopscotchForHTML5Runtime>>PlatformWithHopscotch is a convenience class which already pre-creates instance of HopscotchForHTML5 in this PlatformWithHopscotch snippet:

class PlatformWithHopscotch usingPlatform: platform = (
  (* primary factory method *)
	|
    public isKindOfPlatformWithElectron = platform isKindOfPlatformWithElectron.	
    public kernel = platform kernel.
    public collections = platform collections.
    public actors = platform actors.
    public mirrors = platform mirrors.    
    public js = platform js.
    public operatingSystem = platform operatingSystem.
    public fonts = Fonts usingPlatform: self.
    public graphics = Graphics usingPlatform: self.
    public text = TextModule usingPlatform: self.
    public hopscotch = Hopscotch usingPlatform: self images: images ducts: (Ducts usingPlatform: self).
    public local = platform.
    public victoryFuel = platform operatingSystem = 'emscripten' ifTrue: [platform victoryFuel].
	|
)

A core question: what object is in the slot hopscotch in the above factory? Let's follow these points:

1. HopscotchForHTML5Runtime, the outer class of PlatformWithHopscotch creates this slot:

   private Hopscotch = manifest HopscotchForHTML5.

   clearly, the Hopscotch slot on HopscotchForHTML5Runtime holds the class HopscotchForHTML5.

2. Next we see this line in the PlatformWithHopscotch primary factory method above - the class PlatformWithHopscotch usingPlatform: platform:

   public hopscotch = Hopscotch usingPlatform: self images: images ducts: (Ducts usingPlatform: self)

   uses the expression Hopscotch. What does it refer to?? In Newspeak, an expression like this used in a primary factory method slot, must be somewhere in the scope of the primary factory method's scope! The only items in scope there, must be in a slot of a parent class! Parent class of PlatformWithHopscotch is HopscotchForHTML5Runtime. So this Hopscotch we are talking about here refers to a Hopscotch slot in HopscotchForHTML5Runtime. And we have seen in item 1, that it holds the class HopscotchForHTML5. As a result, the primary factory method in

   public hopscotch = Hopscotch usingPlatform: self images: images ducts: (Ducts usingPlatform: self)

   is the same as

   public hopscotch = HopscotchForHTML5 usingPlatform: self images: images ducts: (Ducts usingPlatform: self)

From there we have the answer to our core question of this paragraph: The slot hopscotch in the factory for PlatformWithHopscotch is instance of HopscotchForHTML5

Now let's draw two conclusions we arrived at in this paragraph:

1. Conclusion 1. The module HopscotchForHTML5Runtime is a packaging library for instances of HopscotchForHTML5. By packaging the runtime, everything we need to write UI code is available in the HopscotchForHTML5 instance. How do we get such instance? This is described in Conclusion 2.

2. Conclusion 2. Any code that is able to create hopscotch, an instance of HopscotchForHTML5Runtime will have access to instance of HopscotchForHTML5 using the second line below:

   hopscotch using: platform. <== this is instance of PlatformWithHopscotch (hopscotch using: platform) hopscotch. <== hopscotch is the slot on PlatformWithHopscotch. hopscotch is instance of HopscotchForHTML5 as we have seen above.

3. Conclusion 3. The module HopscotchForHTML5Runtime can be asked for the platform object. The platform type is <HopscotchForHTML5Runtime>>PlatformWithHopscotch>, and is passed to any module when running in context of the Web based Newspeak.

Summary: In this chapter, we deduced code we need to obtain hopscotch, an instance of HopscotchForHTML5. This instance is all we need to write any Newspeak UI.

This chapter uses Hopscotch knowledge acquired in the above chapters, to develop a sample UI Application in Newspeak.

As with other Applications with UI, we will need two top level classes. Let us name the Application class CheckedItemApp and it's UI class CheckedItemUI. The basic structure of an Application with UI was already described on several examples, including Code, run, and debug the CounterApp in Newspeak .

The knowledge about a structure of a UI class, the Model-Presenter-Subject was developed by browsing the HopscotchForHTML5 in Discovery of the HopscotchForHTML5 class basics, and is used below in 3. Write code for CheckedItemUI, the class showing the UI.

We will use information about APIs that define a Newspeak Application from chapter 4. Application module: API of module that needs to be distributed as an App and 3. Hello World from Application to create the application class CheckedItemApp.

First, we create the class for a top level Application module. We can create this class in the IDE, or create the class in a text file, then "Compile file(s)". We start with a text file.

Regarding the methods the CheckedItemApp class should have, there should be a primary factory #packageUsing: manifest and an instance method #main: platform args: args. This makes the class a packageble, distributable, and runnable Newspeak app (an Application module). See Newspeak modules API zoo for Newspeak "convention methods" signatures.

class CheckedItemApp

class CheckedItemApp packageUsing: manifest = ()
(
  public main: platform args: args = (
    'Hello World from HelloWorldApp' out.
  )
)

Chapter introduction and goal: In this chapter, we will write CheckedItemUI, the UI of the application. The UI code will be spread over several nested classes of the top level class CheckedItemUI. To write this UI, we will use the knowledge discovered and summarized in chapter Summary of Subject and it's model, Presenter and Fragment, their associations, and their lifecycle. We will need to create concrete nested classes for the Model, Subject and Presenter, then we will need to instantiate those classes (in that order) to form the UI.

The UI will be extremely simple: a label with text "check this", and one check box. We should be able to check the checkbox. That is all.

Note that we will not write any Fragment (Widget) classes, we only use some preexisting fragment-creation methods discovered by browsing HopscotchForHTLM5>>Presenter such as #row:, #label: and #checkbox:.

Chapters below describe writing the code for CheckedItemUI step by step.

So far we have prepared two separate classes:

1. CheckedItemApp: We created this class as a (so far almost empty) top level class in 1. Start coding the Application class CheckedItemApp. We equipped the class with API methods that make the class instance an application.
2. CheckedItemUI: We added this class in step 3. Write code for CheckedItemUI, the class showing the UI. In that step, we also added the code that creates a row of widgets (fragments) in the CheckedItemUI>>#define method.

In the rest of this chapter, we finish integrating the CheckedItemUI into the CheckedItemApp by creating an instance of CheckedItemUI in the main method of the CheckedItemApp. This instance creation will perform the process of showing our UI, defined in the CheckedItemUI>>#define method.

The complete code and UI of the CheckedItemApp can be found here:

https://github.com/mzimmerm/newspeak-doc/tree/main/newspeak---a-few-notes-code/checked-item-app

To skip the coding details above, we can "Compile file(s)" to load full finished code from there and study it. The classes will appear in the IDE.

Clicking the [run] executes the app from the IDE, and presents its UI:

and after checking the item we get

You can also package it and run the Application as a standalone .vfuel file from the IDE, by clicking the [deploy] link beside the class name, then selecting "As VictoryFuel with Mirrors".

More details on deployment for another sample Application is in the intro section around Make deployment file for CounterApp

Note: The code for the CheckedItemApp built here is as simple as it can be, to focus on understanding HopscotchForHTML5. The Application should be improved in the future. The main weakness of the current version is that it exposes model publicly - model should be private wrapped in Subject.

This concludes the chapter that explores writing UIs in HopscotchForHTML5.

Use the following code to create a dropDownMenuFragment instance in our ConcretePresenter class.

1. menu, (which is simply an instance of a list of menu label/menu action tuples). For future proof, call the method Presenter#menuWithLabelsAndActions:labelActionList to create the menu, for example

   menu = menuWithLabelsAndActions: {
       {'Save to File'. [respondToSave]}.
       #separator.
       {'Delete'. [respondToDelete]}.
     }
   

2. dropDownMenuFragment, an instance of DropDownMenuFragment, which is a wrapper for the menu. This instance is created by calling the #Presenter#dropDownMenu:menu. Using this line in our code will wrap the menu into a drop down menu shown in the GUI with two items: 'Save to File' and 'Download'.

   dropDownMenuFragment:: dropDownMenu: menu. 
   

When we want to add to GUI a popup menu which shows after clicking on an image, and understand it's working internals, follow this section.