Getting started

Getting started

This page will explain how to install Charm and how to get the most out of using it.

Installing and running Charm

To install Charm, first install Go, and then in your terminal go into the main Charm folder and go build. You now have a working copy of Charm which can be run with .\charm.

If you do so, you will see something like this in your terminal:

  ╔═══════════♥═══════════╗
  ║  Charm version 0.4.0  ║
  ╚═══════════♥═══════════╝

→ 

This is a REPL. Even though no service is running, it will still evaluate expressions in Charm.

→ 2 + 2
4
→ len "petunia"
7
→

How best to use Charm

We have supplied Charm with a VSCode extension which highlights Charm code and takes care of indentation for you. You can add this to VSCode by copying the charm-highlighter folder of the distribution to your <user home>/.vscode/extensions folder. If VSCode is already running, it may be necessary to restart it.

We intend to add support for other editors, but until then, the best way to code in Charm is to edit your scripts in VSCode while running Charm in a terminal in the bottom panel.

If you are using VSCode for the first time, note that it ships with autosave turned off. We recommend that you turn it on.

A first script

Let's look at an example script. You can find this in the examples folder of Charm as first.ch. It has a command greet, for greeting people, and a function factorial, for finding factorials. If you can read any code in any language, you will find that you can also read this.

cmd

greet :
	get name from Input("What's your name? ")
	post "Hello " + name + "!" to Output()

def

factorial (n) :
	n == 0 :
		1
	n > 0 :
		n * factorial n - 1
	else :
		error "can't take the factorial of a negative number"

We can tell Charm to run it in the REPL:

→ hub run "examples/first.ch"
Starting script 'examples/first.ch' as service '#0'.
#0 →  

Because this particular script doesn't have a main command, it doesn't actually do anything on initialization. Instead it supplies us with a service (automatically named #0 since we didn't name it ourselves) which knows the definitions of greet and factorial:

#0 → greet
What's your name? Marmaduke
Hello Marmaduke!
#0 → factorial 6 
720
#0 → 

Introducing the hub

To run our first example script, we told the REPL hub run "examples/first.ch". That is we ran the script by telling "the hub" to run the script for us.

But what is the hub? It's your new best friend. It allows you to start services and stop them. It helps you write and run tests, it explains error messages for you and traces runtime errors, it lets you turn hotcoding on and off, it supplies you with documentation, and if you like it will also turn into a server and perform role-based access management for you. In short it lets you create, manage, and deploy your scripts and services. It is called "the hub" because it can run several services at once and allow them to interact with one another.

The hub is itself a Charm service, but equipped with a few superpowers that makes it the boss of all the other services. However it has the same syntax and semantics as a Charm service, because it is one.

Since the hub has so many uses, it has a section to itself in this wiki. However, to get you started here are some useful instructions:

run

As we've seen, hub run "<filename>" will initialize a service from the given script. The hub will supply a name for the service from the series #0, #1, #2 ...

If you want to name the service yourself, do hub run "<filename>" as "<service name>". E.g:

#0 → hub run "examples/first.ch" as "First"                                                                                                            
Starting script 'examples/first.ch' as service 'First'.
First → greet                                                                                                                                          
What's your name? Theophania                                                                                                                           
Hello Theophania!                                                                                                                                      First → 

hub services

Starting up one service doesn't stop the other services from running. hub services provides you with a list of all the ones that are.

First → hub services 

The hub is running the following services:

  ▪ Service '#0' running script 'first.ch'.
  ▪ Service 'First' running script 'first.ch'.

First → 

hub switch

hub switch "<service name>" changes the "current service" (the one you're talking to) to the service named. As you'll have noticed, the name of the current service shows up in the prompt.

First → hub switch "#0"
ok
#0 →      

hub halt

hub halt "<service name>" halts the named service.

#0 → hub halt "First"
ok
→

hub quit

This shuts down Charm, but remembers every service you had running at shutdown which you gave a specific name to (by using hub run ... as) and starts them up again when you restart Charm.

Hotcoding

By default, Charm has hotcoding turned on. That is, when you talk to a Charm service, if its source code has been changed since last you interacted with it, the service will automatically be re-initialized with the new code.

So if you also have autosave turned on in your editor, changes in your code will propagate through to the service without you needing to do anything. Try it out! If you're still running the service from the previous section, change Hello to Goodbye in the script, and then in the REPL we get:

#0 → greet
What's your name? Horace                                                                                                                            
Goodbye Horace!
#0 → 

Hotcoding can be turned on and off with hub hot on and hub hot off.