BASIC language
The BASIC language, word by word
Every statement, directive and operator of aukimi's BASIC dialect, and the 52 commands the compiler itself provides: lists, maps, tasks, handles. Each page gives the syntax, what every part means, a program that compiles, and the traps.
The 2 000+ commands of the catalogue (sprites, sound, 3D…) are in the command reference.
Control flow · 11
- IFStatementRuns a block of statements only when a condition is true, with optional ELSEIF and ELSE branches. The first true branch runs and the others are skipped.
- SELECTStatementCompares one value with a list of CASE values and runs the branch of the first match. CASE DEFAULT runs when nothing matched.
- FORStatementRepeats a block while a counter goes from a start value to an end value, adding the step after each pass.
- WHILEStatementRepeats a block as long as a condition is true. The condition is tested before each pass, so the body can run zero times.
- REPEATStatementRepeats a block until a condition becomes true. The condition is tested after each pass, so the body runs at least once.
- DO … LOOPStatementRuns its body once per frame: the frame loop of a classic game. Code before DO runs once first, code after LOOP runs once when EXIT leaves the loop.
- EXITStatementLeaves the innermost loop at once. The program continues after its NEXT, ENDWHILE, UNTIL or LOOP.
- CONTINUEStatementSkips the rest of the current pass and starts the next pass of the innermost loop.
- GOTOStatementJumps to a label. A backward jump repeats code, a forward jump skips code and can leave loops.
- GOSUBStatementRuns the subroutine that starts at a label, up to its RETURN, then continues after the GOSUB.
- ENDStatementStops the program at once. Nothing after it runs, not even the code after LOOP.
Program · 2
Declarations · 13
- DIMStatementDeclares an array, with one or more dimensions, whose bounds are inclusive. UNDIM empties it.
- GLOBALStatementDeclares a variable shared by the whole program, every FUNCTION included. It works anywhere, even inside a FUNCTION.
- LOCALStatementDeclares a variable that belongs to one call of a FUNCTION. It hides a program variable of the same name.
- ASStatementGives a variable or an array a type. From then on, every value stored in it is converted to that type.
- OPTION EXPLICITDirectiveMakes declarations compulsory: every name the program writes to must be declared first, or the program does not compile.
- #CONSTANTDirectiveNames a fixed value. The constant is read back with # in front of its name, anywhere in the program.
- ENUMERATIONStatementDeclares a run of numbered constants, one per line. ENUMERATIONBINARY doubles the value at each line, for flags.
- DATAStatementWrites constant values in a DATASECTION. READ takes them one by one, in order; RESTORE moves the reading position.
- INC / DECStatementAdds 1, or an amount, to a variable (INC), or subtracts it (DEC).
- FOREACHStatementWalks a list or a map from its first element to its last. Inside the loop, the element of this pass is the current one.
- Array membersStatementReads the size of an array, resizes it, inserts, removes, finds and sorts cells, through members written after a dot.
- NewListStatementDeclares a list: values kept in order, with one current element. <name>() reads or writes that element.
- NewMapStatementDeclares a map: values stored under text keys. <name>(<key>) reads or writes one entry, <name>() the current one.
Structures and functions · 13
- FUNCTIONStatementDeclares a named block of code that takes parameters and can give back a value. It runs to its end in one go, inside the current frame.
- Lifecycle functionsStatementGives a FUNCTION a reserved name so that the Engine calls it by itself: once at start, every frame, at a fixed rate, or when a collision, a trigger, a message or an animation event happens.
- REFStatementMarks a FUNCTION parameter that receives the caller variable itself instead of a copy, so that the function can change it.
- @ handlesStatementMakes a handle: a value that points at a variable. You can store it, pass it and return it, then read or write the variable through it.
- TYPEStatementDeclares a record type: a group of named fields, each with its own type. A record is a value: assigning it to a declared variable makes a deep copy.
- METHODStatementDeclares a function that belongs to a TYPE. Inside it, SELF is the record the method was called on.
- NEWStatementCreates a fresh record of a TYPE and passes the arguments to its New method, the constructor, if it has one.
- DELETEStatementEnds a record: runs its Delete method, if it has one, then marks the record as deleted.
- WITHStatementOpens a block where \field stands for <record>.field, anywhere on the line, to write less when many lines touch one record.
- WITH <family>StatementOpens a block where \property calls the catalogue command <Family><Property> on one object, so its id and the family name are written once.
- Dot notationStatementAttaches a command family to a variable, so that s.position(100, 200) calls SpritePosition(s, 100, 200) and s.x reads SpriteX(s), anywhere in the program.
- $"…"OperatorBuilds a string from text and holes: each {expression} is replaced by Str(expression), and the whole string becomes a concatenation.
- @exposeDirectiveTurns the top-level assignment on the next line into a setting shown in the Inspector. The value set there replaces the value written in the code when the program starts.
Preprocessor · 5
- #INCLUDEDirectivePuts the lines of a BASIC module of the project in place of the directive, once per program. Later requests for the same module are skipped.
- #INSERTDirectivePuts the lines of a BASIC module of the project in place of the directive, every time it appears.
- IncludeFileFunctionPuts the lines of a BASIC module of the project in place of the line, every time it appears. It is PureBasic's name for #INSERT.
- #IFDirectiveKeeps the lines of the first branch whose condition is true and drops the others, before the program is compiled. A condition tests symbols, such as the target profile.
- #DEFINEDirectiveAdds a symbol for #IF with #DEFINE, or removes one with #UNDEF. A symbol has no value: it is defined or not.
Operators · 4
- AND, OR, NOTOperatorCombines conditions: AND is true when both sides are, OR when at least one is, and NOT reverses one. They are logical, not bitwise.
- Bitwise operatorsOperatorComputes on the bits of whole numbers: && and, || or, ~~ exclusive or, ! flips every bit, << and >> shift.
- DIVOperatorDivides two numbers. / keeps the decimals; DIV keeps only the whole part, cut toward zero.
- ComparisonOperatorCompares two values: equal, different, less, greater, less or equal, greater or equal. Numbers compare by value, text by character codes.
Lists · 25
- AddElementList commandAdds a new element after the current one and makes it the current element. The new element holds the default value of the list type.
- InsertElementList commandAdds a new element before the current one and makes it the current element. The new element holds the default value of the list type.
- DeleteElementList commandDeletes the current element. The element before it becomes the current one.
- ClearListList commandRemoves every element of a list. The list stays usable and has no current element.
- FreeListList commandRemoves every element of a list and frees the list. It cannot be used again until a new NewList declares it.
- ListSizeList commandReturns the number of elements in a list.
- ListIndexList commandReturns the position of the current element, counted from 0.
- ResetListList commandMoves the cursor before the first element, so that the next NextElement() lands on the first one.
- NextElementList commandMoves the cursor to the next element and makes it current.
- PreviousElementList commandMoves the cursor to the previous element and makes it current.
- FirstElementList commandMakes the first element of the list the current one.
- LastElementList commandMakes the last element of the list the current one.
- SelectElementList commandMakes the element at a given position the current one.
- CopyListList commandReplaces the content of one list with a copy of another. Later changes to one list do not show in the other.
- CompareListList commandCompares two lists element by element, in order.
- MergeListsList commandMoves every element of one list into another. The source list ends up empty.
- SortListList commandSorts a list of numbers or strings, in place.
- SortStructuredListList commandSorts a list of records on one of their fields, in place.
- RandomizeListList commandShuffles the elements of a list, or of a range of it, into a random order.
- PushListPositionList commandRemembers the current element on a stack, so that PopListPosition() can come back to it later.
- PopListPositionList commandMakes the element saved by the last PushListPosition() current again, and removes it from the stack.
- MoveElementList commandMoves the current element to another place in the same list. It stays the current element.
- SwapElementsList commandSwaps two elements of a list, given by their positions.
- SplitListList commandMoves the current element and every element after it into another list.
- ChangeCurrentElementList commandMakes the element at a given position the current one. It is another name for SelectElement().
Maps · 13
- AddMapElementMap commandCreates the entry for a key and makes it the current entry. An entry that already exists is reset to the default value.
- FindMapElementMap commandLooks for a key without creating it. When the key exists, its entry becomes the current one.
- DeleteMapElementMap commandDeletes the entry of a key, or the current entry when no key is given.
- ClearMapMap commandRemoves every entry of a map. The map stays usable.
- FreeMapMap commandRemoves every entry of a map and frees it. A freed map cannot be used until it is declared again with NewMap.
- MapSizeMap commandGives the number of entries in a map.
- MapKeyMap commandGives the key of the current entry of a map.
- ResetMapMap commandMoves the cursor of a map before its first entry, so that the next NextMapElement() goes to the first entry.
- NextMapElementMap commandMoves to the next entry of a map and makes it current. Entries come in the order they were created.
- CopyMapMap commandReplaces every entry of the destination map with a copy of the source map's entries.
- CompareMapMap commandTells whether two maps hold the same keys with the same values. The order in which the entries were created does not matter.
- PushMapPositionMap commandRemembers the current entry of a map on a stack, so that PopMapPosition() can come back to it.
- PopMapPositionMap commandGoes back to the entry remembered by the last PushMapPosition() and makes it current again.
Numbers · 3
Handles · 4
- GetRefFunctionReads the variable, field, array cell, list element or map entry that a handle points at.
- SetRefFunctionWrites a value into the variable, field, array cell, list element or map entry that a handle points at.
- IsRefFunctionTells whether a handle still points at something, so that GetRef() and SetRef() can be used on it safely.
- ReleaseRefFunctionEnds a handle. The variable it pointed at is not touched; only the handle stops working.
Errors · 3
- TRYStatementRuns statements and catches the runtime error they raise. CATCH handles the error, FINALLY always runs at the end.
- THROWStatementRaises an error that the nearest enclosing CATCH receives. Without a CATCH, the program stops at that line.
- RETHROWStatementSends the error being handled in a CATCH on to the next enclosing TRY, unchanged.
Tasks · 11
- STARTTASKStatementStarts a label as a cooperative task that runs alongside the main program, and stores its handle in a variable.
- AWAITTASKStatementPauses the current code until a task ends. The Engine keeps drawing frames in the meantime.
- AWAITALLStatementPauses the current code until every listed task has ended.
- AWAITANYStatementPauses the current code until the first of the listed tasks ends, fails or is cancelled.
- CANCELTASKStatementAsks a task to stop. The task stops at its next yield, and the code after that yield never runs.
- YieldTaskFunctionEnds the current frame and resumes on the next one, like Sync(). Its name reads well inside a task.
- WaitFunctionPauses the current code for a number of seconds of game time. The Engine keeps drawing frames during the wait.
- TaskDoneFunctionTells whether a task has returned normally. Polled from the main loop, it lets the game keep drawing while the task works.
- TaskFailedFunctionTells whether a task stopped on an error.
- TaskCancelledFunctionTells whether CANCELTASK was called on a task that was still running.
- TaskResultFunctionGives the value that a finished task returned with RETURN.