Cuis CookBook - User contributions [en]

The Cuis Cookbook

2025-06-03T14:00:44Z

Ssmith2112: Fix typos

A programming language cookbook is something like ''[https://stackoverflow.com/ StackOverflow]'', without the digging part and the try&pray experience. For a gentle and structured introduction to Cuis-Smalltalk, you should start with the '''The Cuis Book''' and '''Learning-Cuis''' more about this in [[CuisCoookBook-References|References]]. This is intended to be a resource for programmers, in the sense that it answers questions that will naturally come up to programmers while exploring Smalltalk.

'''Reliability'''. I am writing these notes while learning Cuis. Some of what I write may not be the best way to solve the problem, it may not even be correct. Be patient, double check. Since I use these recipes myself I am going to improve them in time.

'''Sorting principles'''. Topic order is intended to go from easy to difficult. From frequently necessary to rarely used. From needed at the beginning of the programming experience to needed by black belts. These three forces, as with the 3 laws of robotics, regulate what chapter goes toward the top of the document. They hold also for sub-chapters and articles.

'''Contributions'''. I am trying to figure out ways to make contributions possible and fruitful, see [[contributions motivated guidelines]]. As a write I see that [[format guidelines|format guidelines are also important]].

'''Copyright'''. You have the right to read, print for your own use, and contribute to the document. You can make external links to this document. You can not copy the document and make it available somewhere else on the Internet. You can't claim ownership. You can't bring the document to an editor and publish it. I, as the author of more than 99% of the words displayed here, retain all rights as well as the right to change these rules.

* [[Introduction]]. What you should expect from this book and the reason why I am writing it. STARTED.
* [[Why Smalltalk?]]. For what reason should you learn another programming language which is also not so popular? Read on, there are very good reasons. STARTED.
* [[Why Cuis Smalltalk?]] . TODO
* [[MetaCookbook]]. Collection of things about this document.

== Installation and start up ==

* Install and run Cuis in Windows
* Install and run Cuis in MacOS
* [[Install and run Cuis in Linux]]
* [[Run Cuis in the Web Browser. (SqueakJS)]]
* [[Run Cuis in a ARM platform, RPi, BeagleBone and similar. (Linux)|Run Cuis in an ARM platform, RPi, BeagleBone and similar. (Linux)]]
* Run Cuis on a remote server. (Linux)
* Run Cuis on the metal: without an Operating System
* How to keep Cuis updated
* [[How to load the most recent changes Juan made to Cuis-Smalltalk-Dev]]

== Cuis in its environment ==

* What is a .image file?
* What is a .changes file?
* [[What is a .user.changes file?]]
* [[What is a .log file?]]
* [[What is release of the image and VM I am running?]]

== Things unique to Cuis and/or Smalltalk ==
Here are all the things that are totally unknown for anybody who has never programmed in any Smalltalk.

* [[How can I make X? Learn to fish in Smalltalk|How can I make X ? Learn to fish in Smalltalk]]
* [[First things first: 1+1 and "Hello World"]]
* How can I type in a basic object ? [[Know the literals]] !
* [[You want something to get done? Ask an object to do it!]]
* [[How do I define a function?]]
* [[How do I create my own Class with some methods inside it?]]
* [[What is a package? How do I create, load and unload one?]]
* [[My project needs to add a method to somebody else Class, how do I do it?|My project needs to add a method to somebody else Class, how do I do it ?]]
* [[How to use Class variables]]. STARTED
* [[Learn how to use the Transcript]] . This is really important, you should take a peek.
* [[Tips & tricks]] . Those little keyboard/mouse shortcuts or little code snippets that may improve your programmer life.
* [[Traps and pitfalls for polyglot developers]] . If you know more programming languages this page is for you.
* [["It didn't understand" can't happen]]. The end of most of your programmer anxiety. You can understand it all.

== About a general Class and Object ==

* [[Create automatically all accessors for a Class instance variables]]
* [[Change the way an Object is printed]]
* [[Find all objects referencing anObject]]
* [[Make your own object initialization]]. All you need to know about <code>new</code>, <code>basicNew</code>, <code>initialize</code> etc. STARTED
* [[How to dump and restore an Object]] -- STARTED
* [[How to manage a Class who should have only one instance]]
* [[Discover in what package a Class lives]]
* [[Follow step bye how a method call gets resolved. Example-1]]

== Data Structures ==

* Fundamentals: numbers, strings and symbols

=== Strings (before default UTF) ===

* [[Cuis-What Strings are made of and how|What Strings are made of and how]]
* [[Cuis-String escape|String escape]]
* [[Cuis-Automatically escape a complex string|Automatically escape a complex string]]
* [[String formatting with format:]]
* [[String formatting with printf:]]
* [[A thousand ways to say new line]] . Newline, to text find it fast
* [[Trim white chars]]
* [[String joining]]
* [[String splitting]]
* [[String search]]
* [[String replace]]
* [[Show me the string, but max N. characters]]
* [[Dump and restore JSON data strings]]
* [[How to hash a string]]
* [[Convert to Base64]]
* [[Convert strings from/to Utf8]]
* Remove accents with, <code>'sarà' asUnaccented . => " 'sara' "</code>
* [[Convert UTF16 to Latin1]]. This is quite useful, in Windows-10 UTF16 is called Unicode.
* Jump to the next level of power, [[use Regex]] . Last in the list for complexity, but should be first for power, don't overlook this.

=== Collections ===

* [[The things you may call a List]] -- STARTED
* [[Array]]
* [[Dictionary a.k.a. Hash Table]]

== Streams ==

* [[Make a stream from a string, for reading]].
* [[Write a long String with a Stream]]
* [[Write to stdout in any system]]. Not only Unix like. Useful for shell programs.

== Date and time ==

* [[Get the current date and time]]
* [[Format date and time as you like most]]
* [[Date and time algebra]]
* [[Get the current time with the highest precision]]
* [[Get date and time as Unix epoch]]
* [[Get date and time in a different country]]
* [[Measure how much time it takes to run a code block]]

== Files and directories ==
You should keep in mind that Smalltalk uses files but it is not based on files. I copy here

part of a ''Juan'' mail to mailing list: "... The essential idea you need to be aware of when learning about all this is that Smalltalk uses files, but it is not file-based. What this means is that all the tools in the Smalltalk image (with the only exception of FileList and FileContentsBrowser) are NOT showing files, but '''live objects'''. The way them relate to files is usually not really important ...".

* [[How to Read or Write a text file]] . without Streams, only Strings.
* [[How to Read or Write a text file with a Stream]]
* [[Read a file line by line]] . Or any general delimiter.
* [[Find the current directory, list it and move in the directory tree]]
* [[Filename extensions]]: .txt, .csv, .json ...
* [[Check things on a pathname. Is there anything? Is it a file? Is it writable?]] ...
* [[Delete files and directories]]
* [[Read/Write a binary file]]
* [[Create a new non-existing file name]]
* [[Using file locks]] -- TODO
* [[Get the list of open files]]
* [[Get the directory where a Class (its Package) is stored]]
* [[Where is the image file? Where is the VM?]]

== Error Handling and the Debugger ==

* [[Call the debugger from a code location]]
* [[Quick exception handling]], equivalent of Python <code>try ... except</code>
* [[Assertions]]
* [[Errors, raise and catch signals]]
* Case-study-1. '''TODO'''. When the debugger pops up send me an email
* b

== Processes ==

* [[Smalltalk processes are not Unix processes]]
* [[See the list of running processes]]
* [[Processes 101]]. Shows how to create a process, name it, start it, stop it and destroy it.
* [[Run a new process]]
* [[Kill a process]]

== Uncategorized useful features ==

* [[Run a method every 2 hours or every day at 15:00]], equivalent to Unix cron
* [[Zip and unZip files and directories]] --- TODO, miss zipping
* [[Convert a file to/from Base64]]
* [[Deal with XML files]] -- STARTED
* [[About Random]]
* [[How to invoke the garbage collector]]
* [[Adapt newline characters to Cuis standard]]
* [[Where to get information about the hardware]] . Screen size, free memory, cpu speed ...
* [[The Dependency Mechanism - part 1]]. Here we talk about the Smalltalk classic '''Parent''' - '''Dependent''' model.
* [[The Dependency Mechanism - part 2]]. Here we explain the why of a '''Model''' class.
* [[The Dependency Mechanism - part 3]]. Here we talk about the '''Observer Pattern'''. (preferred current method in Cuis)
* How to use the '''serial port'''. See [https://github.com/nmingotti/Cuis-Smalltalk-SerialPort SerialPort] package, it has documentation.

== Run external programs ==
If you run Cuis in Linux/Unix, and to some extent also in the Mac, you can use thousands of already written shell programs that solve the most diverse issues. Examples:

* Do you want to know how much free space is available on the disk?
* How many wireless networks your computer can see?
* Run an R script to make a fantastic plot?
* ... these and thousands of other things are possible once you are able to leverage the power of Unix from Cuis.

You can perform these kind of operations with the module <code>OSProcess</code> included in Cuis or with the external package <code>CommandShell</code>. The second is easier, the first is lower level => more difficult but more flexible.

* [[Traps and pitfalls specific to running external programs]]
* [[The basics of interacting with Unix]] . Find this process <code>pid</code>, <code>ARGV</code>, <code>ENV</code> , <code>stdin</code>, <code>stdout</code>, <code>stderr</code> ... and all those fundamental things.
* [[Run a program with OSProcess]]
* [[Run a program with CommandShell]]

== Networking and the Web ==

* How to ping a computer
* How to discover the IP of a given host name
* How to get a webpage's content

== Databases ==

* Talk to '''PostgreSQL'''. See the PostgreSQL package, it has documentation.
* Talk to MongoDB
* Talk to SQlite

== Scripting Cuis ==
This section is about setting Cuis to start up in the way you like it, on any image you may want to boot.

* Author name and initials programmatically
* Set your preferred font size
* Set your user name
* Stop the system from asking to save the image on pressing Cuis World->Quit
* An example of customized Cuis startup Requires only one executable script file !
* Do ENV variables affect Cuis ?
* How do I pass a string to be executed by Cuis when it boots ?
* How do I pass a file to be executed by Cuis when it boots ?
* How to quit Cuis immediately. No questions asked.

== Scripting with Cuis ==
Is it possible to make Unix scripts with Cuis? Does it make any sense? This section explores these subjects.

* Initial considerations. here

= Delivering an application written in Cuis =
This section explores ways in which you can have other people, non programmers, use your coolest applications. To run the application it may be necessary to: [1] Run VM and an Image [2] Run VM + Image + some code snippet passed as a String [3] Run VM + Image + a script file.

* Deploy a Cuis application in Linux
* Deploy a Cuis application in Windows-10
* Deploy a Cuis application in MacOS

= Morphic Cookbook =

* Basic operations with Morphs
* Kill a Morph . A few ways to destroy a Morph.
* Place Morphs in World as you wish, automatically
* Drawing and pictures with the ImageMorph
* Application. Convert a color image to black and white
* Application. Show contours in an image
* How to layout the Morphs . This is the basic step to know prodromic to make your own GUI in Cuis.
* Fonts - 1. First interactions with Fonts
* Basic event handling in Morphic . Here we see how to do something when a mouse button or a key on the keyboard get pressed.

= The Sound system =
To some people doing programming is manipulating sounds. As for some other people it is building a nice graphical user interface or some one else does networks services. For this reason the sound system chapter is placed after Morphic.

All this chapter requires you to load the sound module. <syntaxhighlight lang="smalltalk">
Feature require: 'Sound'.
</syntaxhighlight>
* [[First experiments with sound]] . Collecting knowledge here, when ready will be split into topics
* [[Play a melody writing a list of note names and their duration]] . Ok for note in the format C,D,E... TODO for notes with Italian names: Do, Re, Mi...
* TODO. Realtime sound playing. On event play immediately a sound, simulate and instrument typing on your computer keyboard
* [[Create and play *.wav files]].
* [[References to the Sound system]] . for further study

= Introspection and The compiler =
These notes are taken reading the wonderful document "The HitchHiker's guide to the Smalltalk Compiler" by Vassili Bykov, here .

* get the current World object.
* what happens when Cuis start up.
* the main loop.
* The Cuis scanner.
* The Cuis parser.
* See the compiled code.

= The Virtual Machine =

* Building the Virtual Machine
* Building the VectorGraphics plugin
* Choosing between FFI and plugin
* Run a script with a proper window title

= Applications built on Cuis =

* DrGeo.
* Borghi DataStreamer.

== TODO ==
These are reminders for me about things to do in the Cookbook or in Cuis

* '''DEV'''. SpellChecker, for text panes in Cuis. It would be useful to be able to spellcheck comments in code. I like to put comments, without spell checker they are so full of bugs they appear really untrustworthy.
* Video about class variables.
* Page about ';' -- '::' -- 'yourself'.
* Video about installation of Cuis, not so easy the first time
* Video about updating Cuis, not obvious
* Video about using the Transcript efficiently
* Video about creation of a minimal GUI
* Video about creation of a minimal application, runnable from Linux command line
* Video about creation of a minimal application, runnable from Windows GUI
* Video about making Tests, and discovering how to use existing classes with them
* Video-or-page about variables, especially class variables

Format guidelines

2025-06-03T13:51:01Z

Ssmith2112: Fix typos

* Accumulating material
* '''variable assignment syntax'''. Use <code>':='</code> instead of <code>'-'</code>. Ratios. I like <code>'_'</code> more, when it is rendered in Cuis XXX-SHOW-IT-UNICODE-XXX but there is a problem. (1) If we use the backward directed arrow the new user will be in trouble since he will not know how to type in that thing. (2) In other Smalltalks <code>':='</code> is used more often, as far as I know.
* '''Syntax highlighting in big code chunks'''. It is much easier to read. The automatic highlighter in Mediawiki does a good job. To insert code you need to do Insert -> More -> Code Block.
* '''Typing in small code chunks (inlined code)'''. At the moment I haven't found a way to highlight inlined code. To type in inlined code for the moment do: (1) select a code chunk (2) Click '''A''' -> Computer Code .
* '''Mouse button name by left-right order'''. Always use the convention first, second, third button. The ordering is left to right. Mice are supposed to have 3 buttons. If people have strange mice (see Apple) they know already how to simulate the 3 buttons. Don't use the button color names as it is done in Squeak. As of today naming mouse buttons by color just adds to the complexity and perplexity of the new user.
* aaa

Why Smalltalk?

2025-06-02T14:36:05Z

Ssmith2112: Fix typos

NOT COMPLETE -- ACCUMULATING MATERIAL

It would be easy here to fill 10 pages of abstract concepts, I don't want to do that. We will compare Smalltalk with another language, a popular one, a good one: Python. If you already know Python, why should you learn Smalltalk?

Let's start from a fundamental concept, almost all popular programming languages can solve almost all existing problems. So why learn more than one? Well, quoting ''Wittgenstein,'' "My language is my world", this holds true also for programming languages. When you choose a programming language you mostly don't choose what is possible for it to do, but what will be easy to achieve according to you or your organization's taste and preferences. For example, in C you can directly access memory locations, in Python and Smalltalk you can't easily, therefore if you are working at a very low level, e.g. you are writing a driver, C is a more fit tool. On the other side, suppose your problem is to find the 10 largest files in your computer that were last opened more than 1 year ago. In C, to do this will take about 1 hour, minimum. In Python and Smalltalk you can do it in a few minutes.

Factors useful in deciding the programming language for your next task.

* '''execution speed'''. How fast does your code need to run? Here the fastest are C, Fortran, and C++. Python and Smalltalk can't even compare to them. TODO COMPARE Python and Smalltalk speed.
* '''cross OS portability'''. Can you run your code in a Mac, Windows, Linux, BSD? Here Python and Smalltalk are very good and C is very bad, your code is going to run on the major OS without changes or with little changes. For example in Windows the root directory is 'C:\' in Unix like systems it is '/'. These little things must always be fixed. In C you would need to compile a specific version of the program for every OS.
* '''cross architecture portability'''. Can you run your code in a normal PC as well as in a Raspberry Pi, in a BeagleBone Black, in a Web browser? In C this is a problem. Python is quite portable, and Smalltalk is the king - it can run in very different platforms, for example with [https://squeak.js.org/ SqueakJS] you can run your program written for a PC right on the Web. You can't do this easily in any other programming language to my knowledge.
* '''library availability for your task'''. Here C is the king, there is a library for everything. Python is still very good, the library park is huge, especially since it got supported from Google. In Smalltalk we are far from the level of C and Python. If you need a very specialized library, either you write it or you call external code.
* '''community size and colleagues'''. At some point you will get stuck. It is true, with open source you can read all the code and answer your own questions but it can take a lot of effort and if you are at a beginner-intermediate level this is just not possible. Therefore, an important factor to consider is: can you communicate with somebody who may answer your question, are there enough people using the technology. Not least, can you find programmers who know the language and work with you on a project? Here C and Python shine, in Smalltalk it is a bit of an issue but we do have our communities.
* '''development speed'''. Here C is really bad, writing programs takes time, debugging is hard. Python is a lot better - I would estimate you can be 5-10 times faster writing in Python. Smalltalk is the best, with its powerful tools and Platonic design not only is development fast, debugging is fast and not so tedious. I estimate you can be 2-3 times faster writing in Smalltalk versus Python.
* '''software maintainability'''. The moment comes when software must be changed to adapt to new circumstances. In C these are often hard times, in Python better, but still, it's imperative nature may require you to understand the conceptual workflow of the entire application. The change from Python2 to Python3 was an example of this problem - people are still getting paid to convert scripts to Python3. Here, Smalltalk shines. It is a system made for changes and evolutive software development. There is no difference from the concept of software creation and software change, you work in the same way and Smalltalk, by default, brings the entire development environment with itself, editor and debugger included. In Smalltalk you always work on the running program. There is no concept of switching it off, changing the code, and then running it again. See it this way, for a "Python is better than C" zealot you will hear this argument: "There aren't boring compile steps". A Smalltalk zealot laughs at that, he may tell you "There aren't boring shut down, correct, and restart the application steps", the application is always running.
* '''vendor support'''. Is there a company that sells an implementation of your language? This can be useful, if you get in real trouble you would know where to ask for help at any level. For C, sure, there are several compiler vendors. Python is a community-only language and as far as I know there isn't a corporate release of the language, there are though thousands of Python software houses so you can consider yourself kind of safe. In Smalltalk there are vendors with a private implementation of the system, for example [https://www.cincomsmalltalk.com/main/products/visualworks/ VisualWorks]. If you are in a corporate environment consider well the option of using their services. Also, their documentation might be far superior to open source projects. It is an option to keep in mind.
* '''self mutability'''. At times you may want to do something unusual. Maybe you would like to change the language a bit, for example a change in the standard library. Let's say I want to teach the String class to recognize Italian words, say i want a String to be able to answer the question 'isItalian'. In C there is not even the Class concept, in Python there are Classes but you just can't di it, the standard library is sealed you are not supposed to change it. In Smalltalk you can change whatever you want, you want to change the meaning of '=' between Floats? You can. Add a new operator '@=' to return true if two numbers are equal if their distance is less than 0.00000001? You can, and it is very easy, there isn't an arcane syntax, it is just standard procedure.
* '''the fun factor'''. After the birth of my first son I had to put a hard stop on Smalltalk coding. More urgent things popped into my hands and I had to restrict my coding to the minimum effort tool to get the job done. In my case it turned out to be a ''sh'' script or ''Python'' or ''Ruby''. Let's restrict to ''Python'', the most generic tool. I can be very productive in Python, I have all libraries for what I need and I can operate from the shell, I don't need a GUI, which for server people like me is a major source of problems. But programming in Smalltalk is really another life with respect to Python, even using Python as a Lisp, so REPL'ing all the time, testing all functions and objects and methods. There are 2 key points here: '''(1-observability)''' in Smalltalk, most of the time, you can see well the data structure going around your code since they are just objects. '''(2-correct-rerun-running-code)''' in Smalltalk when the program breaks it doesn't just tell you, "I found a problem in line 345" and spit at you the dead body of a stack trace. No, in Smalltalk the debugger opens and you are brought to the middle of the things while they are still happening. This is really, really the best experience. Lisp does kind of the same thing but inspecting live data structures in Lisp is a major source of pain.

There is a first factor which is very important which is '''execution''' '''speed'''. Some languages are faster than others for example C is faster than Python and Smalltalk, so if speed is of paramount interest, let's say you are writing a new matrix multiplication algorithm, it is better you just do it in C.

'''Pure v.s. Mixed languages'''. Python is an imperative programming language which borrows some Object Orientation principles, some functional style and tries to make everybody happy. Consider this <code>l = [1,2,3]</code> you made a list, you can't say <code>l.len()</code> as it should be if Python was reasonably object oriented, no, no, you must do <code>len(l)</code>. This is just arbitrary. There is not a global plan in the Python language, it grows to accommodate new fashions. Smalltalk is completely different. In Smalltalk there is a plan, a view of the world and it is inescapable, everything is an object and the only thing you can do is send an object a message. Therefore if I tell you that the format to send a message to an object is <code>OBJECT MESSAGE</code> then you already know that if <code>L</code> is some kind of list object and <code>size</code> is an available message for it, for sure, you can just do <code>L size</code>. Do you want to upcase a string? what if <code>S</code> is a string you just do <code>S upcase</code>.

'''A programming language v.s. an operating system'''. ...

'''Closed languages vs. Open languages'''. Suppose you want to teach a Python string how to do something. That is, for example, you read a CSV file or are receiving data from a web form, you are parsing fields and you have one for phone numbers. You may have prepared a proper PhoneNumber class to deal with this kind of data but when you read the CSV it will arrive to you as a String. So you would like to do something like this: <code>'+39425805040'.toPhoneNumber() </code> well, you can forget about it, you can't do it in Python, built in data structures are untouchable. In Smalltalk instead it is a very simple process, you add the <code>toPhoneNumber</code> to the String class and that's it, your program now knows how to transform String into PhoneNumbers.

'''Chained v.s. unchained languages'''. Suppose you are dealing with a very special problem and you need to redefine a builtin method.... no tail call regression ...

'''Live programming environment vs. Write-Run-Stop-Write-Run loop'''. This will seem like magic to you, it was for me. The way we are used to programming a computer is this: we write a program, run it, see what does not work, stop it (if it does not die by itself due to a bug) write in a correction, run again. Repeat the loop, this is your programmer day. If you are unlucky there is also the compile step, if you are really unlucky add the reboot step. Well, forget about this horrible situation, the Smalltalk programming environment is always active! Smalltalk never stops, when a strange condition happens a debugger pops up and asks you 99% of the time "This object does not know how to answer to the message you sent it, what do we do?" . It is nothing dramatic, you teach the object how to answer the message and the program goes on. It seems unreal, but it is just like that. Your programmer day is now building nice objects which are able to understand messages. It could be that you are a scientific programmer and you need to teach the object <code>Matrix</code> how to deal with a message <code>eigenvalues</code>, it could be you are into web programming and your <code>WebServer</code> object has received a message <code>getPriceItemWithCode:231231231</code> it does not matter what you need to teach your computer, the scheme is fixed, it is just objects and messages.

'''HackableSystems vs. LockedSystems'''. Suppose one day you want to change your control structures, for example, in your application, you would like to define a different kind of for loop, let's call it the <code>forgettyFor</code>, that on each loop if forgets to iterate over one element taken at random. That is not going to be easy in Python. In Smalltalk it is trivial, because the for loop is achieved with a message, if you want to define <code>forgettyFor</code> it is just matter of defining a new message.

'''Maintainability'''. The order spurs from the object system. ...

'''Live inspectable and changeable objects'''. This concept does not exist in python.

'''The magic of the event system'''.

'''Programming by simulation'''.

'''The image'''. In Smalltalk there is the concept of the image. This does not exist in Python. The image contains all your program and state, always. At some time you can tell Smalltalk to save the image to a file and then, another day, recover to that exact point. You can send the image to a remote colleague for him to see what you are seeing right now, no differences. This can be extremely helpful in at least a few circumstances, you found a bug, you would like to make a proper correction but for the moment the program needs to just run, so you save the image into a file, make a quick fix then send yourself the broken image to produce a better quality code patch. Consider another case, you are doing a simulation, there are several random variables, and the simulation took hours or days to complete. You see some incredible results, you need to think about it, show it to your colleagues, so you save the image into a file and when you will be ready you can inspect whatever you wish. Isn't that fantastic? A few other languages have images, like ''Common Lisp'' and ''R'', but in Smalltalk the image is even more interesting because with its integrated environment looking into variables (which for us are objects) is a pleasant activity compared to digging into data files, core dumps or JSON structures from the command line.

'''ease of code hiding'''. If you are not running an opensource project soon enough you will hit this problem: "If I leave my code open my software will be copied and I can't sell it to anybody". This is an unfortunate truth. So, if you need to hide your code, at this moment in time, Cuis-Smalltalk is not the tool for you. AFAIK the same goes for Pharo and Squeak. You may wish to try some commercial Smalltalk, for example Cincom.

The things you may call a List

2025-05-12T03:18:02Z

Ssmith2112: Fix typos

In many other programming languages such as Python, Ruby, Lisp-like etc. you will find a structure called '''list'''. This is a beautiful structure where you can put stuff in, also of different kinds, you can remove stuff, search the list. It grows by itself its size to fit your requests. It is really handy.

In Cuis, and in Smalltalk in general, we don't have a data structure named ''list''. The thing that is nearest to it is the class '''OrderedCollection'''.

There is one thing that may confuse you so let's get it straight from the beginning. Python, Ruby, Lisp-likes have a way to type in lists directly. In Smalltalk when we type in an object that looks like a list the system store it as an '''Array'''. But no worries, ''Array'' and ''OrderedCollection'' are both descendants of '''SequenceableCollection''' so many operations work on both data structures and you can easily convert one into another.

'''Exercise'''. Open the Browser and check what messages an object of class ''SequenceableColletion'' can understand.

'''Exercise'''. Open a Browser and confirm that ''SequenceableCollection'' is an ancestor of both ''Array'' and ''OrderedCollection''.

In the following, to keep the language compact I will talk about ''lists'', but you have been warned, there is no ''list'' in Smalltalk. Also, I will use the variable <code>v</code> to store intermediate results just because it looks better than <code>l</code>, which I often confuse with <code>1</code> (one).

'''CAVEAT'''. We are not going to cover here examples of all possible methods you can use on lists. Use the '''Terse Guide''' to see more possibilities and of course the Browser at the relevant Class.

=== Make a list 'by hand', equivalent of <code>v = [1,2,3]</code> in Python/Ruby and others. ===
v _ #(1 2 3). "=> #(1 2 3) "
v class. " Array "
or
v _ {1+2. 123. 7/2. 'hello'.}. " #(3 123 7/2 'hello') "
v class. " Array "
Observe that in this second case the list has been made with the results of the evaluation of a ''sequence of commands''.

=== Make a list, programmatically ===
v _ OrderedCollection new. "=> an OrderedCollection() "
v add: 1.
v add: 'foo bar'.
"let's go higher, put another list into the list"
v2 _ OrderedCollection new.
v2 add: 'tizio' . oc2 add: 'caio'. oc2 add: 'sempronio'.
v add: v2.
v "=> an OrderedCollection(1 'foo bar' an OrderedCollection('tizio' 'caio' 'sempronio')) "

=== The Smalltalk way to see a list ===
Comparing to Python and Ruby representation of the list you would say that we are really bad. Well, look now, leverage Smalltalk integrated graphical user interface.
v explore .

=== Check if a list contains an element ===
#(1 2 3) includes: 2. "=> true "

=== Return the first element of the list satisfying a property ===
#(1 2 3 4 5 6) detect: [:a | a > 3] ifNone: nil. "=> 4 "
#(1 2 3 4 5 6) detect: [:a | a > 10] ifNone: nil. "=> nil "

=== Return all elements of a list satisfying a property ===
#(1 2 3 4 5 6) select: [:a | a > 3] . "=> #(4 5 6) "
#(1 2 3 4 5 6) select: [:a | a > 10] . "=> #() "

=== Iterate over elements of a list for side effects ===
tmp _ 0 .
#(10 20 30) do: [ :x | tmp _ tmp + x ] .
tmp. "=> 60 "

=== map. Apply an operation to all elements of a list and build a new list with the results ===
#(1 2 3) collect: [:el | 2 * el ] . "=> #(2 4 6) "

=== remove. all elements from a list if they satisfy a property ===
se _ Set new.
se add: 1.
se add: 2.
se removeAllSuchThat: [:x | x == 2] .

=== TODO Return the list of all indexes of elements satisfying a property ===
----NM started on 15-Aug-2021. Examples done in Cuis5.0-4738.image

The Cuis Cookbook

2025-05-12T03:07:41Z

Ssmith2112: Fix typos

A programming language cookbook is something like ''StackOverflow'', without the digging part and the try&pray experience. For a gentle and structured introduction to Cuis-Smalltalk, you should start with the '''The Cuis Book''' and '''Learning-Cuis''' more about this on the [[CuisCoookBook-References|References]]. This is intended to be a resource for programmers, in the sense that it answers questions that will naturally come up to programmers while exploring Smalltalk.

'''Reliability'''. I am writing these notes while learning Cuis. Some of what I write may not be the best way to solve the problem, it may not even be correct. Be patient, double check! Since I use these recipes myself I am going to improve them in time.

'''Sorting principles'''. Topic order is intended to go from easy to difficult. From frequently necessary to rarely used. From needed at the beginning of the programming experience to needed by black belts. These three forces, as the 3 laws of robotics, regulate what chapter goes toward the top of the document. They hold also for sub-chapters and articles.

'''Contributions'''. I am trying to figure out ways to make contributions possible and fruitful, see [[contributions motivated guidelines]].

'''Copyright'''. You have the right to read, print for your own use and contribute to the document. You can make external links to this document. You can not copy the document and make it available somewhere else on the Internet. You can't claim ownership. You can't bring the document to an editor and publish it. I, as the author of more than 99% of the words here displayed retain all rights as well as the right to change these rules.

* [[Introduction]]. What you should expect from this book and the reason why I am writing it. STARTED.
* [[Why Smalltalk?]]. For what reason should you learn another programming language which is also not so popular. Read on, there are very good reasons. STARTED.

== Installation and start up ==

* Install and run Cuis in Windows
* Install and run Cuis in the Mac
* [[Install and run Cuis in Linux]]
* [[Run Cuis in the Web Browser. (SqueakJS)]]
* [[Run Cuis in a ARM platform, RPi, BeagleBone and similar. (Linux)]]
* Run Cuis in a remote server. (Linux)
* Run Cuis on the metal: without Operating System
* How to keep Cuis updated
* [[How to load the most recent changes Juan made to Cuis-Smalltalk-Dev]]

== Cuis in its environment ==

* What is a .image file?
* What is a .changes file?
* [[What is a .user.changes file?]]
* [[What is a .log file?]]
* [[What is release of the image and VM I am running?]]

== Things unique to Cuis and/or Smalltalk ==
Here are all the things that are totally unknown for anybody who never programmed in any Smalltalk.

* [[How can I make X? Learn to fish in Smalltalk|How can I make X ? Learn to fish in Smalltalk]]
* [[First things first: 1+1 and "Hello World"]]
* How can I type in a basic object ? [[Know the literals]] !
* [[You want something to get done? Ask an object to do it!]]
* [[How do I define a function?]]
* [[How do I create my own Class with some methods inside it?]]
* [[What is a package? How do I create, load and unload one?]]
* [[My project needs to add a method to somebody else Class, how do I do it?|My project needs to add a method to somebody else Class, how do I do it ?]]
* [[How to use Class variables]]. STARTED
* [[Learn how to use the Transcript]] . This is really important, better you take a peek.
* [[Tips & tricks]] . Those little keyboard/mouse shortcuts or little code snippets that may improve your programmer life.
* [[Traps and pitfalls for polyglot developers]] . If you know more programming languages this page is for you.
* [["It didn't understand" can't happen]]. The end of most of your programmer anxiety. You can understand it all.

== About a general Class and Object ==

* [[Create automatically all accessors for a Class instance variables]]
* [[Change the way an Object is printed]]
* [[Find all objects referencing anObject]]
* [[Make your own object initialization]]. All you need to know about <code>new</code>, <code>basicNew</code>, <code>initialize</code> etc. STARTED
* [[How to dump and restore an Object]] -- STARTED
* [[How to manage a Class who should have only one instance]]
* [[Discover in what package a Class lives]]
* [[Follow step bye how a method call gets resolved. Example-1]]

== Data Structures ==

* Fundamentals: numbers, strings and symbols

=== Strings (before default UTF) ===

* [[Cuis-What Strings are made of and how|What Strings are made of and how]]
* [[Cuis-String escape|String escape]]
* [[Cuis-Automatically escape a complex string|Automatically escape a complex string]]
* [[String formatting with format:]]
* [[String formatting with printf:]]
* [[A thousand ways to say new line]] . Newline, to text find it fast
* [[Trim white chars]]
* [[String joining]]
* [[String splitting]]
* [[String search]]
* [[String replace]]
* [[Show me the string, but max N. characters]]
* [[Dump and restore JSON data strings]]
* [[How to hash a string]]
* [[Convert to Base64]]
* [[Convert strings from/to Utf8]]
* Remove accents with, <code>'sarà' asUnaccented . => " 'sara' "</code>
* [[Convert UTF16 to Latin1]]. This is quite useful, in Windows-10 UTF16 is called Unicode.
* Jump to the next level of power, [[use Regex]] . Last in the list for complexity, but should be first for power, don't overlook this.

=== Collections ===

* [[The things you may call a List]] -- STARTED
* [[Array]]
* [[Dictionary a.k.a. Hash Table]]

== Streams ==

* [[Make a stream from a string, for reading]].
* [[Write a long String with a Stream]]
* [[Write to stdout in any system]]. Not only Unix like. Useful for shell programs.

== Date and time ==

* [[Get the current date and time]]
* [[Format date and time as you like most]]
* [[Date and time algebra]]
* [[Get the current time with the highest precision]]
* [[Get date and time as Unix epoch]]
* [[Get date and time in a different country]]
* [[Measure how much time it takes to run a code block]]

== Files and directories ==
You should keep in mind that Smalltalk uses files but it is not based on files. I copy here

part of a ''Juan'' mail to mailing list: "... The essential idea you need to be aware of when learning about all this is that Smalltalk uses files, but it is not file-based. What this means is that all the tools in the Smalltalk image (with the only exception of FileList and FileContentsBrowser) are NOT showing files, but '''live objects'''. The way them relate to files is usually not really important ...".

* [[How to Read or Write a text file]] . without Streams, only Strings.
* [[How to Read or Write a text file with a Stream]]
* [[Read a file line by line]] . Or any general delimiter.
* [[Find the current directory, list it and move in the directory tree]]
* [[Filename extensions]]: .txt, .csv, .json ...
* [[Check things on a pathname. Is there anything? Is it a file? Is it writable?]] ...
* [[Delete files and directories]]
* [[Read/Write a binary file]]
* [[Create a new non-existing file name]]
* [[Using file locks]] -- TODO
* [[Get the list of open files]]
* [[Get the directory where a Class (its Package) is stored]]
* [[Where is the image file? Where is the VM?]]

== Error Handling and the Debugger ==

* [[Call the debugger from a code location]]
* [[Quick exception handling]], equivalent of Python <code>try ... except</code>
* [[Assertions]]
* [[Errors, raise and catch signals]]
* Case-study-1. '''TODO'''. When the debugger pops up send me an email
* b

== Processes ==

* [[Smalltalk processes are not Unix processes]]
* [[See the list of running processes]]
* [[Processes 101]]. Shows how to create a process, name it, start it, stop it and destroy it.
* [[Run a new process]]
* [[Kill a process]]

== Uncategorized useful features ==

* [[Run a method every 2 hours or every day at 15:00]], equivalent to Unix cron
* [[Zip and unZip files and directories]] --- TODO, miss zipping
* [[Convert a file to/from Base64]]
* [[Deal with XML files]] -- STARTED
* [[About Random]]
* [[How to invoke the garbage collector]]
* [[Adapt newline characters to Cuis standard]]
* [[Where to get information about the hardware]] . Screen size, free memory, cpu speed ...
* [[The Dependency Mechanism - part 1]]. Here we talk about the Smalltalk classic '''Parent''' - '''Dependent''' model.
* [[The Dependency Mechanism - part 2]]. Here we explain the why of a '''Model''' class.
* [[The Dependency Mechanism - part 3]]. Here we talk about the '''Observer Pattern'''. (preferred current method in Cuis)
* How to use the '''serial port'''. See [https://github.com/nmingotti/Cuis-Smalltalk-SerialPort SerialPort] package, it has documentation.

== Run external programs ==
If you run Cuis in Linux/Unix, and to some extent also in the Mac, you can use thousands of already written shell

programs that solve the most diverse issues. Do you want to know how much free space is available on the disk?

How many wireless networks your computer can see? Run an R script to make a fantastic plot? These and thousands

of other things are possible once you are able to leverage the power of Unix from Cuis.

You can perform these kind of operations with the module <code>OSProcess</code> included in Cuis or with the external package <code>CommandShell</code>. The second is easier the first is more lower level.

* Traps and pitfalls specific to running external programs
* The ABCs of interacting with Unix . Find this process <code>pid</code>, <code>ARGV</code>, <code>ENV</code> , <code>stdin</code>, <code>stdout</code>, <code>stderr</code> ... and all those fundamental things.
* Run a program with OSProcess
* Run a program with CommandShell

== Networking and the Web ==

* How to ping a computer
* How to discover the IP of a given host name
* How to get a webpage's content

== Databases ==

* Talk to '''PostgreSQL'''. See the PostgreSQL package, it has documentation.
* Talk to MongoDB
* Talk to SQlite

== Scripting Cuis ==
This section is about setting Cuis to start up in the way you like it, on any image you may want to boot.

* Author name and initials programmatically
* Set your preferred font size
* Set your user name
* Stop the system from asking to save the image on pressing Cuis World->Quit
* An example of customized Cuis startup Requires only one executable script file !
* Do ENV variables affect Cuis ?
* How do I pass a string to be executed by Cuis when it boots ?
* How do I pass a file to be executed by Cuis when it boots ?
* How to quit Cuis immediately. No questions asked.

== Scripting with Cuis ==
Is it possible to make Unix scripts with Cuis? Does it make any sense? This section explores these subjects.

* Initial considerations. here

= Delivering an application written in Cuis =
This section explores ways in which you can have other people, non programmers, use your coolest applications. To run the application it may be necessary to: [1] Run VM and an Image [2] Run VM + Image + some code snippet passed as a String [3] Run VM + Image + a script file.

* Deploy a Cuis application in Linux
* Deploy a Cuis application in Windows-10
* Deploy a Cuis application in MacOS

= Morphic Cookbook =

* Basic operations with Morphs
* Kill a Morph . A few ways to destroy a Morph.
* Place Morphs in World as you wish, automatically
* Drawing and pictures with the ImageMorph
* Application. Convert a color image to black and white
* Application. Show contours in an image
* How to layout the Morphs . This is the basic step to know prodromic to make your own GUI in Cuis.
* Fonts - 1. First interactions with Fonts
* Basic event handling in Morphic . Here we see how to do something when a mouse button or a key on the keyboard get pressed.

= The Sound system =
To some people doing programming is manipulating sounds. As for some other people it is building a nice graphical user interface or some one else does networks services. For this reason the sound system chapter is placed after Morphic.
* [[First experiments with sound]] . Collecting knowledge here, when ready will be split into topics

= Introspection and The compiler =
These notes are taken reading the wonderful document "The HitchHiker's guide to the Smalltalk Compiler" by Vassili Bykov, here .

* get the current World object.
* what happens when Cuis start up.
* the main loop.
* The Cuis scanner.
* The Cuis parser.
* See the compiled code.

= The Virtual Machine =

* Building the Virtual Machine
* Building the VectorGraphics plugin
* Choosing between FFI and plugin
* Run a script with a proper window title

= Applications built on Cuis =

* DrGeo

== TODO ==
These are reminders for me about things to do in the Cookbook or in Cuis

* '''DEV'''. SpellChecker, for text panes in Cuis. It would be useful to be able to spellcheck comments in code. I like to put comments, without spell checker they are so full of bugs they appear really untrustworthy.
* Video about class variables.
* Page about ';' -- '::' -- 'yourself'.
* Video about installation of Cuis, not so easy the first time
* Video about updating Cuis, not obvious
* Video about using the Transcript efficiently
* Video about creation of a minimal GUI
* Video about creation of a minimal application, runnable from Linux command line
* Video about creation of a minimal application, runnable from Windows GUI
* Video about making Tests, and discovering how to use existing classes with them
* Video-or-page about variables, especially class variables