Hydrogen Basics

How do I write Python code in a .md file?

Markdown has a wonderfully easy function that enables you to insert blocks of code written in dozens of common programming languages like Python directly into the file itself. To do this, simply type three consecutive backticks/backquotes, that key with the tilda that you probably seldomly use, followed by the name of the programming language you wish to write in. In our case, we’ll always use Python. On a new line, you can begin writing your block of code. Once you finish writing your code, make sure to end the block with three more backticks/backquotes on the line below your final line of code. You should end up with something that looks like this:

```python
myGreeting = 'Welcome to AguaClara!'
print(myGreeting)
```

In your .md file, the resulting output will look something like this:

myGreeting = 'Welcome to AguaClara!'
print(myGreeting)

Now lets say I want to insert a block of plain text like this sentence after a block of code, but decide that I want to continue developing my code after the plain text. Instead of starting a new code block and adding everything I previously coded in the old block into my new code block, I can simply continue writing my code where I left off. For example, say I want to append something to myGreeting in a code block after this paragraph. All I have to do to implement this is as follows:

myNewGreeting = myGreeting + ' I hope you have a fun time!'
print(myNewGreeting)

My variable assignments from my first code block are recognized in my second code block, meaning my assignments for myGreeting carries between the two blocks.

Running the code with Hydrogen

Hydrogen: Run

Hydrogen: Run is the most basic command for running your code, and will execute exactly what you tell it to. The quick keystroke to perform this action is Cmnd + Enter or Cntrl + Enter. There are several ways to use Hydrogen: Run.

• Selected Code: If you’ve highlighted a block of code and perform Hydrogen: Run, the entire block of code will be executed.

• Current Block: If you haven’t highlighted any code, Hydrogen will attempt to run code on or before the line your cursor is on.

  • If you’re on a line with a complete code expression, Hydrogen: Run will evaluate that line only.

  • If you’re on a line that begins a loop, Hydrogen: Run will evaluate the entire loop.

  • If you’re on a blank line, Hydrogen: Run will run the first block of code above your current position.

Hydrogen: Run All and Hydrogen: Run All Above

Hydrogen: Run All and Hydrogen: Run All Above are two useful functions that enable you to run an entire script without selecting all the code. Unfortunately, both commands are not supported within a .md file, and will only be helpful if you work out of a .py file.

• To use Hydrogen: Run All, simply press Cmnd + Cntrl + Enter anywhere in your code.

• To use Hydrogen: Run All Above, you’ll have to use Cmnd + Shift + P to open the Atom palette and search for the command itself since it doesn’t come with a keybinding by default.

How do I know if my code has been executed by Hydrogen?

The great thing about Hydrogen is that it’s incredibly easy to know if the Python code you wrote is syntactically correct and executable. If we look at the code I wrote above, and use Hydrogen: Run on the block, we’ll get two things to show up. The first thing we’ll see is a little check mark next to the line myGreeting = 'Welcome to AguaClara!'. This check indicates that Hydrogen has evaluated that code, but since that line is purely a variable assignment with no output, Hydrogen won’t produce any output. In the line containing print(myGreeting), Hydrogen outputs the string “Welcome to AguaClara!” because the print() function in Python produces an output.

Hydrogen will also tell you when your code is bad and won’t execute by giving you the error message that any other Python interpreter would give if you attempted to run the same bad code. In the case of our sample code, I left out a single quote at the end of my message, so Python couldn’t interpret it as a string, and Hydrogen told me what the syntax error was in the message.

Now, complete Lesson 3 of the interactive tutorials. It’s in the Interactive-Tutorial-3-Hydrogen.md file in your aguaclara_tutorial repository.