Interactive Magik tutorials with Emacs’ eval and print

Learning Magik becomes considerably easier when code can be evaluated while you are reading and editing it. Emacs turns a tutorial from a static page into a working environment: select a method, send it to a Magik session, inspect the result, adjust the code, and run it again without losing your place.

This style suits GE Smallworld development, where understanding an object, collection, database record, or inherited method often matters as much as writing the final expression. The combination of Emacs, a Magik REPL, evaluation commands, and carefully placed print statements gives developers fast feedback on how the runtime behaves.

It is also a practical fit for Australian teams. A developer in Melbourne may be pairing with a colleague in Brisbane, while a consultant supporting a Perth or regional utility project works against a remote environment. Interactive examples reduce the delay between a question in a Teams call and evidence from the running system.

Connecting Emacs to a working Magik session

An interactive tutorial begins with a reliable connection between Emacs and the Magik environment. Depending on the local setup, this may be a terminal session, a Smallworld image, or an Emacs extension that sends expressions and regions to a live interpreter. The important point is that the editor and runtime can exchange code and output repeatedly.

Start with a harmless expression that confirms the session is active. In Magik, this could be a simple arithmetic calculation, a string operation, or an inspection of a known object. Send the expression from Emacs, observe the printed response, and then repeat it with a small change. This first exercise verifies that the correct image, workspace, and project environment are connected.

A useful tutorial should explain where results appear. Some configurations place output in a dedicated buffer, while others show it in a shell or REPL window. Developers should learn how to switch between the source buffer and the evaluation buffer, clear old output, and recognise an error message without confusing it with ordinary printed data.

Australian organisations often maintain separate development, test, and production-like Smallworld environments. A session name or prompt is therefore worth checking before evaluation. A quick inspection in a Sydney office or from a home connection in Hobart can prevent code being sent to the wrong image, especially when several remote sessions are open.

Using eval for small, deliberate experiments

The most effective Magik tutorials begin with small expressions rather than complete application classes. Evaluate a literal, assign it to a variable, call a method, and then inspect the resulting value. Each action should answer one narrow question about syntax or behaviour.

For example, a lesson might create a collection, add a few values, and evaluate an expression that returns its size. The learner can then change the collection, send only the changed lines, and compare the result. This creates a tight edit–eval–observe loop that is faster and clearer than repeatedly running a large application workflow.

Region evaluation is especially helpful when exploring a method. Select the method body or a short block, send it to the live Magik process, and watch for syntax or runtime feedback. When a method depends on an existing object, the tutorial can first establish that object in the session and then evaluate the method against it.

Whole-buffer evaluation has a place, but it should come later. Sending an entire file can hide which expression caused an error and may overwrite definitions that the learner is still trying to understand. Short evaluation units make the history of an experiment visible and help developers build confidence with Magik’s object-oriented syntax.

This approach is valuable during client work in Australia, where project knowledge may be shared across a small consulting team rather than a large training department. A reproducible sequence of expressions can travel with a ticket, a pull request, or a handover between a Melbourne developer and a field team in regional New South Wales.

Making print output useful

Print statements are most useful when they explain the state of an experiment. Printing an object, a collection size, a key attribute, or a class name gives the learner evidence about what the code actually received. A bare value can be difficult to interpret, so descriptive labels make tutorial output easier to scan.

A simple pattern is to print a label followed by the value being examined. For a collection exercise, output might identify the collection type, the number of elements, and one representative item. For a database-related example, output can show an identifier and selected attributes rather than dumping an entire record into the REPL.

Too much output makes interactive work noisy. A tutorial should demonstrate how to narrow a print statement after the first inspection. Begin with the object, identify the useful property, and then print only that property in later iterations. This mirrors normal debugging practice, where the goal is to reduce uncertainty rather than produce a wall of text.

Printed output also helps explain object identity and method dispatch. Two values may look similar while belonging to different classes, and a method may return a new object rather than modify the original one. By printing the class, selected state, and returned value separately, learners can see those distinctions directly.

When output is copied into documentation, Australian spelling and local domain examples can make the material easier to recognise. A tutorial using a water-network feature, cadastral record, or transport asset will feel more relevant to teams working with state utilities, councils, and infrastructure providers than an abstract example alone.

Inspecting objects and navigating methods

Evaluation becomes more powerful when paired with inspection tools. Once an expression returns an object, the next step is to discover its class, available methods, inherited behaviour, and important attributes. Emacs can support this workflow through navigation commands, source lookup, code folding, and buffers that keep related definitions close at hand.

A practical tutorial should move from observation to navigation. Print the object, identify its class, jump to the relevant method, and evaluate a small variation. If the method calls another method, follow that call rather than treating the original definition as a black box. This builds a mental model of the framework as a network of collaborating objects.

Code folding is helpful when a Magik source file contains many methods. Collapse unrelated sections, keep the active method visible, and send only the region being studied. Method navigation reduces the time spent searching through large application packages, particularly when class definitions have accumulated over years of project customisation.

The same workflow supports debugging. A learner can place a diagnostic print before and after a method call, evaluate the region, and compare the values. If the result is unexpected, inspect the receiver and arguments before changing the implementation. This preserves the distinction between a faulty assumption and a faulty method.

Teams that maintain older Smallworld estates often need to understand existing code before making changes. A clear Emacs workflow is therefore useful for consultants travelling between Brisbane and the Gold Coast, or for developers supporting a client remotely from Adelaide. It provides a disciplined way to investigate unfamiliar code without relying on guesswork.

Exploring collections and database results

Collections are a natural subject for interactive Magik lessons because their contents can be changed and inspected quickly. Begin with a small, known set of values. Evaluate insertion, removal, iteration, and selection operations one at a time, printing the size and a few values after each change.

The tutorial should explain the difference between changing a collection and producing another collection. Evaluate the original expression, store the returned result, and print both objects where appropriate. This makes it easier to recognise whether a method mutates state, returns a filtered view, or creates a separate result.

Database and GIS examples require extra care. A live query may return a large number of records, so print counts and selected fields first. Limit the result set during exploration, and avoid printing sensitive or unnecessary attributes. A learner can still understand query behaviour without flooding the Emacs buffer or placing production data into a shared transcript.

A useful exercise might inspect a handful of network features, print their identifiers, and follow one feature to a related object. The next step could evaluate a method that calculates a property, then print the input identifier and calculated result together. This creates a trace that can be checked by another developer.

Interactive work also benefits from repeatable paths and project configuration. When a source directory or package is not being found, a short path copy guide can help resolve the editor-side setup before the lesson moves into Magik behaviour. Separating configuration problems from language problems saves considerable time.

Building tutorials that developers can reuse

A strong tutorial has a visible rhythm: prepare the session, evaluate a small expression, print a meaningful result, inspect the related object, and record what changed. Each step should be executable in Emacs and should leave the session in a sensible state for the next step.

Keep examples independent where possible. A learner who joins halfway through should be able to recreate the current object or collection without running an entire application. Setup code can be placed in a clearly marked block, while the expressions under discussion remain short and easy to send to the REPL.

It is also worth documenting expected output without making the lesson rigid. Object ordering, database contents, image configuration, and project customisations can affect results. Explain the important shape of the output, such as a count increasing from three to four or a returned object changing class, rather than insisting that every character must match.

Use print statements as temporary instrumentation, then show how to remove or refine them. This teaches a professional habit: diagnostics are valuable during investigation but should not become permanent noise in production methods. Where a debugger or object inspector is available, explain when it provides better detail than printed values.

The following comparison summarises which interactive technique suits each learning task:

Learning task	Emacs action	Useful output	Best result
Check a live session	Evaluate a small expression	Simple value or prompt response	Confirms the correct runtime
Learn syntax	Send a short region	Returned value and error location	Fast correction of small mistakes
Explore a collection	Evaluate one operation at a time	Size, selected items, class	Clear view of state changes
Understand a method	Navigate to definition and evaluate	Arguments, receiver, return value	Better grasp of dispatch and flow
Inspect database data	Run a limited query	Count and selected attributes	Safer, more readable exploration
Investigate a defect	Add temporary prints or use inspection	Before-and-after state	Evidence for the cause of a problem

A reusable tutorial should finish with a compact exercise that combines these techniques. For example, create or retrieve an object, call a method, print the relevant result, navigate to the implementation, and repeat the experiment with a changed input. The learner should finish with a working session and a clear record of what was observed.

Use Magik Emacs tutorials as working documents rather than pages to read once. Connect to a safe development image, evaluate each example, print only the evidence you need, and keep the useful snippets beside the project code. That practice turns language documentation into a repeatable investigation tool for everyday Smallworld development.