//
//------------------ DOK FILE --------------------------------------------------
+Header	toplevelLib
=pkg	bios
=title	Top-level
=short	commands for the top-level
=desc
The Top-level interface may be started from [minimacy]/topLevel.mcy
Alternately it is possible to start it with the following call:
	consoleStart(nil)
This Top-level can be seen as a text-based console, in which you can run commands to get information about the state of the Virtual Machine, including processes, threads, memory, network connections, ...
Most of the following functions could also be called from your own programs, mostly for debugging. For example insert the following to dump the callstack at any point of your program:
	dumpCallstack(nil)
//
//
//------------------ PROTO ----------------------------------------------------- consoleStart
+Proto	consoleStart
=type	fun Package -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function starts a Top-level prompt. It allows to type Minimacy expressions and evaluate them.
	consoleStart (nil)
>Minimacy Top-level
>Ready
>
>] pi
>-> Float: 3.14159
>] 123+456
>-> Int: 579 (0x243)
>]
Question is: which functions are visible from the Top-level?
When passing [[nil]] as the 'package' argument, a new empty package is created which sees only the Bios functions.
When passing an existing package, the Top-level may use any function defined in this package or visible from this package. And the name of the package is displayed before the prompt character ']'.
For example let's define a file test.console.mcy with:
	fun test() = echoLn "TEST";;
	fun main() = consoleStart (pkg);;
Launch this file:
>> ---- package: test.console
>> fun test : fun -> Str
>> fun main : fun -> Bool
>>
>> compiled in 1 ms
>
>
>
>Minimacy Top-level
>Ready
>
>test.console] test
>TEST
>-> Str: "TEST"
>test.console]

//
+arg	package
=type	Package
=desc	An existing package or [[nil]] for a new empty package
//
+arg	result
=type	Bool
=desc	Always true
//
//
//------------------ PROTO ----------------------------------------------------- help
+Proto	help
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	Display the help message.
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- sys
+Proto	sys
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	Displays all the available data: [[pkgList]], [[ts]], [[inputs]], [[timers]], [[net]], [[mounts]], [[ms]].
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- timers
+Proto	timers
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	Displays the list of current timers and associated threads.
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- dumpCallstack
+Proto	dumpCallstack
=type	fun Int -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
Displays the current callstack of a specific thread. When id is nil, displays the current callstack of the current thread.
Be aware that due to terminal function call optimization, the callstack may present some "hole".
Assume that function A calls B which calls C which calls dumpCallstack, the expected callstack should display C, B, A.
However if B calls C as a terminal function call, the callstack will display C, A.
Terminal function call is when the function call is the last operation in the evaluation of a function.
//
+arg	id
=type	Int
=desc	A thread ID, or nil
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- reboot
+Proto	reboot
=type	fun -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function performs a full restart of the Virtual Machine.
//
+arg	result
=type	Int
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- dir
+Proto	dir
=type	fun Str -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function displays the content of the specified path.
	> dir ("demo")
	
>   DIRECTORY | Fri, 03 Feb 2023 18:36:14 UTC | demo/fun/
>        1011 | Mon, 26 Feb 2024 18:00:53 UTC | demo/demo.2d.qrcode.mcy
>        3837 | Mon, 26 Feb 2024 18:00:53 UTC | demo/demo.2d.triangulation.mcy
>        5315 | Tue, 06 Feb 2024 21:21:12 UTC | demo/demo.fun.boing.mcy
>         901 | Tue, 27 Feb 2024 05:33:26 UTC | demo/demo.fun.mandelbrot.mcy
>        1286 | Fri, 12 Jan 2024 17:07:48 UTC | demo/demo.fun.maze.mcy
>         823 | Tue, 30 Jan 2024 16:37:44 UTC | demo/demo.fun.queens.mcy
>        6588 | Mon, 26 Feb 2024 18:00:53 UTC | demo/demo.fun.tetris.mcy
>7 element(s)
>-> Bool: true
//
+arg	path
=type	Str
=desc	A path
//
+arg	result
=type	Bool
=desc	Always true
//
//
//------------------ PROTO ----------------------------------------------------- start
+Proto	start
=type	fun Str -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	explicit
=desc
This function starts a new App based on the specified package.
	> start ("demo.fun.maze")
//
+arg	pkgName
=type	Str
=desc	The name of a package
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- pkgList
+Proto	pkgList
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function displays the list of the packages already loaded into the VM.
	> pkgList()
>   core.console
>   boot
>   bios
>-> Bool: true
//
+arg	result
=type	Bool
=desc	Always true
//
//
//------------------ PROTO ----------------------------------------------------- pkgScope
+Proto	pkgScope
=type	fun Package -> a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function displays the list of the functions which are visible from the specified package.
//
+arg	p
=type	Package
=desc	A package
//
+arg	result
=type	a1
=desc	Always nil
//
//
//------------------ PROTO ----------------------------------------------------- pkg
+Proto	pkg
=type	Package
=mode	constant
=pkg	bios
=impl	mcy
=link	
=desc	This constant is the current package, the package in which this "pkg" keyword is present.
//
//
//------------------ PROTO ----------------------------------------------------- fs
+Proto	fs
=type	fun -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- partitions
+Proto	partitions
=type	fun -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- inputs
+Proto	inputs
=type	fun -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- mounts
+Proto	mounts
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- ms
+Proto	ms
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- net
+Proto	net
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- ts
+Proto	ts
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc