Notice: Stat is currently in private beta. This documentation is incomplete and subject to change.

Stat Docs

File Types and Sections

Stat is not like most other languages where you can define multiple functions and classes in a single file. In fact, Stat doesn't have classes at all. Instead, Stat takes a different approach and lets the file system manage the structure of your program for you. Each file has a single purpose and a single responsibility. This makes Stat projects easy to maintain, easy to debug, and gets rid of a lot of the ambiguity that other languages tend to have. Do you want to create a class? What is a class other than a collection of functions? In Stat, simply create a folder and put a bunch of function files in that folder. Simple as that. I know, classes also contain properties... aka data. As far as the data goes, Stat keeps behavior and data separate so there is no need for a special "class" file. Everything is either a function that provides behavior, an object that contains data, or a stream that handles input and output.
Every Stat file is made up of 1 or more sections that define what type of file it is as well as how that file behaves. There are several Stat file types and each file type can contain different sections. We are going to go over each file type, what purpose they serve, as well as what sections each file type can contain.

Procedure Files

Procedure files are files that can be directly executed via the command line. They must have a MAIN section and optionally, they can have an IMPORTS section and a META section. Here is an example of a procedure file. 
// This is a simple procedure file that calls a function
// and stores the return value into a variable
IMPORTS
	generateName

// The META section is optional. The only thing the META
// section does in a procedure is define the file type
META
	type procedure

// The MAIN section is where the execution starts
MAIN
	let name = generateString()

 The section order in a Stat file doesn't matter

You can put sections in any order you'd like. It won't change the behavior of the file.
Here is another procedure that outputs a simple greeting 
// The MAIN section is the only required section
MAIN
	let console = console
	"Welcome to Stat\n" -> console

Enum Files

Enum files are simple and only contain a list of possible choices. Enum is short for enumerations and they are used to represent a fixed set of related values such as states, days of the week, colors, statuses or any other value where there are a finite number of fixed choices. Enum files must contain a META section and an OPTIONS section and that's it. They cannot contain any other sections. Here is an example of an enum file. 
// This is an enum file that defines possible statuses.
META
	type enum

OPTIONS
	// Options MUST follow normal variable naming conventions
	// This means that they must start with a lower case
	// letter and can only contain letters and numbers
	pending
	onHold
	processing
	completed
	failed
	cancelled

Function Files

Function files are exactly what you'd think. They contain functions. In Stat, each function file must contain exactly 1 function. You can't have a function file that contains multiple functions. Function files must have a META section and a FUNCTION section. And they can optionally have an IMPORTS section and a PERSIST section. One thing to take note of is that function files cannot be executed. They must be imported before they run. If you try to execute a function file, you'll get an error like so: 
$ Stat path/to/function.stat
RuntimeError: Invalid file type. You can only run procedures
Here are a few examples of function files. 
// This is a simple function call that returns a greeting

// The META section is required.
// You must specify the file type as well as the return type
META
	type function
	return: string

// The FUNCTION section contains the code that will
// run every time the function is called
FUNCTION
	return "Hello There"
Here is a slightly more complex function that takes a name as an argument and returns a personalized greeting 
// This is a simple function call that returns a personalized greeting
META
	type function
	arg name: string
	return: string

FUNCTION
	return "Hello " + name
And one more function that contains persistent variables. This function remembers the number of times it has been called and incorporates that value into the greeting. 
// This is a simple function call that returns a personalized greeting
// and it remembers the number of times it has been called.
META
	type function
	arg name: string
	return: string

// The PERSIST section defines variables that
// persist beyond the execution of a function.
PERSIST
	let calledCount = 0

FUNCTION
	// Increment the called counter
	calledCount += 1

	// Assuming the name passed in is "John",
	// this returns "(1) Hello John" the first time it's called
	// and it returns: "(2) Hello John" the 2nd time it's called, etc...
	return "(" + calledCount to: string + ") Hello " + name
Just like procedures, functions can also have an IMPORTS section. Functions can call functions too. 
// This function simply returns the return value of another function.
IMPORTS
	anotherFunction

META
	type function
	return: anotherFunction()

FUNCTION
	// Assuming that anotherFunction doesn't take any arguments
	return anotherFunction()

 How you name your files matters.

Functions and other file types take on the same name as their file name when they are imported. So, file names must follow the same naming convention as variables and must have the .stat extension

In the example above, the file that is imported is anotherFunction.stat located in the same folder as the function that imported it.

Type Definition Files

Type definition files allow you to define reusable data types that can be imported and used in other Stat files. If you need to define a complex data type and have that data type accessible across other Stat files, then you need to create a type definition file. Type definition files must contain a META section and can optionally contain an IMPORTS section.
Here is an example of a type definition file. 
// This is a type definition for a complex struct that
// would be tedious to re-write every time it's needed.
IMPORTS
	// Import an enum of possible post types
	type
	// Import an enum of possible statuses
	status

META
	type typeDef

	typeDef: {
		id: int,
		postName: string,
		postType: types,
		postStatus: status,
		postContent: string,
		postComments: [string]
	}

Interface Files

Interface files are simply function files without the FUNCTION section. The purpose of interface files is to define a function data type without defining an actual function. They're essentially type definition files, but for functions. Interface files must contain a META section and can optionally contain an IMPORTS section.
Here is an example of an interface file that defines a function type that takes 2 arguments, name and age and that returns a bool value 
// This is a simple interface file
META
	type interface

	arg name: string
	arg age: int
	return: bool

The MAIN section

The MAIN section is where execution always starts. Put the code that should run when the program starts in this section. Only procedure files should contain a MAIN section.
Here is an example of a procedure file: 
// This is a simple procedure file that outputs Hello World
MAIN
	let out = open console
	"Hello World\n" -> out
	// Prints "Hello World" on the screen

The META section

The META section defines the file type as well as some other properties for the file. The statements that a META section contains depends on the file type as each file type can contain different statements within the META section
  • Procedure Files: These files can only contain a type procedure statement in the META section
  • Enum Files These files MUST only contain a type enum statement in the META section
  • Function Files These files can contain the following statements in the META section:
    • Function files MUST contain a type function statement in the META section
    • Function files MUST contain a return: type statement in the META section. The type must be a valid data type
    • Function files can optionally contain 1 or more arg name: type statements in the META section. One for each argument that the function takes.
    • Function files can optionally contain 1 or more generic T statements in the META section. One for each generic that the function defines. (More on generics later)
    • Function files can optionally contain a no events statement in the META section to disable event listeners
    • Function files can optionally contain 1 or more prop propertyName statements in the META section. One for each function property
  • Type Definition Files These files MUST contain the following statements in the META section
    • Type definition files MUST contain a type typeDef statement in the META section
    • Type definition files MUST contain a typeDef: type statement in the META section
  • Interface Files These files follow the same rules as Function Files when it comes to the statements that are allowed in the META section
Here are some examples:
// An example procedure file
META
	// This statement is optional as procedure is the default file type
	type procedure

MAIN
	return 0
// An example enum file
META
	// This statement is required to set the file type as an enum file
	type enum

OPTIONS
	choice1
	choice2
// An example function file
META
	// This statement is required to set the file type as a function file
	type function

	// We can disable events on this function
	no events

	// We can have 1 or more generic definitions
	generic T
	generic U

	// We can have 1 or more function argument definitions
	arg firstName: string
	arg lastName: string = "Doe"

	// We can have 1 or more function property definitions
	prop calledCount: int = 0

	// This statement is required. We have to define the type of value that the function returns
	return: int

FUNCTION
	return 0
// An example type definition file
META
	// This statement is required to set the file type as a type definition
	type typeDef

	// This statement is required. We must define the type definition
	typeDef: string
// An example interface file
META
	// This statement is required to set the file type as an interface file
	type interface

	// We can disable events on this interface
	no events

	// We can have 1 or more generic definitions
	generic T
	generic U

	// We can have 1 or more function argument definitions
	arg firstName: string
	arg lastName: string = "Doe"

	// We can have 1 or more function property definitions
	prop calledCount: int = 0

	// This statement is required. We have to define the type of value that the function returns
	return: int

The IMPORTS section

The IMPORTS section is nothing more than a list of files to import. Each import statement is simply a path to the file that's being imported that's relative to the current file and without any file extension. Each import statement can optionally be renamed by appending as variableName after the import path. Here are some examples: 
// An example of imports
IMPORTS
	// This imports the file myFile.stat that's in the same folder as this file
	myFile

	// This imports the file upperFile.stat that's located 1 directory up
	../upperFile

	// This imports the file subFile.stat that's located in the "sub" folder
	sub/subFile

	// This imports the file anotherFile.stat that's located in a folder that's located 1 directory up
	../anotherFolder/anotherFile

	// This imports the file renameFile.stat that's in the same folder as this file
	// It also renames the imported variable to myVar
	renameFile as myVar

MAIN
	return 0

The FUNCTION section

The FUNCTION section is straight forward. It contains the function body for function files. Every time a function is called, this is the code that gets executed. 
// An example of the FUNCTION section
META
	type function
	return: int

FUNCTION
	// This gets executed every time the function is called
	return 0

The PERSIST section

The PERSIST section defines variables that persist beyond the execution of a function. A PERSIST section can only be defined within a function file. Here is an example: 
// An example of the PERSIST section
META
	type function
	return: string

PERSIST
	// Any variables that are defined in this section persist
	// beyond the end of the function call
	let counter = 0

FUNCTION
	// Increment the counter
	counter += 1

	// Return a string that tells how many times this function was called
	return "Executed " + counter to: string + " times"

The OPTIONS section

The OPTIONS section simply defines options for an enum. Each option should be on its own line and should follow the same naming rules as for variable names. 
// An example enum
META
	type enum

OPTIONS
	// Each choice on its own line
	choice1
	choice2
	choice3
Previous
Next