IO: Difference between revisions

From MemCP
Jump to navigation Jump to search
(Created page with "= IO = The '''IO''' module provides functions for input and output operations, environment handling, file streaming, server control, and argument parsing in SCM. ← Back to Full SCM API documentation == print == Prints values to stdout (only in IO environment) '''Allowed number of parameters:''' 1–1000 '''Parameters:''' * '''value...''' (<code>any</code>): values to print '''Returns:''' <code>bool</code> == env == returns the content of a environment vari...")
 
(Refresh MemCP documentation: accuracy, operational guidance, performance profile and maintained API reference)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
<!-- Copyright (C) 2026 Carl-Philip Haensch -->
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
<span id="io"></span>
= IO =
= IO =


The '''IO''' module provides functions for input and output operations, environment handling, file streaming, server control, and argument parsing in SCM.
<!-- Generated from MemCP c42e19eba on 2026-08-27; do not edit manually. -->
<div class="mw-message-box mw-message-box-notice">Generated from MemCP commit <code>c42e19eba</code> on 27 August 2026. See [[Full SCM API documentation]].</div>
 
The '''IO''' module provides process-facing input and output facilities for Scheme programs and embedded services. It includes console output, environment access, files and streams, HTTP helpers, serialization, argument handling, and server-control functions.


← Back to [[Full SCM API documentation]]
IO functions are intentionally effectful. Treat filenames, URLs, environment values, request data, and generated output as trust boundaries; restrict administrative handlers and do not expose arbitrary IO primitives to untrusted users.


== print ==
== print ==
Line 9: Line 16:
Prints values to stdout (only in IO environment)
Prints values to stdout (only in IO environment)


'''Allowed number of parameters:''' 1–1000
'''Allowed number of parameters:''' 0–10000
 
<span id="parameters"></span>
=== Parameters ===
 
* '''value...''' (<code>any</code>): values to print ''(variadic)''


'''Parameters:'''
<span id="returns"></span>
* '''value...''' (<code>any</code>): values to print
=== Returns ===


'''Returns:''' <code>bool</code>
* '''value''' (<code>bool</code>)


== env ==
== env ==
Line 22: Line 34:
'''Allowed number of parameters:''' 1–2
'''Allowed number of parameters:''' 1–2


'''Parameters:'''
<span id="parameters-1"></span>
=== Parameters ===
 
* '''var''' (<code>string</code>): envvar
* '''var''' (<code>string</code>): envvar
* '''default''' (<code>string</code>): default if the env is not found
* '''default''' (<code>string</code>): default if the env is not found ''(optional)''
 
<span id="returns-1"></span>
=== Returns ===


'''Returns:''' <code>string</code>
* '''value''' (<code>string</code>)


== help ==
== help ==


Lists all functions or prints help for a specific function
Lists all functions or returns help for a specific function as a string


'''Allowed number of parameters:''' 0–1
'''Allowed number of parameters:''' 0–1


'''Parameters:'''
<span id="parameters-2"></span>
* '''topic''' (<code>string</code>): function to print help about
=== Parameters ===
 
* '''topic''' (<code>string</code>): function to get help about ''(optional)''


'''Returns:''' <code>nil</code>
<span id="returns-2"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)


== import ==
== import ==


Imports a .scm file into current namespace
Imports a file .scm file into current namespace


'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-3"></span>
* '''filename''' (<code>string</code>): filename relative to folder of source file
=== Parameters ===


'''Returns:''' <code>any</code>
* '''filename''' (<code>string</code>): filename relative to folder of source file or absolute path
 
<span id="returns-3"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== load ==
== load ==
Line 56: Line 83:
'''Allowed number of parameters:''' 1–3
'''Allowed number of parameters:''' 1–3


'''Parameters:'''
<span id="parameters-4"></span>
* '''filenameOrStream''' (<code>string|stream</code>): filename or stream
=== Parameters ===
* '''linehandler''' (<code>func</code>): handler for each line
 
* '''delimiter''' (<code>string</code>): delimiter for line extraction
* '''filenameOrStream''' (<code>string|stream</code>): filename relative to folder of source file, absolute path, or stream to read from
* '''linehandler''' (<code>func</code>): handler that reads each line; each line may end with delimiter ''(optional)''
** '''Parameters'''
*** '''line''' (<code>string</code>)
** '''Returns'''
*** '''value''' (<code>any</code>)
* '''delimiter''' (<code>string</code>): delimiter to extract; if no delimiter is given, the file is read as whole and returned or passed to linehandler ''(optional)''


'''Returns:''' <code>string|bool</code>
<span id="returns-4"></span>
=== Returns ===
 
* '''value''' (<code>string|bool</code>)


== stream ==
== stream ==
Line 69: Line 105:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-5"></span>
* '''filename''' (<code>string</code>): filename
=== Parameters ===


'''Returns:''' <code>stream</code>
* '''filename''' (<code>string</code>): filename relative to folder of source file or absolute path
 
<span id="returns-5"></span>
=== Returns ===
 
* '''value''' (<code>stream</code>)


== watch ==
== watch ==


Loads a file and calls a callback whenever the file changes
Loads a file and calls the callback. Whenever the file changes on disk, the file is load again.


'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-6"></span>
* '''filename''' (<code>string</code>): filename
=== Parameters ===
* '''updatehandler''' (<code>func</code>): handler that receives content
 
* '''filename''' (<code>string</code>): filename relative to folder of source file or absolute path
* '''updatehandler''' (<code>func</code>): handler that receives the file content whenever it changes
** '''Parameters'''
*** '''content''' (<code>string</code>): new file content
** '''Returns'''
*** '''result''' (<code>any</code>): ignored handler result
 
<span id="returns-6"></span>
=== Returns ===


'''Returns:''' <code>bool</code>
* '''value''' (<code>bool</code>)


== serve ==
== serve ==
Line 92: Line 142:
'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-7"></span>
* '''port''' (<code>number</code>): port number
=== Parameters ===
* '''handler''' (<code>func</code>): lambda(req res)
 
* '''port''' (<code>number</code>): port number for HTTP server
* '''handler''' (<code>func</code>): handler that processes each HTTP request
** '''Parameters'''
*** '''req''' (<code>any</code>): HTTP request object
*** '''res''' (<code>any</code>): HTTP response object
** '''Returns'''
*** '''result''' (<code>any</code>): handler result
 
<span id="returns-7"></span>
=== Returns ===


'''Returns:''' <code>bool</code>
* '''value''' (<code>bool</code>)


<span id="servestatic"></span>
== serveStatic ==
== serveStatic ==


Creates a static handler for use in (serve)
creates a static-file HTTP handler for use with serve


'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-8"></span>
* '''directory''' (<code>string</code>): folder with files
=== Parameters ===
 
* '''directory''' (<code>string</code>): folder with the files to serve
 
<span id="returns-8"></span>
=== Returns ===


'''Returns:''' <code>func</code>
* '''handler''' (<code>func</code>): HTTP handler that serves files from the configured directory
** '''Parameters'''
*** '''req''' (<code>any</code>): HTTP request object
*** '''res''' (<code>any</code>): HTTP response object
** '''Returns'''
*** '''result''' (<code>any</code>): handler result


== mysql ==
== mysql ==


Opens a MySQL server with custom handlers
Imports a file .scm file into current namespace


'''Allowed number of parameters:''' 4–4
'''Allowed number of parameters:''' 4–4


'''Parameters:'''
<span id="parameters-9"></span>
* '''port''' (<code>number</code>): port
=== Parameters ===
* '''getPassword''' (<code>func</code>): password resolver
 
* '''schemacallback''' (<code>func</code>): schema access checker
* '''port''' (<code>number</code>): port number for MySQL server
* '''handler''' (<code>func</code>): SQL handler
* '''getPassword''' (<code>func</code>): returns the password for a user, or nil to deny login
** '''Parameters'''
*** '''username''' (<code>string</code>): user attempting to log in
** '''Returns'''
*** '''password''' (<code>string|nil</code>): password used for authentication, or nil to deny login
* '''schemacallback''' (<code>func</code>): checks whether a user may access a schema
** '''Parameters'''
*** '''username''' (<code>string</code>): authenticated user
*** '''schema''' (<code>string</code>): requested schema
** '''Returns'''
*** '''allowed''' (<code>bool</code>): whether access is allowed
* '''handler''' (<code>func</code>): processes one SQL query in a schema
** '''Parameters'''
*** '''schema''' (<code>string</code>)
*** '''sql''' (<code>string</code>)
*** '''resultrow''' (<code>func</code>): emits one result row
**** '''Parameters'''
***** '''row''' (<code>list&lt;any&gt;</code>)
****** '''column value''' (<code>any</code>)
**** '''Returns'''
***** '''result''' (<code>any</code>)
*** '''session''' (<code>func</code>): reads or updates request-local values
**** '''Parameters'''
***** '''key''' (<code>any</code>) ''(optional)''
***** '''value''' (<code>any</code>) ''(optional)''
**** '''Returns'''
***** '''stored value''' (<code>any</code>)
** '''Returns'''
*** '''value''' (<code>any</code>)
 
<span id="returns-9"></span>
=== Returns ===


'''Returns:''' <code>bool</code>
* '''value''' (<code>bool</code>)
 
== mysql_socket ==
 
Listen on a Unix domain socket for MySQL protocol
 
'''Allowed number of parameters:''' 4–4
 
<span id="parameters-10"></span>
=== Parameters ===
 
* '''socketpath''' (<code>string</code>): path to the Unix domain socket
* '''getPassword''' (<code>func</code>): returns the password for a user, or nil to deny login
** '''Parameters'''
*** '''username''' (<code>string</code>): user attempting to log in
** '''Returns'''
*** '''password''' (<code>string|nil</code>): password used for authentication, or nil to deny login
* '''schemacallback''' (<code>func</code>): checks whether a user may access a schema
** '''Parameters'''
*** '''username''' (<code>string</code>): authenticated user
*** '''schema''' (<code>string</code>): requested schema
** '''Returns'''
*** '''allowed''' (<code>bool</code>): whether access is allowed
* '''handler''' (<code>func</code>): processes one SQL query in a schema
** '''Parameters'''
*** '''schema''' (<code>string</code>)
*** '''sql''' (<code>string</code>)
*** '''resultrow''' (<code>func</code>): emits one result row
**** '''Parameters'''
***** '''row''' (<code>list&lt;any&gt;</code>)
****** '''column value''' (<code>any</code>)
**** '''Returns'''
***** '''result''' (<code>any</code>)
*** '''session''' (<code>func</code>): reads or updates request-local values
**** '''Parameters'''
***** '''key''' (<code>any</code>) ''(optional)''
***** '''value''' (<code>any</code>) ''(optional)''
**** '''Returns'''
***** '''stored value''' (<code>any</code>)
** '''Returns'''
*** '''value''' (<code>any</code>)
 
<span id="returns-10"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)


== password ==
== password ==


Hashes a password with sha1
Hashes a password with sha1 (for mysql user authentication)


'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-11"></span>
* '''password''' (<code>string</code>): plain text password
=== Parameters ===


'''Returns:''' <code>string</code>
* '''password''' (<code>string</code>): plain text password to hash
 
<span id="returns-11"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)
 
== shutdown ==
 
Initiates a graceful shutdown of memcp after a short delay
 
'''Allowed number of parameters:''' 0–0
 
<span id="parameters-12"></span>
=== Parameters ===
 
''This function has no parameters.''
 
<span id="returns-12"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)
 
== crash ==
 
Hard process exit with no cleanup (kill -9 equivalent) for crash testing. SCM only, not exposed to SQL.
 
'''Allowed number of parameters:''' 0–0
 
<span id="parameters-13"></span>
=== Parameters ===
 
''This function has no parameters.''
 
<span id="returns-13"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)
 
== path ==
 
Joins path segments using the OS path separator and cleans the result
 
'''Allowed number of parameters:''' 0–10000
 
<span id="parameters-14"></span>
=== Parameters ===
 
* '''segments''' (<code>string</code>): path segments to join ''(variadic)''
 
<span id="returns-14"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)


== args ==
== args ==
Line 140: Line 340:
'''Allowed number of parameters:''' 0–0
'''Allowed number of parameters:''' 0–0


'''Parameters:''' _none_
<span id="parameters-15"></span>
=== Parameters ===


'''Returns:''' <code>list</code>
''This function has no parameters.''
 
<span id="returns-15"></span>
=== Returns ===
 
* '''value''' (<code>list</code>)


== arg ==
== arg ==
Line 150: Line 356:
'''Allowed number of parameters:''' 2–3
'''Allowed number of parameters:''' 2–3


'''Parameters:'''
<span id="parameters-16"></span>
* '''longname''' (<code>string</code>): long argument name
=== Parameters ===
* '''shortname''' (<code>string</code>): short argument or default
 
* '''default''' (<code>any</code>): fallback value
* '''longname''' (<code>string</code>): long argument name (without --)
* '''shortname''' (<code>string|any</code>): short argument name (without -) or default value if only 2 args
* '''default''' (<code>any</code>): default value if argument not found ''(optional)''
 
<span id="returns-16"></span>
=== Returns ===


'''Returns:''' <code>any</code>
* '''value''' (<code>any</code>)

Latest revision as of 11:59, 28 August 2026


IO

Generated from MemCP commit c42e19eba on 27 August 2026. See Full SCM API documentation.

The IO module provides process-facing input and output facilities for Scheme programs and embedded services. It includes console output, environment access, files and streams, HTTP helpers, serialization, argument handling, and server-control functions.

IO functions are intentionally effectful. Treat filenames, URLs, environment values, request data, and generated output as trust boundaries; restrict administrative handlers and do not expose arbitrary IO primitives to untrusted users.

print

Prints values to stdout (only in IO environment)

Allowed number of parameters: 0–10000

Parameters

  • value... (any): values to print (variadic)

Returns

  • value (bool)

env

returns the content of a environment variable

Allowed number of parameters: 1–2

Parameters

  • var (string): envvar
  • default (string): default if the env is not found (optional)

Returns

  • value (string)

help

Lists all functions or returns help for a specific function as a string

Allowed number of parameters: 0–1

Parameters

  • topic (string): function to get help about (optional)

Returns

  • value (string)

import

Imports a file .scm file into current namespace

Allowed number of parameters: 1–1

Parameters

  • filename (string): filename relative to folder of source file or absolute path

Returns

  • value (any)

load

Loads a file or stream and returns the string or iterates line-wise

Allowed number of parameters: 1–3

Parameters

  • filenameOrStream (string|stream): filename relative to folder of source file, absolute path, or stream to read from
  • linehandler (func): handler that reads each line; each line may end with delimiter (optional)
    • Parameters
      • line (string)
    • Returns
      • value (any)
  • delimiter (string): delimiter to extract; if no delimiter is given, the file is read as whole and returned or passed to linehandler (optional)

Returns

  • value (string|bool)

stream

Opens a file readonly as stream

Allowed number of parameters: 1–1

Parameters

  • filename (string): filename relative to folder of source file or absolute path

Returns

  • value (stream)

watch

Loads a file and calls the callback. Whenever the file changes on disk, the file is load again.

Allowed number of parameters: 2–2

Parameters

  • filename (string): filename relative to folder of source file or absolute path
  • updatehandler (func): handler that receives the file content whenever it changes
    • Parameters
      • content (string): new file content
    • Returns
      • result (any): ignored handler result

Returns

  • value (bool)

serve

Opens a HTTP server at a given port

Allowed number of parameters: 2–2

Parameters

  • port (number): port number for HTTP server
  • handler (func): handler that processes each HTTP request
    • Parameters
      • req (any): HTTP request object
      • res (any): HTTP response object
    • Returns
      • result (any): handler result

Returns

  • value (bool)

serveStatic

creates a static-file HTTP handler for use with serve

Allowed number of parameters: 1–1

Parameters

  • directory (string): folder with the files to serve

Returns

  • handler (func): HTTP handler that serves files from the configured directory
    • Parameters
      • req (any): HTTP request object
      • res (any): HTTP response object
    • Returns
      • result (any): handler result

mysql

Imports a file .scm file into current namespace

Allowed number of parameters: 4–4

Parameters

  • port (number): port number for MySQL server
  • getPassword (func): returns the password for a user, or nil to deny login
    • Parameters
      • username (string): user attempting to log in
    • Returns
      • password (string|nil): password used for authentication, or nil to deny login
  • schemacallback (func): checks whether a user may access a schema
    • Parameters
      • username (string): authenticated user
      • schema (string): requested schema
    • Returns
      • allowed (bool): whether access is allowed
  • handler (func): processes one SQL query in a schema
    • Parameters
      • schema (string)
      • sql (string)
      • resultrow (func): emits one result row
        • Parameters
          • row (list<any>)
            • column value (any)
        • Returns
          • result (any)
      • session (func): reads or updates request-local values
        • Parameters
          • key (any) (optional)
          • value (any) (optional)
        • Returns
          • stored value (any)
    • Returns
      • value (any)

Returns

  • value (bool)

mysql_socket

Listen on a Unix domain socket for MySQL protocol

Allowed number of parameters: 4–4

Parameters

  • socketpath (string): path to the Unix domain socket
  • getPassword (func): returns the password for a user, or nil to deny login
    • Parameters
      • username (string): user attempting to log in
    • Returns
      • password (string|nil): password used for authentication, or nil to deny login
  • schemacallback (func): checks whether a user may access a schema
    • Parameters
      • username (string): authenticated user
      • schema (string): requested schema
    • Returns
      • allowed (bool): whether access is allowed
  • handler (func): processes one SQL query in a schema
    • Parameters
      • schema (string)
      • sql (string)
      • resultrow (func): emits one result row
        • Parameters
          • row (list<any>)
            • column value (any)
        • Returns
          • result (any)
      • session (func): reads or updates request-local values
        • Parameters
          • key (any) (optional)
          • value (any) (optional)
        • Returns
          • stored value (any)
    • Returns
      • value (any)

Returns

  • value (bool)

password

Hashes a password with sha1 (for mysql user authentication)

Allowed number of parameters: 1–1

Parameters

  • password (string): plain text password to hash

Returns

  • value (string)

shutdown

Initiates a graceful shutdown of memcp after a short delay

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • value (bool)

crash

Hard process exit with no cleanup (kill -9 equivalent) for crash testing. SCM only, not exposed to SQL.

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • value (bool)

path

Joins path segments using the OS path separator and cleans the result

Allowed number of parameters: 0–10000

Parameters

  • segments (string): path segments to join (variadic)

Returns

  • value (string)

args

Returns command line arguments

Allowed number of parameters: 0–0

Parameters

This function has no parameters.

Returns

  • value (list)

arg

Gets a command line argument value

Allowed number of parameters: 2–3

Parameters

  • longname (string): long argument name (without --)
  • shortname (string|any): short argument name (without -) or default value if only 2 args
  • default (any): default value if argument not found (optional)

Returns

  • value (any)
Retrieved from "https://www.memcp.org/index.php?title=IO&oldid=333"