tosh help / guide

Also read tips on using the editor.

Scratch is a programming language designed for beginners.

Scratch's main appeal is that it's block-based: instead of typing in code, you drag blocks around. Since the block shapes are only allowed to fit together in certain ways, syntax errors are impossible. Overall, the block-based interface makes it beginner-friendly.

tosh is a text-based Scratch editor: you type in code in a text-based format which it compiles into Scratch projects, thus defeating the whole point of Scratch. (Why?!).

The Syntax

The syntax has only a few guiding principles:

That's it! And since you already know all the blocks in Scratch, the language should be easy to learn.

If you've used scratchblocks syntax before, be warned: tosh is quite different!

Read on for details…

Text Inputs

Write text input values inside single or double quotes. (I prefer double quotes, but you can use whichever you like.)

Some menu options must also be written in quotes: broadcasts, costumes, sounds, and sprite names. 

say "Hello world!"
broadcast "start the game"
switch costume to "red square"
play sound "pop"
point towards "Sprite1"

say [Hello world!]
broadcast [start the game v]
switch costume to [red square v]
play sound [pop v]
point towards [Sprite1 v]

Write all other menu options without quotes. These take only built-in values such as mouse-pointer which tosh can recognise. 

if key space pressed? and sqrt of 9 = 3 then
  stop other scripts in sprite
end

if <<key [space v] pressed?> and <([sqrt v] of (9)) = [3]>> then
  stop [other scripts in sprite v]
end

Order of operations

The order of operations tells you which things to perform first. For example, if you saw 2 + 3 * 4 while doing maths, you'd know to do the multiplication first. If you saw 2 + (3 * 4) it would mean the same thing; but the brackets aren't needed. You might have used a mnemonic like "BIDMAS" or "PEMDAS" to remember the order.

In computer languages, we use order of operations to work out where to put the brackets: tosh uses it to work out where to put blocks when converting your text into Scratch code.

You can think order of operations as how "tightly" blocks bind to their arguments. From the example above, we can say that * binds tighter than +.

Here's how the rest of the blocks fit in:

  1. Stack blocks like say … for … secs bind the loosest.
  2. Booleans like … and …
  3. Reporters with inputs like sin of …
  4. Arithmetic binds tighter than numeric reporters. First we have + and -…
  5. …and then we have *, /, and mod
  6. Finally, we have reporters with no inputs, like x position, which bind tightest.

Examples: 

move 2 + 3 * 4 steps

move ((2) + ((3) * (4))) steps

say 10 + sin of 90 + 15

say (((10) + ([sin v] of (90))) + (15))

(Look carefully—they might be surprising!)

The rules above mean you can usually omit brackets around reporter blocks. But just like in maths, you can use brackets if you need to.

Examples: 

say 2 + sin of (90 + 15)
say ((2) + ([sin v] of ((90) + (15))))
if <mouse down? and touching "cat"?> or score = 0 then
  
end

if <<<mouse down?> and <touching [cat? v]>> or <(score) = [0]>> then
  
end

Reporters

If you have a syntax error, try putting in a bracket just before.

Reporters in text inputs don't need brackets.

Reporters in number inputs only need brackets if you want to change the order of operations.

But to put a reporter into a menu input, you need to write brackets around it. 

say x position for timer secs
broadcast (join "message-" (score))
switch costume to (timer / 25)
play sound (item score of groceries)
point towards (join "sprite-" (score))

say (x position) for (timer) secs
broadcast (join [message-] (score))
switch costume to ((timer) / (25))
play sound (item (score) of [groceries v])
point towards (join [sprite-] (score))

The join block is special: reporters in its inputs always need brackets. 

say join "Hello " "world!"
say join "I'm at: " (x position)
say join join (x position) ", " (y position)

say (join [Hello ] [world!]
say (join [I'm at: ] (x position))
say (join (join (x position) [, ]) (y position))

List reporters always need brackets. (Variables don't.) 

say score for 1 secs
say (groceries)

say (score) for [1] secs
say (groceries :: list)

Control structures

Separate scripts with one or more blank lines.

The editor will automatically indent the blocks inside a c-block like repeat 10 using one extra tab at the start of each line.

Write end to indicate where a c-block ends.

As you'd expect, tosh is sensible and won't let you place any blocks after a cap block such as stop all. Similarly, you cannot put blocks directly above a hat block such as when or define hat.

Custom blocks

Define custom blocks using the define keyword: 

define jump (height) [message] grounded: <grounded?>
repeat height
  change y by 4
end

define jump (height) [message] grounded: <grounded?>
repeat (height)
  change y by (4)
end

Write input names in brackets. Use different brackets depending on which shape of input you want:

You use a custom block the same way as any built-in stack block. (Except that you have to write brackets around any reporters in the custom block's inputs.) 

jump 42 "Hello world!" grounded: <0 = 1>
jump (10 * score) (answer) grounded: <mouse down?>

jump (42) [Hello world!] grounded: <[0] = [1]> :: custom
jump ((10) * (score)) (answer) grounded: <mouse down?> :: custom

Get started

The above is all you need to know to start using tosh!

Reference

You might find these useful while coding:

The tips for using the editor may also be helpful.

Credits

Many thanks to the following:

Thanks to my beta testers:

Scratch is developed by the Lifelong Kindergarten group at the MIT Media Lab.

Shut up, Dan.

;