Cuis CookBook - User contributions [en]

MetaCookbook

2025-05-13T08:01:05Z

Nmingott: added stuff and corrections

=== Things ToDo ===

* add logo on the top left
* add certificate
* adjust things in such a way that visiting '''cuiscookbook.euriscom.it''' goes straight to the right page. It is important to have a name that always will link to the document.
* Daily backups exported in my backup systems.
* write somewhere a page about me
* Consider moving this server in my own hardware

=== Pages about this book ===

* contributors guidelines
* style guidelines

MetaCookbook

2025-05-13T07:59:01Z

Nmingott: added page and first content

=== Things ToDo ===

* add logo on the top left
* add certificate
* adjust things in such a way that visiting cuiscookbook.euriscom.it goes straight to the right page. It is importan to have a name that always will link to the document.
* Daily backups exported in my backup systems.
* write somewhere a page about me

=== Pages about this book ===

* contributors guidelines
* style guidelines

The Cuis Cookbook

2025-05-13T07:54:46Z

Nmingott: added link to new pages

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 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]]. As a write I see that also important are [[format 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.
* [[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 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. 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

The Cuis Cookbook

2025-05-13T07:43:23Z

Nmingott: added link

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 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]]. As a write I see that also important are [[format 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. 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

Why Smalltalk?

2025-05-13T07:41:00Z

Nmingott: rephrase

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 know already 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 to 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 it is possible to do, but what it will be easy to achieve according to you or your organization taste and preferences. For example, in C you can access directly memory locations, in Python and Smalltalk you can't easily do it, therefore if you are working very low level, e.g. you are writing a driver, C is just a more fit tool. On the other side, suppose your problem is to find the 10 largest files in your computer opened the last time more than 1 year ago. In C to do this it 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 can your code run? Here the fastest are C, Fortran, 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 '/'. This 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 an normal PC as well as in a RPi, in a BeagleBone Black, in a Web browser ? In C this is a problem, Python is quite portable, Smalltalk is the king it can run in very different platform, for example with [https://squeak.js.org/ SqueakJS] you can run you program written for a PC straight into the Web. You can't do easily this in any other programming language of 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, expecially since it got supported from Google. In Smalltalk we are far from their level. If you need a very specialized library either you write it or you call external code.
* '''community size and colleagues'''. At some moment you will get stuck. It is true, with open source you can read all the code and answer your own question but it can take a large effort and if you are at a beginner-intermediate level this is just not possible. Therefore, a factor to consider well is: can you communicate with somebody how may answer your question, is 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 a issue but we have our communities.
* '''development speed'''. Here C is really bad, writing programs takes time, debugging is hard. Python is really already a lot better I would estimate you can be 5-10 faster writing in Python. Smalltalk is the best, with its powerful tools and Platonic design not only development is fast, debugging is fast and not so tedious. I estimate you can be 2-3 times faster writing in Smalltalk respect to Python.
* '''software maintainability'''. The moment comes software must be changed to adapt to new circumstances. In C these are often hard time, in Python better but still, its imperative nature may require you to understand conceptual workflow of all the application. The change from Python2 to Python3 was an example of this problem, people is still getting payed to convert scripts to Python3. Smalltalk here shines, it is a system made for changes and evolutive software development. There is no difference from the concept of software creation of and software change, you work in the same way and Smalltalk, be default, brings all the 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, change the code and run 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 laugh 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 your self 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, 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 '@=' tell true if two numbers are equals if their distance is less than 0.00000001 ? You can, and it is very easy, there isn't a an arcane syntax, it is just standard procedure.
* '''the fun factor'''. After the birth of my first son I had to put an 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 it is a major source of problems. But programming in Smalltalk is really another life 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 in the middle of the things while they are still happening. This is really, really the best experience. Lisp does kind of the same 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 your 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 borrow some Object Orientation principles, some functional style and tryies 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 reasonable 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 accomodate new fashions. Smalltalk is completely different. In Smalltalk there is a plan, a view of the world and it is unescapeable, everything is an object and the only thing you can do is to send and 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 can know already that if <code>L</code> is some kind of list object and <code>size</code> is an available messsage for it, for sure, you just do <code>L size</code>. Do you want to upcase a string? what if <code>S</code> is a string you just to <code>S upcase</code>.

'''A prgramming lanuage v.s. an operating system'''. ...

'''Closed languages v.s. Open languages'''. Suppose you want to teach a Python string how to do something. That is for example you red a CSV file or receiveing 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 kid of data but when you read the CSV it will arrive 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 silly business 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 v.s. Write-Run-Stop-Write-Run loop'''. This will seem magic to you, it was for me. The way we are used to program computer is this. We write a program, run it, see what does not work, stop it (it does not dies by itself for 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 him, what do we do?" . It is nothing dramatic, you teach the object how to answer the message and the programs goes on. It seems unreal, but it is just like that. Your programmer day is now building nice objects which are able to undestand 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 object and messages.

'''HackableSystems v.s. 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, 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 into a file and than, another day, recover to that exact point. You can send the image to a far 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 with wish. Isn't it fantastic? A few other languages have images, like ''Common Lisp'' and ''R'', but in Smalltalk the thing 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.

Why Smalltalk?

2025-05-13T07:36:22Z

Nmingott: rewrite parts

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 know already 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 to 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 it is possible to do, but what it will be easy to achieve according to you or your organization taste and preferences. For example, in C you can access directly memory locations, in Python and Smalltalk you can't easily do it, therefore if you are working very low level, e.g. you are writing a driver, C is just a more fit tool. On the other side, suppose your problem is to find the 10 largest files in your computer opened the last time more than 1 year ago. In C to do this it 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 can your code run? Here the fastest are C, Fortran, 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 '/'. This 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 an normal PC as well as in a RPi, in a BeagleBone Black, in a Web browser ? In C this is a problem, Python is quite portable, Smalltalk is the king it can run in very different platform, for example with [https://squeak.js.org/ SqueakJS] you can run you program written for a PC straight into the Web. You can't do easily this in any other programming language of 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, expecially since it got supported from Google. In Smalltalk we are far from their level. If you need a very specialized library either you write it or you call external code.
* '''community size and colleagues'''. At some moment you will get stuck. It is true, with open source you can read all the code and answer your own question but it can take a large effort and if you are at a beginner-intermediate level this is just not possible. Therefore, a factor to consider well is: can you communicate with somebody how may answer your question, is 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 a issue but we have our communities.
* '''development speed'''. Here C is really bad, writing programs takes time, debugging is hard. Python is really already a lot better I would estimate you can be 5-10 faster writing in Python. Smalltalk is the best, with its powerful tools and Platonic design not only development is fast, debugging is fast and not so tedious. I estimate you can be 2-3 times faster writing in Smalltalk respect to Python.
* '''software maintainability'''. The moment comes software must be changed to adapt to new circumstances. In C these are often hard time, in Python better but still, its imperative nature may require you to understand conceptual workflow of all the application. The change from Python2 to Python3 was an example of this problem, people is still getting payed to convert scripts to Python3. Smalltalk here shines, it is a system made for changes and evolutive software development. There is no difference from the concept of software creation of and software change, you work in the same way and Smalltalk, be default, brings all the 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, change the code and run 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 laugh 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 your self 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, 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 '@=' tell true if two numbers are equals if their distance is less than 0.00000001 ? You can, and it is very easy, there isn't a an arcane syntax, it is just standard procedure.
* '''the fun factor'''. After the birth of my first son I had to put an 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'. Though, in retrospective, I see how productive I am since, 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 it is a major source of problems. But programming in Smalltalk is really another life 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 in the middle of the things while they are still happening. This is really, really the best experience. Lisp does kind of the same 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 your 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 borrow some Object Orientation principles, some functional style and tryies 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 reasonable 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 accomodate new fashions. Smalltalk is completely different. In Smalltalk there is a plan, a view of the world and it is unescapeable, everything is an object and the only thing you can do is to send and 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 can know already that if <code>L</code> is some kind of list object and <code>size</code> is an available messsage for it, for sure, you just do <code>L size</code>. Do you want to upcase a string? what if <code>S</code> is a string you just to <code>S upcase</code>.

'''A prgramming lanuage v.s. an operating system'''. ...

'''Closed languages v.s. Open languages'''. Suppose you want to teach a Python string how to do something. That is for example you red a CSV file or receiveing 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 kid of data but when you read the CSV it will arrive 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 silly business 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 v.s. Write-Run-Stop-Write-Run loop'''. This will seem magic to you, it was for me. The way we are used to program computer is this. We write a program, run it, see what does not work, stop it (it does not dies by itself for 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 him, what do we do?" . It is nothing dramatic, you teach the object how to answer the message and the programs goes on. It seems unreal, but it is just like that. Your programmer day is now building nice objects which are able to undestand 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 object and messages.

'''HackableSystems v.s. 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, 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 into a file and than, another day, recover to that exact point. You can send the image to a far 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 with wish. Isn't it fantastic? A few other languages have images, like ''Common Lisp'' and ''R'', but in Smalltalk the thing 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 Cuis Cookbook

2025-05-13T07:31:40Z

Nmingott: typo

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]]. As a write I see that also important are [[format 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. 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-05-13T07:25:39Z

Nmingott: add something to quit the edit stat (strange)

* Accumulating material
* '''variable assignment syntax'''. Use <code>':='</code> instead of <code>'-'</code>. Ratios. I like more <code>'_'</code>, 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 Smalltalk <code>':='</code> is more used, as far as I know.
* '''Syntax highlight 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 fund a way to hilight iniled code. To type in inlined code for the moment do: (1) select a code chunk (2) Click '''A''' -> Computer Code .
* '''Muse button name by left-right order'''. Always use the convention first, second, third button. The ordering is left to right. Mouser 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 button by color just adds to the complexity and perplexity of the new user.
* aaa

Format guidelines

2025-05-13T07:18:59Z

Nmingott: started new page

The Cuis Cookbook

2025-05-13T06:58:59Z

Nmingott: added link

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]]. As a write I see that also important are [[format 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. 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

Date and time algebra

2025-05-13T06:55:56Z

Nmingott: syntax hilight

'''Problem'''. You want to know what will be the weekday name of the day 1000 day in the future from now.

'''Solution'''. Cuis has a class '''Duration''' and is capable of doing dates algebra.<syntaxhighlight lang="smalltalk">
((DateAndTime now) + (Duration days: 1000)) dayOfWeekName . "=>" #Saturday
</syntaxhighlight>

'''Exercise'''. Explore the classes '''DateAndTime''', '''Duration''' and what is nearby in the Browser.

'''Exercise'''. Find the distance in hours between your birth date and your mother's.

How do I define a function?

2025-05-13T06:53:21Z

Nmingott: changed $_ with ':='

* Most probably, if you asked yourself ''how do I define a function ...'' it is because you are very new to ''Smalltalk''. You need to know straight now that defining a function as we will do now is very much infrequent in Smalltalk since out credo is: '''The world is made of objects and actions are carried out sending messages to object'''. Therefore, every time you think ''I should define a function'' you should instead be thinking ''I should define a proper method !''
* Here is how you define and use the simplest function in Smalltalk, we call them '''BlockClosure'''.
<syntaxhighlight lang="smalltalk">
f := [ :x | x * 2].
f class. "=>" BlockClosure
f value: 5. "=>" 10
</syntaxhighlight>
* Do you want to get more sophisticated ? Here is a 2 arguments function
<syntaxhighlight lang="smalltalk">
g := [ :x :y | x + y ].
g value: 3 value: 5. "=>" 8
</syntaxhighlight>

* Do you now want to do the right thing ? Then, learn how to define the message '''double''' inside the class '''Number'''.

How do I define a function?

2025-05-13T06:52:34Z

Nmingott: syntax hilight

* Most probably, if you asked yourself ''how do I define a function ...'' it is because you are very new to ''Smalltalk''. You need to know straight now that defining a function as we will do now is very much infrequent in Smalltalk since out credo is: '''The world is made of objects and actions are carried out sending messages to object'''. Therefore, every time you think ''I should define a function'' you should instead be thinking ''I should define a proper method !''
* Here is how you define and use the simplest function in Smalltalk, we call them '''BlockClosure'''.
<syntaxhighlight lang="smalltalk">
f := [ :x | x * 2].
f class. "=>" BlockClosure
f value: 5. "=>" 10
</syntaxhighlight>
* Do you want to get more sophisticated ? Here is a 2 arguments function
<syntaxhighlight lang="smalltalk">
g _ [ :x :y | x + y ].
g value: 3 value: 5. "=>" 8
</syntaxhighlight>

* Do you now want to do the right thing ? Then, learn how to define the message '''double''' inside the class '''Number'''.

Run Cuis in a ARM platform, RPi, BeagleBone and similar. (Linux)

2025-05-13T06:49:26Z

Nmingott: added link

* Running Cuis on ARM (BeagleBone, RPi etc.) isn't any different that on your pc, but there are a few details to know.
* '''ATTENTION'''. This information is valid on 19-Oct-2021. Things should change in better in the next months.
* The only two things you need to know are:

# You must use a 32 bit image, like this, for example:

<code>./sqcogspur32linuxhtRPi/squeak Cuis-Smalltalk-Dev/Cuis5.0-4834-32.image</code>

# You would rightfully try to use as VM '''squeak.cog.spur_linux32ARMv6_202003021730.tar.gz''', but this is broken unfortunately. I had success using the '''latest build''', [https://github.com/OpenSmalltalk/opensmalltalk-vm/releases/download/latest-build/squeak.cog.spur_linux32ARMv6.tar.gz here].

* Here is a runnability proof:
[[File:Runnability-prof.png|600x600px]]
----Dr. Nicola Mingotti wrote this on 19-Oct-2021.

The Cuis Cookbook

2025-05-13T06:47:29Z

Nmingott: small variation

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. 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

The Cuis Cookbook

2025-05-12T21:27:11Z

Nmingott: /* Applications built on Cuis */

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. 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

The Cuis Cookbook

2025-05-12T21:25:37Z

Nmingott:

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. 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

== 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

References to the Sound system

2025-05-12T21:24:09Z

Nmingott: Created page with "TODO. Add references i have from the Swiki TODO. Add Hannes references received via mail"

TODO. Add references i have from the Swiki

TODO. Add Hannes references received via mail

The Cuis Cookbook

2025-05-12T21:23:36Z

Nmingott: /* The Sound system */

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. 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.

* [[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

== 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

Create and play *.wav files

2025-05-12T21:20:53Z

Nmingott: split content in pages

TODO. Say something about *.wav files

===== Create a *.wav file =====
<syntaxhighlight lang="smalltalk" line="1">
(AbstractSound noteSequenceOn:
FMSound flute2 from:
#( (e5 0.5 500) (d5 0.5 300) (c5 0.5 350)
(d5 0.5 300) (e5 0.5 500) (e5 0.5 300)
(e5 1.0 350) (d5 0.5 400) (d5 0.5 300)
(d5 1.0 330) (e5 0.5 400) (g5 0.5 300)
(g5 1.0 500) )
) storeWAVOnFileNamed: 'maryhadalittlelamb.wav'.
</syntaxhighlight>

===== Play a *.wav file =====
<syntaxhighlight lang="smalltalk">
(SampledSound fromWaveFileNamed: 'maryhadalittlelamb.wav') play
</syntaxhighlight>

Create and play *.wav files

2025-05-12T21:17:19Z

Nmingott: imoprted

===== Create a *.wav file =====
(AbstractSound noteSequenceOn: FMSound flute2 from: #(
(e5 0.5 500) (d5 0.5 300) (c5 0.5 350)
(d5 0.5 300) (e5 0.5 500) (e5 0.5 300)
(e5 1.0 350) (d5 0.5 400) (d5 0.5 300)
(d5 1.0 330) (e5 0.5 400) (g5 0.5 300)
(g5 1.0 500)
)) storeWAVOnFileNamed: 'maryhadalittlelamb.wav'.

===== Play a *.wav file =====
(SampledSound fromWaveFileNamed: 'maryhadalittlelamb.wav') play

Play a melody writing a list of note names and their duration

2025-05-12T21:16:31Z

Nmingott: split subject into a page

TODO. Add piano keyboard view

TODO. Add procedure to play a melody with Italian note names: Do, Re, Mi

TODO. Add referece to the interesting history of different note naming scheme<syntaxhighlight lang="smalltalk">
(AbstractSound noteSequenceOn:
PluckedSound default from:
#((c4 1 500)
(d4 1 500)
(e4 1 500)
(g4 1 500)
(a4 1 250)
(a4 1 250)
(c5 1 500)
)
) play

</syntaxhighlight>

Play a melody writing a list of note names and their duration

2025-05-12T21:14:37Z

Nmingott: imported material

xxxx
(AbstractSound noteSequenceOn:
PluckedSound default from:
#((c4 1 500)
(d4 1 500)
(e4 1 500)
(g4 1 500)
(a4 1 250)
(a4 1 250)
(c5 1 500)
)
) play

The Cuis Cookbook

2025-05-12T21:13:47Z

Nmingott: /* The Sound system */

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. 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.

* [[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.

* [[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

== 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

First experiments with sound

2025-05-12T21:06:55Z

Nmingott: added sections

These notes were started from hhzl observations [https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/issues/82 here].

The sound system was exported from Squeak, more information can be found in the Swiki, see [[squeak:152|[1]]] and [[squeak:152|[2]]].

The sound system isn't loaded in the Cuis base system, but it is included in it, you just need to load it with:<syntaxhighlight lang="smalltalk">
Feature require: 'Sound'.

</syntaxhighlight>

===== Play a melody writing note names and duration =====
<syntaxhighlight lang="smalltalk">
(AbstractSound noteSequenceOn:
PluckedSound default from:
#((c4 1 500)
(d4 1 500)
(e4 1 500)
(g4 1 500)
(a4 1 250)
(a4 1 250)
(c5 1 500)
)
) play

</syntaxhighlight>

===== TODO. Play a melody with note names in Italian: Do, Re, Mi ... =====
xxxxx Should be easy.

xxxxx link to the interesting story of the two different note names

===== TODO. Realtime sound. on envent play a sound as soon as possible =====
This is necessary to simulate instruments playing on a computer keyboard or on some other external harware device. It is important that the delay is small otherwise the effect will be not realistic and not fun. At the moment i don't know how to do it.

===== Create a *.wav file =====
<syntaxhighlight lang="smalltalk">
(AbstractSound noteSequenceOn: FMSound flute2 from: #(
(e5 0.5 500) (d5 0.5 300) (c5 0.5 350)
(d5 0.5 300) (e5 0.5 500) (e5 0.5 300)
(e5 1.0 350) (d5 0.5 400) (d5 0.5 300)
(d5 1.0 330) (e5 0.5 400) (g5 0.5 300)
(g5 1.0 500)
)) storeWAVOnFileNamed: 'maryhadalittlelamb.wav'.

</syntaxhighlight>

===== Play a *.wav file =====
<syntaxhighlight lang="smalltalk">
(SampledSound fromWaveFileNamed: 'maryhadalittlelamb.wav') play
</syntaxhighlight>

'''Exercise.1'''. Check that the class '''Sound''' isn't present in Cuis by default.

===== References =====

* xxxx
* xxxx

First experiments with sound

2025-05-12T21:03:20Z

Nmingott:

These notes were started from hhzl observations [https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/issues/82 here].

The sound system was exported from Squeak, more information can be found in the Swiki, see [[squeak:152|[1]]] and [[squeak:152|[2]]].

The sound system isn't loaded in the Cuis base system, but it is included in it, you just need to load it with:<syntaxhighlight lang="smalltalk">
Feature require: 'Sound'.

</syntaxhighlight>

===== Play a melody writing note names and duration =====
<syntaxhighlight lang="smalltalk">
(AbstractSound noteSequenceOn:
PluckedSound default from:
#((c4 1 500)
(d4 1 500)
(e4 1 500)
(g4 1 500)
(a4 1 250)
(a4 1 250)
(c5 1 500)
)
) play

</syntaxhighlight>

===== TODO. Play a melody with note names in Italian: Do, Re, Mi ... =====
TODO. Link to the interesting story of this topic

TODO.

===== Create a *.wav file =====
<syntaxhighlight lang="smalltalk">
(AbstractSound noteSequenceOn: FMSound flute2 from: #(
(e5 0.5 500) (d5 0.5 300) (c5 0.5 350)
(d5 0.5 300) (e5 0.5 500) (e5 0.5 300)
(e5 1.0 350) (d5 0.5 400) (d5 0.5 300)
(d5 1.0 330) (e5 0.5 400) (g5 0.5 300)
(g5 1.0 500)
)) storeWAVOnFileNamed: 'maryhadalittlelamb.wav'.

</syntaxhighlight>

===== Play a *.wav file =====
<syntaxhighlight lang="smalltalk">
(SampledSound fromWaveFileNamed: 'maryhadalittlelamb.wav') play
</syntaxhighlight>

'''Exercise.1'''. Check that the class '''Sound''' isn't present in Cuis by default.

===== References =====

* xxxx
* xxxx

Why Smalltalk?

2025-05-12T20:57:44Z

Nmingott:

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 know already 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 to 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 actually don't choose what it is possible to do, but what it will be easy to achieve, the computer view of the World, what it will be easy to talk about. For example, in C you can access directly memory locations, in Python and Smalltalk you can't easily do it, therefore if you are working very low level, e.g. you are writing a driver, C is just a more fit tool. Then, suppose your problem is to take all files in your hard drive and find the 10 largest. Well, in C to do this it 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 can your code run? Here the fastest are C, Fortran, 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 '/'. This 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 an normal PC as well as in a RPi, in a BeagleBone Black, in a Web browser ? In C this is a problem, Python is quite portable, Smalltalk is the king it can run in very different platform, for example with [https://squeak.js.org/ SqueakJS] you can run you program written for a PC straight into the Web. You can't do easily this in any other programming language of 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, expecially since it got supported from Google. In Smalltalk we are far from their level. If you need a very specialized library either you write it or you call external code.
* '''community size and colleagues'''. At some moment you will get stuck. It is true, with open source you can read all the code and answer your own question but it can take a large effort and if you are at a beginner-intermediate level this is just not possible. Therefore, a factor to consider well is: can you communicate with somebody how may answer your question, is 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 a issue but we have our communities.
* '''development speed'''. Here C is really bad, writing programs takes time, debugging is hard. Python is really already a lot better I would estimate you can be 5-10 faster writing in Python. Smalltalk is the best, with its powerful tools and Platonic design not only development is fast, debugging is fast and not so tedious. I estimate you can be 2-3 times faster writing in Smalltalk respect to Python.
* '''software maintainability'''. The moment comes software must be changed to adapt to new circumstances. In C these are often hard time, in Python better but still, its imperative nature may require you to understand conceptual workflow of all the application. The change from Python2 to Python3 was an example of this problem, people is still getting payed to convert scripts to Python3. Smalltalk here shines, it is a system made for changes and evolutive software development. There is no difference from the concept of software creation of and software change, you work in the same way and Smalltalk, be default, brings all the 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, change the code and run 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 laugh 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 your self 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, 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 '@=' tell true if two numbers are equals if their distance is less than 0.00000001 ? You can, and it is very easy, there isn't a an arcane syntax, it is just standard procedure.
* '''the fun factor'''. After the birth of my first son I had to put an 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'. Though, in retrospective, I see how productive I am since, 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 it is a major source of problems. But programming in Smalltalk is really another life 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 in the middle of the things while they are still happening. This is really, really the best experience. Lisp does kind of the same 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 your 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 borrow some Object Orientation principles, some functional style and tryies 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 reasonable 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 accomodate new fashions. Smalltalk is completely different. In Smalltalk there is a plan, a view of the world and it is unescapeable, everything is an object and the only thing you can do is to send and 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 can know already that if <code>L</code> is some kind of list object and <code>size</code> is an available messsage for it, for sure, you just do <code>L size</code>. Do you want to upcase a string? what if <code>S</code> is a string you just to <code>S upcase</code>.

'''A prgramming lanuage v.s. an operating system'''. ...

'''Closed languages v.s. Open languages'''. Suppose you want to teach a Python string how to do something. That is for example you red a CSV file or receiveing 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 kid of data but when you read the CSV it will arrive 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 silly business 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 v.s. Write-Run-Stop-Write-Run loop'''. This will seem magic to you, it was for me. The way we are used to program computer is this. We write a program, run it, see what does not work, stop it (it does not dies by itself for 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 him, what do we do?" . It is nothing dramatic, you teach the object how to answer the message and the programs goes on. It seems unreal, but it is just like that. Your programmer day is now building nice objects which are able to undestand 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 object and messages.

'''HackableSystems v.s. 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, 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 into a file and than, another day, recover to that exact point. You can send the image to a far 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 with wish. Isn't it fantastic? A few other languages have images, like ''Common Lisp'' and ''R'', but in Smalltalk the thing 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.

Why Smalltalk?

2025-05-12T20:56:22Z

Nmingott:

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 know already 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 to 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 actually don't choose what it is possible to do, but what it will be easy to achieve, the computer view of the World, what it will be easy to talk about. For example, in C you can access directly memory locations, in Python and Smalltalk you can't easily do it, therefore if you are working very low level, e.g. you are writing a driver, C is just a more fit tool. Then, suppose your problem is to take all files in your hard drive and find the 10 largest. Well, in C to do this it 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 can your code run? Here the fastest are C, Fortran, 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 '/'. This 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 an normal PC as well as in a RPi, in a BeagleBone Black, in a Web browser ? In C this is a problem, Python is quite portable, Smalltalk is the king it can run in very different platform, for example with [https://squeak.js.org/ SqueakJS] you can run you program written for a PC straight into the Web. You can't do easily this in any other programming language of 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, expecially since it got supported from Google. In Smalltalk we are far from their level. If you need a very specialized library either you write it or you call external code.
* '''community size and colleagues'''. At some moment you will get stuck. It is true, with open source you can read all the code and answer your own question but it can take a large effort and if you are at a beginner-intermediate level this is just not possible. Therefore, a factor to consider well is: can you communicate with somebody how may answer your question, is 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 a issue but we have our communities.
* '''development speed'''. Here C is really bad, writing programs takes time, debugging is hard. Python is really already a lot better I would estimate you can be 5-10 faster writing in Python. Smalltalk is the best, with its powerful tools and Platonic design not only development is fast, debugging is fast and not so tedious. I estimate you can be 2-3 times faster writing in Smalltalk respect to Python.
* '''software maintainability'''. The moment comes software must be changed to adapt to new circumstances. In C these are often hard time, in Python better but still, its imperative nature may require you to understand conceptual workflow of all the application. The change from Python2 to Python3 was an example of this problem, people is still getting payed to convert scripts to Python3. Smalltalk here shines, it is a system made for changes and evolutive software development. There is no difference from the concept of software creation of and software change, you work in the same way and Smalltalk, be default, brings all the 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, change the code and run 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 laugh 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 your self 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, 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 '@=' tell true if two numbers are equals if their distance is less than 0.00000001 ? You can, and it is very easy, there isn't a an arcane syntax, it is just standard procedure.
* '''the fun factor'''. After the birth of my first son I had to put an 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'. Though, in retrospective, I see how productive I am since, 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 it is a major source of problems. But programming in Smalltalk is really another life 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 in the middle of the things while they are still happening. This is really, really the best experience. Lisp does kind of the same but inspecting 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 your 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 borrow some Object Orientation principles, some functional style and tryies 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 reasonable 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 accomodate new fashions. Smalltalk is completely different. In Smalltalk there is a plan, a view of the world and it is unescapeable, everything is an object and the only thing you can do is to send and 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 can know already that if <code>L</code> is some kind of list object and <code>size</code> is an available messsage for it, for sure, you just do <code>L size</code>. Do you want to upcase a string? what if <code>S</code> is a string you just to <code>S upcase</code>.

'''A prgramming lanuage v.s. an operating system'''. ...

'''Closed languages v.s. Open languages'''. Suppose you want to teach a Python string how to do something. That is for example you red a CSV file or receiveing 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 kid of data but when you read the CSV it will arrive 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 silly business 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 v.s. Write-Run-Stop-Write-Run loop'''. This will seem magic to you, it was for me. The way we are used to program computer is this. We write a program, run it, see what does not work, stop it (it does not dies by itself for 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 him, what do we do?" . It is nothing dramatic, you teach the object how to answer the message and the programs goes on. It seems unreal, but it is just like that. Your programmer day is now building nice objects which are able to undestand 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 object and messages.

'''HackableSystems v.s. 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, 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 into a file and than, another day, recover to that exact point. You can send the image to a far 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 with wish. Isn't it fantastic? A few other languages have images, like ''Common Lisp'' and ''R'', but in Smalltalk the thing 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.

Why Smalltalk?

2025-05-12T20:53:18Z

Nmingott: 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 know already 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 to 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 actually don't choose what it is possible to do, but what it will be easy to achieve, the computer view of the World, what it will be easy to talk about. For example, in C you can access directly memory locations, in Python and Smalltalk you can't easily do it, therefore if you are working very low level, e.g. you are writing a driver, C is just a more fit tool. Then, suppose your problem is to take all files in your hard drive and find the 10 largest. Well, in C to do this it 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 can your code run? Here the fastest are C, Fortran, 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 '/'. This 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 an normal PC as well as in a RPi, in a BeagleBone Black, in a Web browser ? In C this is a problem, Python is quite portable, Smalltalk is the king it can run in very different platform, for example with [https://squeak.js.org/ SqueakJS] you can run you program written for a PC straight into the Web. You can't do easily this in any other programming language of 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, expecially since it got supported from Google. In Smalltalk we are far from their level. If you need a very specialized library either you write it or you call external code.
* '''community size and colleagues'''. At some moment you will get stuck. It is true, with open source you can read all the code and answer your own question but it can take a large effort and if you are at a beginner-intermediate level this is just not possible. Therefore, a factor to consider well is: can you communicate with somebody how may answer your question, is 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 a issue but we have our communities.
* '''development speed'''. Here C is really bad, writing programs takes time, debugging is hard. Python is really already a lot better I would estimate you can be 5-10 faster writing in Python. Smalltalk is the best, with its powerful tools and Platonic design not only development is fast, debugging is fast and not so tedious. I estimate you can be 2-3 times faster writing in Smalltalk respect to Python.
* '''software maintainability'''. The moment comes software must be changed to adapt to new circumstances. In C these are often hard time, in Python better but still, its imperative nature may require you to understand conceptual workflow of all the application. The change from Python2 to Python3 was an example of this problem, people is still getting payed to convert scripts to Python3. Smalltalk here shines, it is a system made for changes and evolutive software development. There is no difference from the concept of software creation of and software change, you work in the same way and Smalltalk, be default, brings all the 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, change the code and run 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 laugh 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 your self 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, 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 '@=' tell true if two numbers are equals if their distance is less than 0.00000001 ? You can, and it is very easy, there isn't a an arcane syntax, it is just standard procedure.
* '''the fun factor'''. After the birth of my first son I had to put an 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'. Though, in retrospective, I see how productive I am since, 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 it is a major source of problems. But programming in Smalltalk is really another life respect to Python, even using Python as a Lisp, so REPL'ing all the time, testing all functions and objects and methogs. There are 2 key points here: (1) in Smalltalk, most of the time, you can see well the data structure going around your code since they are just objects. (2) 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 in the middle of the things while they are still happening. This is really, really the best experience. Lisp does kind of the same but inspecting 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 your 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 borrow some Object Orientation principles, some functional style and tryies 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 reasonable 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 accomodate new fashions. Smalltalk is completely different. In Smalltalk there is a plan, a view of the world and it is unescapeable, everything is an object and the only thing you can do is to send and 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 can know already that if <code>L</code> is some kind of list object and <code>size</code> is an available messsage for it, for sure, you just do <code>L size</code>. Do you want to upcase a string? what if <code>S</code> is a string you just to <code>S upcase</code>.

'''A prgramming lanuage v.s. an operating system'''. ...

'''Closed languages v.s. Open languages'''. Suppose you want to teach a Python string how to do something. That is for example you red a CSV file or receiveing 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 kid of data but when you read the CSV it will arrive 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 silly business 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 v.s. Write-Run-Stop-Write-Run loop'''. This will seem magic to you, it was for me. The way we are used to program computer is this. We write a program, run it, see what does not work, stop it (it does not dies by itself for 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 him, what do we do?" . It is nothing dramatic, you teach the object how to answer the message and the programs goes on. It seems unreal, but it is just like that. Your programmer day is now building nice objects which are able to undestand 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 object and messages.

'''HackableSystems v.s. 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, 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 into a file and than, another day, recover to that exact point. You can send the image to a far 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 with wish. Isn't it fantastic? A few other languages have images, like ''Common Lisp'' and ''R'', but in Smalltalk the thing 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 Dependency Mechanism - part 3

2025-05-12T20:42:52Z

Nmingott: imported material

* In Cuis the dependency is handled with the Observer pattern
* In the observer pattern an object called '''subject''' maintains a list of '''observers'''. The '''subject''' notifies its '''observers''' when it changes.
* In Cuis the Parent-Dependent pattern is implemented with the Subject-Observer this way

{| class="wikitable"
|
|'''Parent-Dependent'''
|'''Subject-Observer'''
|-
|connection making. '''objB''' wants to be informed of changes in '''objA'''.
|<code>objA addDependent: objB</code>
|<code>objA when: #changed send: #update to: objB</code>
|-
|'''objA''' tells the objects who are watching it that it changed state.
|<code>objA changed: #param</code>
|<code>objA triggerEvent: #changed with: #param</code>
|-
|when '''objA''' state changes the message <code>update</code> is sent to '''objB''' with a parameter.
|<code>objB update: #param</code>
|<code>objB update: #param</code>
|-
|we want '''objB''' to stop watching '''objA'''
|<code>objA removeDependent: objB</code>
|<code>objA removeActionWithReceiver: objB forEvent: #changed</code>
|}

* Observe that the parameter <code>#changed</code> is used explicitly in Cuis to build Parent-Dependent pattern, but that is actually a free parameter in the Observer model.
* In Cuis6 '''Model''' is substituted by '''ActiveModel''', if you look into the implementation of the Parent-Dependent pattern you will see that dependencies between objects go by default stored in class variable '''ActionMaps''' of '''ActiveModel''' . This instead of using class variable '''DependentsFields''' of class '''Object''', as done in the classic implementation, for example in VisualWorks and Squeak.
* '''Exercise'''. Use <code>ActiveModel actionMaps</code> to explore the '''ActionMaps''' class variable content.
* Mirroring our previous example in the Parent-Dependent model, we impolement of two simple classes (in the Subject-Observer model) '''MyActiveNumber''' and '''MyObserverNumber''' for objects '''objA''' and '''objB''', where '''objB''' is observer for '''objA'''. We want to keep the dependency mechanism localized so '''MyActiveNumber''' will be subclass of '''ActiveModel''' (instead of '''Object'''). When '''objA''' changes we want '''objB''' to receive the message <code>update</code>, we don't want to pass any parameter, '''objB''' will ask what it need to '''objA'''. You can get the fileout here: MyActiveNumber.st and MyObserverNumber.st .

ActiveModel subclass: #MyActiveNumber
instanceVariableNames: 'value'

MyActiveNumber >> initialize
value := 0.
^ self

MyActiveNumber >> value
^ value

MyActiveNumber >> value: aNumber
value := aNumber
self triggerEvent: #iChanged

Object subclass: #MyObserverNumber
instanceVariableNames: 'value model'

MyObserverNumber class >> newWithModel: anObject
^ super new initializeWithModel: anObject

MyObserverNumber >> initializeWithModel: anObject
value := 0.
model := anObject .
model when: #iChanged send: #update to: self .
^ self

MyObserverNumber update
|vPar vMe |
vPar := model value.
vMe := vPar * 2.
value := vMe.
Transcript show: ('my MODEL value is:{1} and mine is value:{2}' format: {vPar. vMe} ).

MyObserverNumber value
^ value

* Then try everything works with a little interaction from the Workspace

objA := MyActiveNumber new.
objB := MyObserverNumber newWithModel: objA.

objA value . "=> 0"
objB value. "=> 0"

objA value: 10.

objB value. "=> 20"

* '''Exercise'''. explore '''objA''' and convince your self it contains the map toward object '''objB'''.

The Dependency Mechanism - part 2

2025-05-12T20:42:13Z

Nmingott: imported material

* In '''Cuis-6''' there isn't anymore a '''Model''', there instead an '''ActiveModel''' class, but the name 'model' a very frequent in the code. You can still find '''Model''' in '''Squeak-5.3''' and '''VisualWorks-8.3''' if you wish to check out some implementation.
* We have seen (here) how to manage Dependency with the Parent / Dependent strategy. But where do all the relations involving objects are stored ?
* There relations are stored by default in the class variable '''DependentsFields''' of the class '''Object''' which is a specialized dictionary, where at every key corresponds an object who is Parent and its values are a list of Dependents objects.
* You can well understand that if there are a lot of dependencies the dictionary in DependentsFields becomes very large and also, there is another problem. If a dependent lost all references in the VM except for a forgotten relationship link in DependentsFields it will stay there and will not be garbage collected.
* To avoid these two problems, and for performance reasons, it was introduced the class '''Model''' which is a subclass of '''Object''' and a has an instance variable field called <code>dependents</code> where all the dependents are stored.
* In this way, if '''objA''' is a intended to be a Parent and you make it as a '''Model''' subclass instance, all its depency relationships will be localized into '''objA''' itself avoiding a large centralized permanent dictionary and also, once you delete '''objA''', you are sure all its dependents will be free to be garbage collected, when necessary.

The Dependency Mechanism - part 1

2025-05-12T20:41:42Z

Nmingott: imported material

* Smalltalk has a way to keep a relation between objects in the sense that, if '''objA''' changes then '''objB''' gets immediately informed about it.
* The classic way for an object to keep updated about another object state is '''polling''', that is '''objB''' checks every X milliseconds the state of '''objA'''. But this is very much resource consuming and, if possible, it should be avoided. Smalltalk has more sophisticated ways to solve this problem.
* The first thing you need to know is that there is a '''classic mechanism''' to do it but in '''Cuis''' it has been '''obsoleted'''. We will look at it in any case, because you can find it in books.

=== The Classic Mechanism of Parent and Dependent ===

* I red about this mechanism in the two books; the content there has to be adapted to run in Cuis but there is still some good interesting contents.
** "Smalltalk by Example" by Alec Sharp, see Chapter 19. pg.149.
** "Smalltalk an introduction to application development with VisualWorks" by Hopkins & Horan, see Chapter 27, pg.287.
* We will explain this mechanism with the simplest example possible
* There are two objects, '''objA''' and '''objB''' which actually contains only just a number in the instance variable <code>value</code>.
* We want that when '''objA''' changes its <code>value</code> to, say, 10, then '''objB''' value must become automatically 20, that is, it must double '''objA''' value.
* So let's define 2 classes and a few methods, very simple stuff:

Object subclass: MyParentNumber
instanceVariableNames: 'value'

MyParentNumber >> initialize
value := 0
^ self

Object subclass: MyDependentNumber
instanceVariableNames: 'value'

MyDependentNumber >> initialize
value := 0
^ self

MyDependentNumber >> update: aParameter
|outStr|
outStr := 'One of my parent changed and toldme "{1}" ! I may do something !' format: {aParam. }.
Transcript show: outStr .

* It is all classic except for the <code>update: aParameter</code>. That is the method that will be called automatically when '''objA''' will get updated.
* So let's now create '''objA''' , '''objB''' and make '''objB''' dependent on '''objA'''

objA _ MyParentNumber new.
objB _ MyDependentNumber new.

". this makes the connection, the dependency relation "
objA addDependent: objB.

* Now, open your Transcript and run this

objA changed: #foobar.

* You will notice that in the transcript there is written "One of my parent changed and told me "foobar" ! I may do something !"
* Aha ! It works. You sent a message <code>changed:#aParameter</code> to '''objA''' and the message <code>update:aParameter</code> was sent to '''objB'''.
* Now we have all the pieces to complete our objective, we just need to glue them together.
* Before that, let's '''break the connection''' between '''objA''' and '''objB''' and show that nothing happens anymore.

objA removeDependent: objB.
objA changed: #foobar.
objA changed: #foobar.
objA changed: #foobar.
" ... nothing intereseting appears into the Transcript now"

* So, here is the new version of the code, the code for the new classes MyParentNumber.st and MyDependentNumber.st is available for download and file-in.

Object subclass: MyParentNumber
instanceVariableNames: 'value'

MyParentNumber >> initialize
value := 0
^ self

MyParentNumber >> value
^ value

MyParentNumber >> value: aNumber
value := aNumber.
"when i change, i inform my dependents that i did, they will check what changed.
the value of the parameter #iChanged is insignificant. "
self changed: #iChanged.

Object subclass: MyDependentNumber
instanceVariableNames: 'value parent'

MyDependentNumber Class >> newWithParent: anObject
^ super new initializeWithParent: anObject

MyDependentNumber >> initializeWithParent: anObject
value := 0.
parent := anObject .
parent addDependent: self.
^ self

MyDependentNumber >> value
^ value

MyDependentNumber >> update: aParameter
|vPar vMe |
". i don't check the parameter, since I know that i am bound to only one Parent and i know
i can read its state when he tells me that he changed. "
vPar := parent value.
vMe := vPar * 2.
value := vMe.
Transcript show: ('my parent value is:{1} and mine is value:{2}' format: {vPar. vMe} ).

* Let's try it out

objA _ MyParentNumber new.
objB _ MyDependentNumber newWithParent: objA.

objA value. "=> 0"
objB value . "=> 0"

objA value: 10.
objB value. " => 20"

* We see it works and we are very happy with that.
* Now the sour part, this mechanism is '''deprecated''' in '''Cuis'''. The methods <code>addDependent:</code>, <code>changed</code>, <code>update:</code> ... are defined in '''Object'''. And if you look at their implementation you will see the mechanism with is used now, called '''Observer pattern''', which we will see in another page.

Where to get information about the hardware

2025-05-12T20:41:16Z

Nmingott: imported material

* You can find you '''screen dimensions''' with

DisplayScreen actualScreenSize. "=> 1920@1080"

* a
* b
* c

Adapt newline characters to Cuis standard

2025-05-12T20:40:49Z

Nmingott: imported material

'''TODO'''. Give a brief intro to the problem.

'''Problem'''. You are loading some code from another Smalltalk, in my case, Squeak, you try to load it into file list and you see funny ending chapters.

'''Solution-1'''. From the FileList: <code>click on the file, move to editor (bottom half), do cmd/alr-a (select all), cmd/alt-shift-u (convert to LF), cmd/alt-s (save)</code>.

How to invoke the garbage collector

2025-05-12T20:40:20Z

Nmingott: imported material

* Sometimes you just want to do it. Get rid of stuff that was disseminated into memory and lost contact with your project.

Smalltalk garbageCollect .

About Random

2025-05-12T20:39:51Z

Nmingott: imported material

Here I list several useful procedure related to randomness

=== Naive approach ===

* Being ''naive'' here means we are not making any questions about how the random number are generated, what distribution they have, and if the sequence will be repeatable at next ''Cuis'' boot.
* Get a random number between '''1''' and '''10'''.

<code>10 atRandom "=> 8 "</code>

* Get a random number chosen from the sequence of integer (10, 11, 12, ..., 19, 20).

(Interval from: 10 to: 20) atRandom . "=> 11 "

* Get a random float between '''[0,1['''

Random next. "=> 0.3395170491838441 "

* Choose a random element from a list

#(123 'a' 'hello' 51) atRandom . "=> 'hello' "

* Shuffle a list of elements

#(123 'a' 'hello' 51) shuffled . "=> #('hello' 'a' 51 123) "

=== Let's get a bit more sophisticated ===

Deal with XML files

2025-05-12T20:39:19Z

Nmingott: importe material

'''TODO'''. Complete the task and upload an example data file with (prices made up).

Many files today are encoded as XML. Some of them have a quite complex data structure and are hard to read for human eyes. But good news! In ''Cuis'' we have a package to deal with XML and ''Smalltalk'' makes exploring XML a lot more enjoyable than in any other programming language.

'''Problem'''. I have a company price list in several ''LibreOffice'' '''.odt''' files. I want to update all those prices adding 1.5%.

'''Solution'''. Say you have a file ''priceList1.odt'' then:

* Make a directory ''printList1Dir'' and copy ''princeList1.odt'' in there.

$> mkdir princeList1Dir
$> cp priceList1.odt priceList1Dir
$> cd priceListdir

* Unzip the file (yes, .odt file as just zipped document, isn't it great?)
* Remove the zipped file from the new directory (you will see why later on)

$> unzip princeList1.odt
$> rm princeList1.odt

* Observe there is a file called '''content.xml''', tadaaaa, we are going to work on that !

'''TO FINISH'''

* Just started to collect the necessary commands for reading
* I miss commands for writing
* I need to work with true files to make this of any use

Feature require: 'YAXO'.

f1 _ '/home/p/download/test1-odt/content.xml' asFileEntry readStream .
xdoc _ XMLDOMParser parseDocumentFrom: f1.
f1 close.
xdoc class. " XMLDocument "
xdoc elements. " show all elements "
xdoc explore.

t1 _ xdoc firstTagNamed: #'table:table'.
t1 class. " XMLElement "
t1 elements .

t1 firstTagNamed: #'text:p'.
" <text:p text:style-name="P2">1A</text:p> "

t1 tagsNamed: #'text:p' do: [ :el |
Transcript log: (' {1}' format: {el. }).
Transcript log: ('- contents {1}' format: {el contents. }).
].

Convert a file to/from Base64

2025-05-12T20:38:49Z

Nmingott: importing material

* One of the use of base64 file is to convert binary files into text files and, for example, send them via mail.
* This is an example of what you get if you watch inside a base64 file

<code>UEsDBAoAAAAAAEZcOFMAAAAAAAAAAAAAAAAIABwAdGVzdERpci9VVAkAA5ObTWHPn01hdXgLAAEE
6AMAAAToAwAAUEsDBAoAAAAAAERcOFMgMDo2BgAAAAYAAAARABwAdGVzdERpci90ZXN0MS50eHRV
VAkAA4+bTWGIm01hdXgLAAEE6AMAAAToAwAAaGVsbG8KUEsDBAoAAAAAAElcOFOQoBAeBwAAAAcA
AAARABwAdGVzdERpci90ZXN0Mi50eHRVVAkAA5qbTWGTm01hdXgLAAEE6AMAAAToAwAAaGVsbG8y
ClBLAQIeAwoAAAAAAEZcOFMAAAAAAAAAAAAAAAAIABgAAAAAAAAAEADtQQAAAAB0ZXN0RGlyL1VU</code>

=== Encode a file into new file Base64 ===

* The Linux/MacOSX way of doing such conversion is:

$> base64 foo.dat > foo.dat.b64

* In Cuis you do:

inFile _ '/home/p/foo.dat'.
file64 _ '/home/p/foo.dat.b64'.
rs1 _ inFile asFileEntry readStream useBytes.
rs2 _ file64 asFileEntry forceWriteStream .
Base64MimeConverter mimeEncode: rs1 to: rs2.
rs1 close. rs2 close.

=== Decode a Base64 file into a new file ===

* You can do this in Linux/MacOSX with

$> base64 -d foo.dat.b64 > foo.dat

* In Cuis you do:

file64 _ '/home/p/foo.dat.b64'.
outFile _ '/home/p/foo.dat'.
rs1 _ file64 asFileEntry readStream.
rs2 _ outFile asFileEntry forceWriteStream useBytes.
Base64MimeConverter mimeDecode: rs1 to: rs2.
rs1 close. rs2 close.

Run a program with CommandShell

2025-05-12T20:37:00Z

Nmingott: importing material

* '''SUPER GOTCHA'''. '''PipeableOSProcess''' is extremely handy, but also, extremely dangerous. Remember to '''close the pipes''' after using it, as shown in the examples below, or sooner or later your program will crash. Keep checked your open pipes with <code>$> sudo lsof | grep squeak | grep pipe</code>.
* '''SUPER GOTCHA'''. I have very bad surprises running PipeableOSProcess in a '''secondary process'''. If you kill the process and a PipeableOSProcess is running you may loose control of the image. If found OSProcess to be more resilient so I recommend you use that, even if it is more wordy to control.

Feature require: 'CommandShell'.
'''Problem'''. I want to know how much free space I still have in my disks. This is half done

if I know that in Linux I can get that info with <code>df -h</code>.

* '''Solution-1'''. This is the easiest solution.
** +] Quite short to type in
** +/-] It is '''synchronous''' with your code. This can be good and bad. When this commands end, the commands after it get executed. For the bad part read on.
** -] It your program to run takes a long time your Cuis is going to '''lock''' untill it has finished.
** NOTE. This example uses a new interface functions introduced in 2021.

p _ PipeableOSProcess waitForCommand: 'uname -a ' .
p exitCode . "=> 0 "
p outputAndError . "=> #('Linux deb4 5.10.0-9-amd64 #1 SMP Debian 5.10.70-1 (2021-09-30) x86_64 GNU/Linux
' <nowiki>''</nowiki>) "
p closePipes.
p close.

* '''Solution-2'''. As before but async
** +] This way does '''not lock''' you system
** -] You must check when execution ends yourself

p _ PipeableOSProcess command: 'df -h'.
out _ p output . " store the output somewhere, you can do it only once. "
p processProxy pid. "=> 112011 "
p processProxy exitCode. "=> 0 "
p closePipes.
p close.
out. "Ctrl+p, see the output"
"=>
'Filesystem Size Used Avail Use% Mounted on
udev 5.1G 0 5.1G 0% /dev
tmpfs 1.1G 18M 1.1G 2% /run
/dev/sda2 93G 80G 8.1G 91% /
tmpfs 5.2G 745M 4.4G 15% /dev/shm
tmpfs 5.0M 4.0K 5.0M 1% /run/lock
tmpfs 5.2G 0 5.2G 0% /sys/fs/cgroup
/dev/sda1 511M 3.3M 508M 1% /boot/efi
//nas.borghi.lan/sambaDisk/DiscoS/ 5.5T 3.8T 1.7T 70% /mnt/discoR
//backup.borghi.lan/backupDisk/ 22T 7.1T 15T 34% /mnt/discoBackup
tmpfs 1.1G 28K 1.1G 1% /run/user/1000
vmhgfs-fuse 1.9T 588G 1.3T 32% /mnt/macos
vmhgfs-fuse 1.9T 588G 1.3T 32% /mnt/dropbox
' "
'''Exercise-1'''. Get your Linux kernel version. Google around to discover the appropriate shell command.

'''Exercise-2'''. Inspect the content of variable <code>p</code>, you will see other interesting stuff there.
----NM 06-Sep-2021. Cuis version...

Run a program with OSProcess

2025-05-12T20:36:23Z

Nmingott: importing material

All the sinppets in this page require you to run
Feature require: 'OSProcess'.

=== Simple. Run a command and wait, only for the output ===

* sync
* Main issue. '''no exit code'''.

'''Example'''. ---- NO - move it out from here, requires CommandShell
out _ OSProcess outputOf: 'pwd'.
out class. "=> String "
out withBlanksTrimmed. "=> '/home/p/prog/cuis-project' "

=== Simple. Run a command and wait, only to get the exit code ===

* sync
* Main issue. '''not frequently useful'''.

'''Example'''
out _ OSProcess waitForCommand: ' sh -c "exit 33" '.
out class. "=> ExternalUnixOSProcess "
out exitCode . "=> 33 . NOTE. exitCode was added on 16-oct-2021."

=== Run a command to get the output, no input, sync ===
'''Example'''. Get the current date using Linux <code>date</code> command.
d _ Delay forMilliseconds: 50.
in _ nil.
out _ '/tmp/test.out' asFileEntry forceWriteStream .
err _ '/tmp/test.err' asFileEntry forceWriteStream .
proc _ UnixProcess forkJob: '/usr/bin/date'
arguments: nil environment: nil
descriptors: {in. out. err.}.
[proc runState == #complete] whileFalse: [d wait].
proc pid.
oExit _ proc exitCode .
oOut _ out contents.
oErr _ err contents.
{in. out. err} do: [ :f | f ifNotNil: [ f close ] ].
'exitCode: {1}, output: {2}' format: {oExit. oOut withBlanksTrimmed .}

"=> 'exitCode: 0, output: Tue 14 Sep 16:23:10 CEST 2021' "

=== Run a command through the shell to get the output, no input, sync ===
'''Example'''. Get the first 3 lines of output of <code>ls</code> in the current directory. That is run in <code>bash</code> the

command <code>ls -l | head -n 3</code>.
d _ Delay forMilliseconds: 50.
in _ nil.
out _ '/tmp/test.out' asFileEntry forceWriteStream .
err _ '/tmp/test.err' asFileEntry forceWriteStream .
proc _ UnixProcess forkJob: '/usr/bin/bash'
arguments: {'-c'. 'ls -l | head -n 3'}
environment: nil
descriptors: {in. out. err.}.
[proc runState == #complete] whileFalse: [d wait].
proc pid.
oExit _ proc exitCode .
oOut _ out contents.
oErr _ err contents.
{in. out. err} do: [ :f | f ifNotNil: [ f close ] ].
'exitCode: %d\noutput: %s' printf: {oExit. oOut withBlanksTrimmed } .
"=> 'exitCode: 0
output: total 3808
drwxrwx--- 3 p p 4096 Aug 18 12:54 AMQP
drwxrwx--- 3 p p 4096 Aug 18 12:54 Cairo' "

=== As before, but pass input through <code>stdin</code> ===
'''Example'''. We are going to count the number of charaters of what is sent through <code>stdin</code> via <code>wc -c</code>.
d _ Delay forMilliseconds: 50.
'/tmp/test.in' asFileEntry fileContents: 'Hello World!'.
in _ '/tmp/test.in' asFileEntry readStream .
out _ '/tmp/test.out' asFileEntry forceWriteStream .
err _ '/tmp/test.err' asFileEntry forceWriteStream .
proc _ UnixProcess forkJob: '/usr/bin/bash'
arguments: {'-c'. 'wc -c'}
environment: nil
descriptors: {in. out. err.}.
[proc runState == #complete] whileFalse: [d wait].
proc pid.
oExit _ proc exitCode .
oOut _ out contents.
oErr _ err contents.
{in. out. err} do: [ :f | f ifNotNil: [ f close ] ].
'exitCode: %d\noutput: %s' printf: {oExit. oOut withBlanksTrimmed } .

"=> 'exitCode: 0
output: 12' "

The basics of interacting with Unix

2025-05-12T20:35:35Z

Nmingott: import + hilight

* You absolutely need the package <code>OSProcess</code>
* To get a reference to the process which is running your Cuis image do:
<syntaxhighlight lang="smalltalk">
UnixProcess thisOSProcess . "=> a UnixProcess with pid 14751 "
</syntaxhighlight>

* Then watch these interactions it should be all clear to you
<syntaxhighlight lang="smalltalk">
". get the current working directory of the shell when it run Cuis "
UnixProcess thisOSProcess getCwd. "=> '/home/p/prog/cuis-project' "

". get the pid of the Cuis process and his father pid "
UnixProcess thisOSProcess pid. "=> 14751 "
UnixProcess thisOSProcess ppid. "=> 14750 "

" ------------
from here on there are class method shortcuts that let you type less but the idea is alwys the same you are asking 'UnixProcess thisOSProcess' to give you info.
------------ "

". get the environment variables of the shell who run Cuis "
UnixProcess env. "=> a Dictionary(#CLUTTER_IM_MODULE->'ibus' #COLORFGBG->'0;15' #COLORTERM->'truecolor' #DBUS_SESSION_BUS_ADDRESS->'unix:path=/run/user/1000/bus' .... #DESKTOP_SESSION->'plasma' #DISPLAY->':0.0' ) "

". the program name corresponding to Cuis, which is the name of the OpenSmalltalkVM"
UnixProcess programName . "=> './sqcogspur64linuxht/lib/squeak/5.0-202003021730/squeak' "

" . the VM arguments, where there is Cuis image file and some extra parameters "
UnixProcess arguments . "=> #('Cuis-Smalltalk-Dev/Cuis5.0-4975.image' '-d' 'Preferences veryBigFonts.') "

". get stdin, stdout, stderr "
". observe that by default, as of now, stdout and stderr are both copied to Transcript but only stderr will go printed into the shell which runs Cuis. "
UnixProcess stdOut nextPutAll: 'Hello world ! '.
UnixProcess stdErr nextPutAll: 'Hello world ! '.

</syntaxhighlight>

The basics of interacting with Unix

2025-05-12T20:30:12Z

Nmingott: imported material

* You absolutely need the package <code>OSProcess</code>
* To get a reference to the process which is running your Cuis image do:

UnixProcess thisOSProcess . "=> a UnixProcess with pid 14751 "

* Then watch these interactions it should be all clear to you

". get the current working directory of the shell when it run Cuis "
UnixProcess thisOSProcess getCwd. "=> '/home/p/prog/cuis-project' "

". get the pid of the Cuis process and his father pid "
UnixProcess thisOSProcess pid. "=> 14751 "
UnixProcess thisOSProcess ppid. "=> 14750 "

" ------------
from here on there are class method shortcuts that let you type less
but the idea is alwys the same you are asking 'UnixProcess thisOSProcess' to
give you info.
------------ "

". get the environment variables of the shell who run Cuis "
UnixProcess env. " => a Dictionary(#CLUTTER_IM_MODULE->'ibus' #COLORFGBG->'0;15'
#COLORTERM->'truecolor' #DBUS_SESSION_BUS_ADDRESS->'unix:path=/run/user/1000/bus' ....
#DESKTOP_SESSION->'plasma' #DISPLAY->':0.0' ) "

". the program name corresponding to Cuis, which is the name of the OpenSmalltalkVM"
UnixProcess programName .
"=> './sqcogspur64linuxht/lib/squeak/5.0-202003021730/squeak' "

" . the VM arguments, where there is Cuis image file and some extra parameters "
UnixProcess arguments .
"=> #('Cuis-Smalltalk-Dev/Cuis5.0-4975.image' '-d' 'Preferences veryBigFonts.') "

". get stdin, stdout, stderr "
". observe that by default, as of now, stdout and stdrr are both copied to Transcript
but only stderr will go printed into the shell which runs Cuis. "
UnixProcess stdOut nextPutAll: 'Hello world ! '.
UnixProcess stdErr nextPutAll: 'Hello world ! '.

Traps and pitfalls specific to running external programs

2025-05-12T20:29:25Z

Nmingott: Created page with "* I run most of my external commands in '''Linux''', sometimes in '''BSD'''. These procedures may work in the Mac, since it is, in some way, a descendant of BSD, but they will not work in Windows. * In different Unix-like systems the same command can be in different positions in the filesystem. For example in Linux Debian <code>date</code> is in <code>/usr/bin/date</code>. In the Mac it is in <code>/bin/date/</code>. * If you run your external command '''synchronously'''..."

* I run most of my external commands in '''Linux''', sometimes in '''BSD'''. These procedures may work in the Mac, since it is, in some way, a descendant of BSD, but they will not work in Windows.
* In different Unix-like systems the same command can be in different positions in the filesystem. For example in Linux Debian <code>date</code> is in <code>/usr/bin/date</code>. In the Mac it is in <code>/bin/date/</code>.
* If you run your external command '''synchronously''' your code will be easier to read but '''Cuis UI will''' '''hang''' until the command is done. This might be very unpleasant so if you want to go that way make sure your external command can complete its task quickly, independently of the input.
* If you run commands through the <code>bash</code> or <code>sh</code> and pass pathnames to it, they should be quoted or even a white space can bring you unexpected results.
* In Smalltalk we write strings with <code>'...'</code> and in the ''Bash'' shell the same character is used for quoting without interpolation, you will soon discover escaping your command can be not trivial. This fact is worsened by the escape character in Smalltalk being again <code>$'</code>.
* Given the previous points I recommend you never to run <code>rm</code> or any destructive command. Mistakes and the unexpected do happen.
* If part of your shell command is taken from user input (e.g. a '''web page form''') keep in mind that '''bad guys exist''' and they try to inject executable code in the forms. Imagine this scenario, you asked the user to give you a mail address and you would like to give that string to the <code>mail</code> command. But the user instead wrote <code>$(cd ; rm -rf *)</code>, say farewell to your home directory.

The Cuis Cookbook

2025-05-12T20:25:21Z

Nmingott: /* Run external programs */

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. 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.

* [[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.
* [[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

The Cuis Cookbook

2025-05-12T20:22:43Z

Nmingott: /* Run external programs */

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. 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.

* 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

Convert UTF16 to Latin1

2025-05-12T20:16:17Z

Nmingott: syntax hilight

'''Problem'''. We got a data file in XML, but it is encoded in UTF16. Cuis is based on Latin1 characters, so, if possible we should convert to this character set before doing any operation.

'''Solution'''. Provided by Juan on the mailing list on date 11-Jun-2022.<syntaxhighlight lang="smalltalk">
utf16 := 'expo-test-IT-UTF16.xml' asFileEntry binaryContents.
possibleBOM := utf16 copyFrom: 1 to: 2.
isLittleEndian := true. "use your best guess"
possibleBOM = #[255 254] ifTrue: [
isLittleEndian := true.
utf16 := utf16 copyFrom: 3 to: utf16 size ].
possibleBOM = #[254 255] ifTrue: [
isLittleEndian := false.
utf16 := utf16 copyFrom: 3 to: utf16 size ].
String streamContents: [ :out |
index := 1.
[index < utf16 size] whileTrue: [
codePoint := utf16 unsignedShortAt: index bigEndian: isLittleEndian not.
out nextPut: (Character codePoint: codePoint).
index _ index + 2 ]].
</syntaxhighlight>

Convert to Base64

2025-05-12T20:10:50Z

Nmingott: syntax hilight

=== Problem ===
Encode a String to Base64.

=== Solution ===
Convert to ByteArray and then encode using #base64Encoded:<syntaxhighlight lang="smalltalk">
'Hello World' asByteArray base64Encoded. "=>" 'SGVsbG8gV29ybGQ='
</syntaxhighlight>

How to hash a string

2025-05-12T20:09:35Z

Nmingott: syntax hilight

== Example 1. ==
Sometimes it is useful to make a number that represents string. This is usually called an ''hash'', one of its properties is that if you change the string a tiny bit the hash number becomes quite different.<syntaxhighlight lang="smalltalk">
'Hello world' hash. "=> 136137888 "
</syntaxhighlight>

== Example 2. MD5 ==
<syntaxhighlight lang="smalltalk">
WebUtils md5Digest: 'foobar'. "=>" '3858F62230AC3C915F300C664312C63F'
</syntaxhighlight>'''Exercise'''. Try to hash 'Hello World' and see how much different it is.

'''Exercise'''. Explore the ''Cryptography-DigitalSignatures'' package for another implementation of the hashing function.

Dump and restore JSON data strings

2025-05-12T20:08:10Z

Nmingott: syntax hilight

Since Javascript is the only language running inside Web browsers it has become extremely popular to dump and exchange data in JSON format. How do I read a JSON dump made from others? How do I make my own?

First of all, to work with JSON you must load this package.<syntaxhighlight lang="smalltalk">
Feature require: 'JSON'.
</syntaxhighlight>

'''Problem'''. I want to convert a Cuis data structure in JSON, how do i do it?

'''Solution'''. By example.<syntaxhighlight lang="smalltalk">
js1 := Json render: {
Dictionary newFromPairs: {'codice'. '111.653.735'. 'quantita'. '1'}.
Dictionary newFromPairs: {'codice'. '111.653.735'. 'quantita'. '2'}
}.

js1 print. "=>"
'[{"quantita": "1", "codice": "111.653.735"},
{"quantita": "2", "codice": "111.653.735"}]'
</syntaxhighlight>

'''Problem'''. I want to read some JSON string and use it as a data structure in Cuis, how do I do ?

'''Solution'''. By example. Using the output of previous problem.<syntaxhighlight lang="smalltalk">
jo1 := Json readFrom: (ReadStream on: js1).

jo1 class. "=> Array "

(jo1 at: 1) class. "=> JsonObject "

jo1 at: 1. "=> a JsonObject('quantita'->'1' 'codice'->'111.653.735' ) "

(jo1 at: 1) at: 'codice'. "=> '111.653.735' "
</syntaxhighlight>

----Dr. Nicola Mingotti. Last updated 03-Sep-2021. Tested in Cuis-5.0-4815.image .

Show me the string, but max N. characters

2025-05-12T20:01:59Z

Nmingott: syntax hilight

In another programming language this may not be such an interesting function but in Smalltalk it is. Why? Because we have inspectors and we are used to see our data interactively. Now image the case you have an ordered collection of Strings, those strings might be email messages bodies or even book texts so, large stuff. If you open the Explorer it tries by default to show you all the string length, which in many cases it is not what you want and might slow you down.

'''Problem'''. We are dealing with long strings. When we print them we don't want by defaut to see the whole story, just the beginning and the end snippets are fine. How to do it ?

'''Solution'''. There is a builtin <code>String>>contractTo:</code> that perform this simple operation for us, we don't need to re-define it ourselves.<syntaxhighlight lang="smalltalk">
"A foobar long string. "
s := 'sdf asdf asdfqwer qwe asd asdf asdf asdf asdf asdf asdf 123 123 1 '.

"let's have an idea of what is inside it ..."
s contractTo: 20. "=> 'sdf asdf ...3 123 1 '"
</syntaxhighlight>

----Dr. Nicola Mingotti last updated on 06-Sep-2021. Tested in Cuis5.0-4834.image.