Basic Usage

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

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

Type

You can add dictated text with the type command. Try saying:

type def factorial

Remember, if you see a list of alternatives on the right, then you’ll need to say:

use one

In order to select the first alternative, and so on. If you’d like to start over, just say:

clear

After you say use for the appropriate row, you should see:

def factorial

Finish that line with another type command:

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

Next, let’s look at a few more powerful commands that let you achieve the same result much more quickly. To start, create a function by saying:

add function factorial

Now, you should see:

def factorial():
    pass

You can think of add as a smarter version of the type command you’ve been using. add was smart enough to create a syntactically-valid block of code for you, without you needing to dictate all of the syntax for creating a function.

Now, let’s add a parameter to the 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 parens, 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 first parameter to n

Either way, you’ll now want to move your cursor back to the next line, so you can say:

down

Now, you can add the if statement 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. 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 the entire line of code before you start speaking, so it can be more efficient to break up longer lines into multiple Serenade commands.