IO: Difference between revisions

From MemCP
Jump to navigation Jump to search
No edit summary
(Refresh MemCP documentation: accuracy, operational guidance, performance profile and maintained API reference)
 
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 19: Line 26:
=== Returns ===
=== Returns ===


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


== env ==
== env ==
Line 36: Line 43:
=== Returns ===
=== Returns ===


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


== help ==
== help ==
Line 52: Line 59:
=== Returns ===
=== Returns ===


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


== import ==
== import ==
Line 68: Line 75:
=== Returns ===
=== Returns ===


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


== load ==
== load ==
Line 80: Line 87:


* '''filenameOrStream''' (<code>string|stream</code>): filename relative to folder of source file, absolute path, or stream to read from
* '''filenameOrStream''' (<code>string|stream</code>): filename relative to folder of source file, absolute path, or stream to read from
* '''linehandler''' (<code>func(line:string) -&gt; any</code>): handler that reads each line; each line may end with delimiter ''(optional)''
* '''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)''
* '''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)''


Line 86: Line 97:
=== Returns ===
=== Returns ===


<code>string|bool</code>
* '''value''' (<code>string|bool</code>)


== stream ==
== stream ==
Line 102: Line 113:
=== Returns ===
=== Returns ===


<code>stream</code>
* '''value''' (<code>stream</code>)


== watch ==
== watch ==
Line 114: Line 125:


* '''filename''' (<code>string</code>): filename relative to folder of source file or absolute path
* '''filename''' (<code>string</code>): filename relative to folder of source file or absolute path
* '''updatehandler''' (<code>func(content:string) -&gt; any</code>): handler that receives the file content func(content)
* '''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>
<span id="returns-6"></span>
=== Returns ===
=== Returns ===


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


== serve ==
== serve ==
Line 131: Line 146:


* '''port''' (<code>number</code>): port number for HTTP server
* '''port''' (<code>number</code>): port number for HTTP server
* '''handler''' (<code>func(req:any, res:any) -&gt; any</code>): handler: lambda(req res) that handles the http request
* '''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>
<span id="returns-7"></span>
=== Returns ===
=== Returns ===


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


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


creates a static handler for use as a callback in (serve) - returns a handler lambda(req res)
creates a static-file HTTP handler for use with serve


'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1
Line 153: Line 173:
=== Returns ===
=== Returns ===


<code>func(req:any, res:any) -&gt; any</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 ==
Line 165: Line 190:


* '''port''' (<code>number</code>): port number for MySQL server
* '''port''' (<code>number</code>): port number for MySQL server
* '''getPassword''' (<code>func(username:string) -&gt; string|nil</code>): lambda(username string) string|nil has to return the password for a user or nil to deny login
* '''getPassword''' (<code>func</code>): returns the password for a user, or nil to deny login
* '''schemacallback''' (<code>func(username:string, schema:string) -&gt; bool</code>): lambda(username schema) bool handler check whether user is allowed to schema - you should check access rights here
** '''Parameters'''
* '''handler''' (<code>func(schema:string, sql:string, resultrow:func, session:func) -&gt; any</code>): lambda(schema sql resultrow session) handler to process sql query in schema. resultrow is a lambda(list)
*** '''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>
<span id="returns-9"></span>
=== Returns ===
=== Returns ===


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


== mysql_socket ==
== mysql_socket ==
Line 184: Line 235:


* '''socketpath''' (<code>string</code>): path to the Unix domain socket
* '''socketpath''' (<code>string</code>): path to the Unix domain socket
* '''getPassword''' (<code>func(username:string) -&gt; string|nil</code>): lambda(username string) string|nil has to return the password for a user or nil to deny login
* '''getPassword''' (<code>func</code>): returns the password for a user, or nil to deny login
* '''schemacallback''' (<code>func(username:string, schema:string) -&gt; bool</code>): lambda(username schema) bool handler check whether user is allowed to schema - you should check access rights here
** '''Parameters'''
* '''handler''' (<code>func(schema:string, sql:string, resultrow:func, session:func) -&gt; any</code>): lambda(schema sql resultrow session) handler to process sql query in schema. resultrow is a lambda(list)
*** '''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>
<span id="returns-10"></span>
=== Returns ===
=== Returns ===


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


== password ==
== password ==
Line 207: Line 284:
=== Returns ===
=== Returns ===


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


== shutdown ==
== shutdown ==
Line 223: Line 300:
=== Returns ===
=== Returns ===


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


== crash ==
== crash ==
Line 239: Line 316:
=== Returns ===
=== Returns ===


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


== path ==
== path ==
Line 255: Line 332:
=== Returns ===
=== Returns ===


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


== args ==
== args ==
Line 271: Line 348:
=== Returns ===
=== Returns ===


<code>list</code>
* '''value''' (<code>list</code>)


== arg ==
== arg ==
Line 289: Line 366:
=== 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"