Basic Usage

Let’s walk through a basic session where you’ll add and edit some Python. Ultimately, we’ll produce the following code:

def factorial(n):
    if n == 0:
        return 1
    else:
        return n * factorial(n - 1)

Type

The type command is the simplest way to dictate text, so let’s start there. type will simply insert what you say at the current cursor position. Try saying:

type def factorial

Remember, if you see a list of alternatives appear, then you’ll need to say a use command to select the row you want, like:

use one

in order to select the first alternative, and so on. If you misspeak or want to start over, just say:

clear

After you say a use command for the appropriate row, you should see the following code appear:

def factorial

Now, finish that line with another type command, this time with a few symbols:

type paren n close paren colon

That should produce:

def factorial(n):

Next, you can create a new line by saying:

newline

You’ll notice that you didn’t have to specify use one that time. Instead, Serenade just executed the command for you—because you weren’t adding free-form text, there was nothing else to say for that command. More on that in the next section, Concepts.

Add

The add command is a much more powerful way to write code. Start by deleting the code you have so far with:

delete file

Next, create a new function with add rather than type by saying:

add function factorial

You should see:

def factorial():
    pass

You can think of the add command as a smarter version of the type command you were using before. add was smart enough to create a syntactically-valid block of code for you, so you didn’t need to dictate all of the syntax required to create a function.

Now, let’s add a parameter to that function using another add command:

add parameter number

You should now see:

def factorial(number):
    pass

Here, you’ll notice that you didn’t need to move your cursor to the inside of the parentheses, as you would have needed to do with type. Instead, add was smart enough to insert the code you wanted in the right place.

Now, let’s say you change your mind, and want to change number to n. You can do this a few different ways.

One way is to go to that part of the text with:

go to phrase number

And then say:

change word to n

Alternatively, you could just say:

change parameter to n

After you do one of those, you’ll want to move your cursor back to the line it was on before, so you can say:

down

Now, you can add the same if statement as before with:

add if n double equals zero

You should see:

def factorial(n):
    if n == 0:
        pass

You’ll notice that the pass statement that was on line two was automatically removed by the add command, so you didn’t have to do that yourself (in addition to a colon and new pass statement being created). This is another example of the power of add compared to the simpler type command for raw text.

You can finish the if with:

add return one

To produce:

def factorial(n):
    if n == 0:
        return 1

Now, create a new line with:

newline

That command will automatically maintain the indentation level you had previously, so to decrease the indentation by one, just say:

dedent

Now, you can add the else with:

add else return n

You should now have the code:

def factorial(n):
    if n == 0:
        return 1
    else:
        return n

To add the second half of the return statement, you can say:

type space times factorial in parens n minus one

To fix all of the spacing in the file automatically, just say:

style file

Now, you should have the final code:

def factorial(n):
    if n == 0:
        return 1
    else:
        return n * factorial(n - 1)

Of course, you could also have added the else with a single command:

add else return n times factorial in parens n minus one

However, you’ll often find that you won’t know an entire line of code before you start speaking, so it can be more efficient to break up longer lines into multiple commands.