stdos - anssihalmeaho/funl GitHub Wiki

stdos

Operating system related services.

getenv

Can be use in two way:

  1. get all environment variables (no argument given)
  2. get environment variable value corresponding name given as argument (string)

type: procedure

Format:

call(stdos.getenv <name-string>) -> <list>
call(stdos.getenv) -> <map>

Return value:

  1. case all read => map, where env.variable names are keys and env. variable values as values
  2. list with two items:
    1. bool : true if environment variable found, false otherwise
    2. if found environment variable value (string), '' otherwise

Example: environment variable name given

found env-var-value = call(stdos.getenv 'MY_TEST_ENV'):
sprintf('found: %v, value: %s' found env-var-value)
-> 'found: true, value: just-test'

setenv

Sets new value for environment variable, environment variable name is given as argument and new value.

Arguments:

  1. environment variable name (string)
  2. new value for environment variable (string)

type: procedure

Format:

call(stdos.setenv <name-string> <new-value-string>) -> <string>

Return value:

  • '' if set successfully
  • otherwise string describing error

unsetenv

Unsets environment variable, environment variable name is given as argument.

type: procedure

Format:

call(stdos.unsetenv <name-string> <new-value-string>) -> <string>

Return value:

  • '' if set successfully
  • otherwise string describing error

exit

Causes program (OS process) to exit, call will not return. Status code to be returned can be given with optional argument (int). If argument is not given, status code is 0.

type: procedure

Format:

call(stdos.exit <status-code-int>)
call(stdos.exit)

Return value: no return value, call does not return

reg-signal-handler

Registers signal handler.

type: procedure

Arguments:

  1. procedure which is called when signal is received
  2. N times -> signal number (int) which is to be handled with handler

Handler format:

proc(signal-number signal-text) ... end

Format:

call(stdos.reg-signal-handler <handler-procedure> <signal-num-1> <signal-num-2> ...) -> true

Return value: true

Example:

handler = proc(sig text) call(stdio.printf 'signal received: %d, %s\n' sig text) end
_ = call(stdos.reg-signal-handler handler 2)

import stdtime
call(stdtime.sleep 5)

-->
<ctrl-c>
signal received: 2, interrupt
<ctrl-c>
signal received: 2, interrupt
<sleeping>
true

exec

Executes external command. Program to be executed is 1st argument. Optionally there are arguments for program.

Returns:

  1. status of execution (bool: true if executed ok, false if failed)
  2. text (string) defining error (if failed)
  3. stdout as bytearray
  4. stderr as bytearray

type: procedure

Arguments:

  1. program to be executed (string)
  2. arguments to program (string) -> 0...N, optional

Format:

call(stdos.exec <program:string> <args:string> ...) -> list(ok:bool error:string stdout:opaque(bytearray) stderr:opaque(bytearray))

Example:

ns main

import stdos
import stdbytes

main = proc()
	ok err out errout = call(stdos.exec 'ls' '-ls'):
	list(
		ok
		err
		call(stdbytes.string out)
		call(stdbytes.string errout)
	)
end

endns

Prints:

list(true, '', 'total 12774
    4 -rwxrwxrwx 1 root root     2485 maali  6 13:57 CONTRIBUTING.md
    4 drwxrwxrwx 1 root root     4096 maali  6 16:29 examples
    1 -rwxrwxrwx 1 root root      474 maali  6 16:02 exec_koe.fnl
    4 drwxrwxrwx 1 root root     4096 maali  6 16:29 funl
12724 -rwxrwxrwx 1 root root 13025624 maali  6 16:29 funla
    1 -rwxrwxrwx 1 root root       46 elo   21  2020 go.mod
    4 -rwxrwxrwx 1 root root     3639 elo   21  2020 hellow.png
    4 -rwxrwxrwx 1 root root     1092 elo   21  2020 LICENSE
    4 -rwxrwxrwx 1 root root     3672 elo   25  2020 main.go
    1 -rwxrwxrwx 1 root root      260 elo   21  2020 Makefile
    0 drwxrwxrwx 1 root root        0 maali  6 16:29 pmap
    4 -rwxrwxrwx 1 root root     2857 maali  6 13:57 README.md
    4 drwxrwxrwx 1 root root     4096 maali  6 16:29 std
    4 drwxrwxrwx 1 root root     4096 maali  6 16:29 stdfun
    8 -rwxrwxrwx 1 root root     5306 elo   21  2020 tester.fnl
    4 drwxrwxrwx 1 root root     4096 maali  6 16:29 tst
    0 drwxrwxrwx 1 root root        0 maali  6 16:29 tstfwk
', '')

exec-with

Similar to exec (executes external command).

First argument is map defining options, currently only one option 'stdin'. With 'stdin' user can provide stdin data (bytearray) to command.

Returns:

  1. status of execution (bool: true if executed ok, false if failed)
  2. text (string) defining error (if failed)
  3. stdout as bytearray
  4. stderr as bytearray

type: procedure

Arguments:

  1. map containing options (currently just key 'stdin')
  2. program to be executed (string)
  3. arguments to program (string) -> 0...N, optional

Format:

call(stdos.exec-with <options:map> <program:string> <args:string> ...) -> list(ok:bool error:string stdout:opaque(bytearray) stderr:opaque(bytearray))

Example:

ns main

import stdos
import stdbytes

main = proc()
	input = call(stdbytes.str-to-bytes 'some input')
	ok err out errout = call(stdos.exec-with map('stdin' input) 'tr' 'a-z' 'A-Z'):
	list(
		ok
		err
		call(stdbytes.string out)
		call(stdbytes.string errout)
	)
end

Prints:

list(true, '', 'SOME INPUT', '')
⚠️ **GitHub.com Fallback** ⚠️