====== SmileBASIC API Reference ======

This page is a series of notes gathered while reading [[http://smilebasic.com/en/e-manual/|the official SmileBASIC documentation]] and [[http://smilebasic.com/wordpress/wp-content/themes/smilebasic/media/pdf-en/InstructionList.pdf|their Instruction List]]. It's not as clear to read as other code documentation sites out there, so my intent is to consolidate it to something easy to browse and reference.

Function names will be listed alphabetically. Feature-related lists of links will be provided as a convenience.

NOTE In case it's not obvious, this is a work in progress. NOTE

===== Names and Variables =====

SmileBASIC supports variable names that are alphanumeric, with optional underscores. Anything that matches this regex should do: ''[a-zA-Z0-9_]+''

===== System Variables =====

===== Types =====

When defining a variable, you encode its type along with its name.

==== Strings ====

Strings are defined via the ''$'' sigil:

<code freebasic>
A$ = "HELLO WORLD"
PRINT A$
' outputs 'HELLO WORLD'
</code>

==== Numbers ====

Numbers can be integers, or floating point numbers. Variables are integers by default.

<code freebasic>
B# = 4
PRINT B#
' outputs '4'
</code>

===== Operators =====

Every programming language has operators, and //SmileBASIC// is no exception.

==== Arithmetic ====

These operators are your standard addition, subtraction, multiplication, and division. Modulo is usually also included in this set.

  * ''+''
  * ''-''
  * ''*''
  * ''/''
  * ''%''

==== Comparison ====

Comparison operators allow you to make decisions when you need to branch the behavior of a program with ''IF..THEN'' or fancy ''[[#goto|GOTO]]'' spaghetti.

  * ''=='' - Equality
  * ''!='' - Inequality
  * ''>'' - Greater Than
  * ''<'' - Less Than
  * ''>='' - Equal to or Greater Than
  * ''<='' - Equal to or Less Than

These same operators can be used stand-alone in expressions to generate boolean values, which are typically ''0'' or ''1''.

==== Logical ====

Logical operators are often combined with expressions that contain comparison operators in order to make meaningful decisions in the program. This means most "business" problems in programming can be broken down into //some// variation of:

<code>
Solution = Logical operations of expressions, containing
           comparisons of variables, containing
           anything from numbers to text to lists.
</code>

If you can abstract a problem into this framework, you are mastering logical operators.

  * ''&&'' - Logical AND
  * ''||'' - Logical OR

The more legible ''AND'' and ''OR'' may also be used, but precedence may differ. More testing is needed.

===== Logic and Control Flow =====

These functions or constructs are used to manipulate the flow, or structure, of your programs.

  * [[#at_sign|@]]
  * [[#goto|GOTO]]

===== Input/Output =====

  * [[#input|INPUT]]
  * [[#print|PRINT]]

===== Graphics Layering =====

===== Sound Effects and Music =====

===== DIRECT Mode Commands =====

===== Function Reference =====

This section is where all the "proper" content lives. Other parts of the page should link back here where relevant.

==== At sign (@) ====

The sigil for a label for [[#goto|GOTO]] to target. Declare a label by typing ''@'', then the name of the label. Later, use ''GOTO'' to point to it. Just be careful you don't put yourself into an infinite loop!

==== CLEAR ====

''CLEAR''

Initializes the internal BASIC memory.

TODO: Does this also erase/initialize variables away?

==== GOTO ====

''GOTO @label''

Jump to the specified label in the code, and continue execution.

//SmileBASIC//, being a derivative of BASIC, lacks many things that higher level languages take for granted today, like do/while, for loops, switch/case, list comprehensions, map/reduce, and so on. Most if not all of these can be implemented in GOTO, albeit it gets messy if your methods aren't rock-solid. This will be your //go-to tool// in getting anything out of BASIC that resembles these higher-level concepts.

==== INPUT ====

''INPUT [message string ;] variable''

Accepts keyboard input and stores it into the given variable; an optional message can be included as a quoted string, followed by a semicolon ('';'').

==== LOCATE ====

''LOCATE [X coord][, Y coord][, Z coord]''

Position the text cursor at the given (X,Y) coordinates (in character cell units instead of pixels), with an optional Z coordinate if the Nintendo 3DS is in 3D Mode.

=== Value Ranges ===

^ Axis ^ Range ^
|  X   | 0-49 |
|  Y   | 0-29 |
|  Z   | -256-1024 |

The Z axis defaults to 0.

Any missing axes from a LOCATE call will be filled in with the last value used for that axis. All axes default to 0 if LOCATE is called after a CLEAR.

==== PRINT ====

''PRINT [expression[; expression || : expression ...]]''

Output the given ''expression'' to the screen. Using a semicolon ('';'') as delimiter concatenates expressions without spaces between them, while the comma ('','') adds TABSTEP spaces.

Using a question mark before an expression is a shorthand for calling PRINT:

<code freebasic>
?(7 + 2) ' outputs 9
</code>

String values can be concatenated with either the semicolon ('';''), or the addition operator (''+''):

<code freebasic>
A$ = "beep "
B$ = "boop"
?(A$+B$) ' outputs "beep boop"
</code>