SBTCVM's SSTNPL, Part 1: basics
Tags: sbtcvm, ternary, sstnpl, tutorial
Published: 2018-10-13 19:34:10

---
title: SBTCVM's SSTNPL, Part 1: basics
published: true
description: A tutorial on making interactive programs for SBTCVM, a balanced ternary Virtual Machine, using SSTNPL.
tags: sbtcvm,ternary,sstnpl,tutorial
---

SBTCVM, being as different to binary as any balanced ternary computer, virtual or not, has plenty of differences that keep existing languages from it (without a shipload of work that is)

In light of this, i wound up creating a second programming language for it, called SSTNPL, or SBTCVM Simplified Ternary Numeric Programming Language. This is the beginning of a series of tutorials on its use, and best practices when working with it.

In part 1, we will take a look at using the 'keyprompt' command in two types of menus, to create a simple program that lets a user change a boolean value.

## getting started

First thing you'll need is [SBTCVM gen 2-9](https://github.com/SBTCVM/SBTCVM-Gen2-9), SBTCVM's latest and greatest iteration, featuring among other things, SSTNPL's compiler.

Once you have that, you can proceed with creating a *.stnp file in the VMUSER directory. (note: if you prefix the .stnp with 'auto_' you can also place it in a subdirectory there)

For this tutorial however, i recommend downloading the example program from the gist embedded in the following section, and placing the *.stnp in VMUSER. 

## The code

{% gist https://gist.github.com/ThomasTheSpaceFox/4a5d1d92d077c7cc3b3a111cc57c3c2a %}

To make things easier, i marked each section clearly with comments `#### LIKE THIS ####`

## Vars

First off, lets look at the **VARS** section. as SSTNPL is fairly static, we need to let it know what variables we will be using. We do this with the `var` statement:

`var varname=@10`
`var varname2=+0-`
`var varname3=:a`

The first example uses signed decimal, via the @ prefix.
The second is plain balanced ternary.
The third uses the given character's code value in SBTCVM's text encoding. This means integer variables can act as 'characters' as well.

## Main

#### Now, lets take a look at **MAIN**.

first, we see a `label`. This lets us use both `goto` and `gsub` (subroutine goto) to jump to that location.

#### Following that we see some text output code:

 - print: prints raw text
 - prline: prints raw text, but appends a newline
 - newline: prints a newline character
 - dumpd: dumps the specified variable in signed decimal as this is used to print our boolean value (called `value`)

#### Keyprompt and set:
`keyprompt` Is a input loop macro that waits for the user to press a key, then continues.

`set` is used to set values returned by several operations to variables.
 here, we `set` the variable `kb` to the value returned by `keyprompt`

#### Conditional subroutine gotos (gsub's):

Its at this point in `main` that we check `kb` against literal character values (letters prefixed with a `:`)

`if kb,:q gsub quit` If `kb` is equal to the character code of `q`, call `quit` as a subroutine

#### goto:

as you might guess, we need to loop here. since we have a label at the top of main, we can jump there:

`goto main`

`goto` both by itself and in conditionals, does not affect return, while `gsub` does. This lets you do complex jumps within subroutines, so its important to note.

## quit:

On a quick touch, exiting an SSTNPL program is simple enough. just use:
`stop`
This will neatly shutdown the VM.

## number:

This section is similar to main, but its acting as a 'value selection' rather than a 'subroutine selection'

#### retflg reset:

looking past the label, we see `val`. This, when used with `set` can be used to directly change the value of variables. here, we use it to reset a return flag.

#### subroutine loop:

after a nifty `prline` message telling the user to press 1 or 0, we then run `keyprompt` in a loop as before. `label number_loop`

#### conditional variable set:

how this 'value selector' works, is it uses pairs of conditional variable sets of both our boolean value variable `value` and our return flag `retflg`

`if kb,:0 =retflg @1`
`if kb,:0 =value @0`

Ooh what have we here? literal decimal integers, using the `@` prefix.
this variable set mode works by setting the variable immediately following the `=` sign, and using the variable or literal just next to that as the data value to use. so if you had a variable called `bob` and wanted to set using that:

`if kb,:0 =value bob`

while we are talking about literals i should mention the ternary literal:

if kb,:0 =value *+0-

same idea as the decimal and character literals, just with a `*` prefix.

#### conditional return:

handily, we can conditionally return from subroutines in SSTNPL using conditionals, rather than the usual `return` command, we do:

`if retflg,@1 return`

This means it will only return when `value` has been set via the user either pressing 1 or 0.

#### loop

As before, we jump to the label we used for the beginning of the loop.
`goto number_loop`


## compiling and running:

easy enough:

compile: `./stnpcom.py tutorial_example`

run: `./SBTCVM_G2_9.py tutorial_example`

## Conclusion:

SSTNPL is fairly low-level, but that doesn't mean it isn't quite useful, if you want to mess around with SBTCVM, and lack good understanding of low level computing.

The takeaway from this, is other than the underlying logic, the overall structure of balanced ternary machines are similar to binary ones, as they both are digital computers and need to be programmed. Hope you found this interesting.


You can find more information on SSTNPL at these links:
[SSTNPL documentation](https://github.com/SBTCVM/SBTCVM-Gen2-9/tree/master/textdocs/SSTNPL)
[General SSTNPL Guide](https://sbtcvm.blogspot.com/p/sstnpl-guide.html)