2026-01-25 03:58:39 +00:00
<!DOCTYPE html>
<!-- retoor <retoor@molodetz.nl> -->
< html lang = "en" >
< head >
< meta charset = "UTF-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< title > tempfile - Wren-CLI Manual</ title >
< link rel = "stylesheet" href = "../css/style.css" >
</ head >
< body >
< button class = "mobile-menu-toggle" > Menu</ button >
< div class = "container" >
< aside class = "sidebar" >
< div class = "sidebar-header" >
< h1 >< a href = "../index.html" > Wren-CLI</ a ></ h1 >
< div class = "version" > v0.4.0</ div >
</ div >
< nav class = "sidebar-nav" >
< div class = "section" >
< span class = "section-title" > Getting Started</ span >
< ul >
< li >< a href = "../getting-started/index.html" > Overview</ a ></ li >
< li >< a href = "../getting-started/installation.html" > Installation</ a ></ li >
< li >< a href = "../getting-started/first-script.html" > First Script</ a ></ li >
< li >< a href = "../getting-started/repl.html" > Using the REPL</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > Language</ span >
< ul >
< li >< a href = "../language/index.html" > Syntax Overview</ a ></ li >
< li >< a href = "../language/classes.html" > Classes</ a ></ li >
< li >< a href = "../language/methods.html" > Methods</ a ></ li >
< li >< a href = "../language/control-flow.html" > Control Flow</ a ></ li >
< li >< a href = "../language/fibers.html" > Fibers</ a ></ li >
< li >< a href = "../language/modules.html" > Modules</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > API Reference</ span >
< ul >
< li >< a href = "index.html" > Overview</ a ></ li >
< li >< a href = "string.html" > String</ a ></ li >
< li >< a href = "number.html" > Num</ a ></ li >
< li >< a href = "argparse.html" > argparse</ a ></ li >
2026-01-25 12:09:28 +00:00
< li >< a href = "base64.html" > base64</ a ></ li >
< li >< a href = "crypto.html" > crypto</ a ></ li >
2026-01-25 03:58:39 +00:00
< li >< a href = "dataset.html" > dataset</ a ></ li >
2026-01-25 12:09:28 +00:00
< li >< a href = "datetime.html" > datetime</ a ></ li >
< li >< a href = "dns.html" > dns</ a ></ li >
< li >< a href = "env.html" > env</ a ></ li >
< li >< a href = "fswatch.html" > fswatch</ a ></ li >
< li >< a href = "html.html" > html</ a ></ li >
< li >< a href = "http.html" > http</ a ></ li >
< li >< a href = "io.html" > io</ a ></ li >
< li >< a href = "jinja.html" > jinja</ a ></ li >
< li >< a href = "json.html" > json</ a ></ li >
2026-01-25 03:58:39 +00:00
< li >< a href = "markdown.html" > markdown</ a ></ li >
2026-01-25 12:09:28 +00:00
< li >< a href = "math.html" > math</ a ></ li >
< li >< a href = "net.html" > net</ a ></ li >
< li >< a href = "os.html" > os</ a ></ li >
< li >< a href = "pathlib.html" > pathlib</ a ></ li >
< li >< a href = "regex.html" > regex</ a ></ li >
< li >< a href = "scheduler.html" > scheduler</ a ></ li >
< li >< a href = "signal.html" > signal</ a ></ li >
< li >< a href = "sqlite.html" > sqlite</ a ></ li >
< li >< a href = "subprocess.html" > subprocess</ a ></ li >
< li >< a href = "sysinfo.html" > sysinfo</ a ></ li >
< li >< a href = "tempfile.html" class = "active" > tempfile</ a ></ li >
< li >< a href = "timer.html" > timer</ a ></ li >
< li >< a href = "tls.html" > tls</ a ></ li >
< li >< a href = "udp.html" > udp</ a ></ li >
< li >< a href = "uuid.html" > uuid</ a ></ li >
< li >< a href = "wdantic.html" > wdantic</ a ></ li >
2026-01-25 03:58:39 +00:00
< li >< a href = "web.html" > web</ a ></ li >
2026-01-25 12:09:28 +00:00
< li >< a href = "websocket.html" > websocket</ a ></ li >
2026-01-25 03:58:39 +00:00
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > Tutorials</ span >
< ul >
< li >< a href = "../tutorials/index.html" > Tutorial List</ a ></ li >
2026-01-25 12:09:28 +00:00
< li >< a href = "../tutorials/http-client.html" > HTTP Client</ a ></ li >
< li >< a href = "../tutorials/websocket-chat.html" > WebSocket Chat</ a ></ li >
< li >< a href = "../tutorials/database-app.html" > Database App</ a ></ li >
< li >< a href = "../tutorials/template-rendering.html" > Templates</ a ></ li >
< li >< a href = "../tutorials/cli-tool.html" > CLI Tool</ a ></ li >
2026-01-25 18:02:02 +00:00
< li >< a href = "../tutorials/web-server.html" > Web Server</ a ></ li >
2026-01-25 03:58:39 +00:00
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > How-To Guides</ span >
< ul >
< li >< a href = "../howto/index.html" > How-To List</ a ></ li >
2026-01-25 12:09:28 +00:00
< li >< a href = "../howto/http-requests.html" > HTTP Requests</ a ></ li >
< li >< a href = "../howto/json-parsing.html" > JSON Parsing</ a ></ li >
< li >< a href = "../howto/regex-patterns.html" > Regex Patterns</ a ></ li >
< li >< a href = "../howto/file-operations.html" > File Operations</ a ></ li >
< li >< a href = "../howto/async-operations.html" > Async Operations</ a ></ li >
< li >< a href = "../howto/error-handling.html" > Error Handling</ a ></ li >
2026-01-25 03:58:39 +00:00
</ ul >
</ div >
2026-01-25 18:02:02 +00:00
< div class = "section" >
< span class = "section-title" > Contributing</ span >
< ul >
< li >< a href = "../contributing/index.html" > Overview</ a ></ li >
< li >< a href = "../contributing/module-overview.html" > Module Architecture</ a ></ li >
< li >< a href = "../contributing/pure-wren-module.html" > Pure-Wren Modules</ a ></ li >
< li >< a href = "../contributing/c-backed-module.html" > C-Backed Modules</ a ></ li >
< li >< a href = "../contributing/foreign-classes.html" > Foreign Classes</ a ></ li >
< li >< a href = "../contributing/async-patterns.html" > Async Patterns</ a ></ li >
< li >< a href = "../contributing/testing.html" > Writing Tests</ a ></ li >
< li >< a href = "../contributing/documentation.html" > Documentation</ a ></ li >
</ ul >
</ div >
2026-01-25 03:58:39 +00:00
</ nav >
</ aside >
< main class = "content" >
< nav class = "breadcrumb" >
< a href = "../index.html" > Home</ a >
< span class = "separator" > /</ span >
< a href = "index.html" > API Reference</ a >
< span class = "separator" > /</ span >
< span > tempfile</ span >
</ nav >
< article >
< h1 > tempfile</ h1 >
< p > The < code > tempfile</ code > module provides utilities for creating temporary files and directories. It mirrors Python's < code > tempfile</ code > API with three classes: < code > TempFile</ code > for low-level operations, < code > NamedTemporaryFile</ code > for temporary files with automatic cleanup, and < code > TemporaryDirectory</ code > for temporary directories with recursive cleanup.</ p >
< pre >< code > import "tempfile" for TempFile, NamedTemporaryFile, TemporaryDirectory</ code ></ pre >
< h2 > TempFile Class</ h2 >
< div class = "class-header" >
< h3 > TempFile</ h3 >
< p > Low-level temporary file and directory utilities</ p >
</ div >
< h3 > Static Properties</ h3 >
< div class = "method-signature" >
< span class = "method-name" > TempFile.tempdir</ span > → < span class = "type" > String|Null</ span >
</ div >
< p > Gets or sets a global override for the temporary directory. When set, < code > gettempdir()</ code > returns this value instead of checking environment variables.</ p >
< pre >< code > TempFile.tempdir = "/my/custom/tmp"
System.print(TempFile.gettempdir()) // /my/custom/tmp
TempFile.tempdir = null // Reset to default</ code ></ pre >
< h3 > Static Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > TempFile.gettempdir</ span > () → < span class = "type" > String</ span >
</ div >
< p > Returns the resolved temporary directory path. Checks in order: the < code > tempdir</ code > override, then < code > TMPDIR</ code > , < code > TEMP</ code > , < code > TMP</ code > environment variables, and falls back to < code > /tmp</ code > on POSIX or < code > C:\Temp</ code > on Windows.</ p >
< div class = "method-signature" >
< span class = "method-name" > TempFile.gettempprefix</ span > () → < span class = "type" > String</ span >
</ div >
< p > Returns the default prefix for temporary file names: < code > "tmp"</ code > .</ p >
< div class = "method-signature" >
< span class = "method-name" > TempFile.mktemp</ span > () → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mktemp</ span > (< span class = "param" > suffix</ span > ) → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mktemp</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > ) → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mktemp</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Generates a unique temporary file path without creating any file. The generated name consists of the prefix, 8 random hexadecimal characters, and the suffix.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > suffix</ span > < span class = "param-type" > (String)</ span > - Suffix for the filename (default: < code > ""</ code > )</ li >
< li >< span class = "param-name" > prefix</ span > < span class = "param-type" > (String)</ span > - Prefix for the filename (default: < code > "tmp"</ code > )</ li >
< li >< span class = "param-name" > dir</ span > < span class = "param-type" > (String)</ span > - Directory for the path (default: < code > gettempdir()</ code > )</ li >
< li >< span class = "returns" > Returns:</ span > A file path string (file is not created)</ li >
</ ul >
< pre >< code > var name = TempFile.mktemp(".txt", "data_")
System.print(name) // e.g., /tmp/data_a1b2c3d4.txt</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > TempFile.mkstemp</ span > () → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mkstemp</ span > (< span class = "param" > suffix</ span > ) → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mkstemp</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > ) → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mkstemp</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Creates a temporary file atomically using exclusive creation flags (< code > O_EXCL</ code > ), preventing race conditions. Retries up to 100 times on name collisions.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > suffix</ span > < span class = "param-type" > (String)</ span > - Suffix for the filename (default: < code > ""</ code > )</ li >
< li >< span class = "param-name" > prefix</ span > < span class = "param-type" > (String)</ span > - Prefix for the filename (default: < code > "tmp"</ code > )</ li >
< li >< span class = "param-name" > dir</ span > < span class = "param-type" > (String)</ span > - Directory for the file (default: < code > gettempdir()</ code > )</ li >
< li >< span class = "returns" > Returns:</ span > The path of the newly created file</ li >
</ ul >
< pre >< code > import "io" for File
var path = TempFile.mkstemp(".dat", "work_")
System.print(path) // e.g., /tmp/work_e5f6a7b8.dat
File.delete(path) // Caller must clean up</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > TempFile.mkdtemp</ span > () → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mkdtemp</ span > (< span class = "param" > suffix</ span > ) → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mkdtemp</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > ) → < span class = "type" > String</ span >< br >
< span class = "method-name" > TempFile.mkdtemp</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > ) → < span class = "type" > String</ span >
</ div >
< p > Creates a temporary directory. Retries up to 100 times on name collisions.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > suffix</ span > < span class = "param-type" > (String)</ span > - Suffix for the directory name (default: < code > ""</ code > )</ li >
< li >< span class = "param-name" > prefix</ span > < span class = "param-type" > (String)</ span > - Prefix for the directory name (default: < code > "tmp"</ code > )</ li >
< li >< span class = "param-name" > dir</ span > < span class = "param-type" > (String)</ span > - Parent directory (default: < code > gettempdir()</ code > )</ li >
< li >< span class = "returns" > Returns:</ span > The path of the newly created directory</ li >
</ ul >
< pre >< code > import "io" for Directory
var dir = TempFile.mkdtemp("_work")
System.print(dir) // e.g., /tmp/tmp9c0d1e2f_work
Directory.delete(dir) // Caller must clean up</ code ></ pre >
< h2 > NamedTemporaryFile Class</ h2 >
< div class = "class-header" >
< h3 > NamedTemporaryFile</ h3 >
< p > A temporary file with a visible name that is optionally deleted on close</ p >
</ div >
< h3 > Constructors</ h3 >
< div class = "method-signature" >
< span class = "method-name" > NamedTemporaryFile.new</ span > () → < span class = "type" > NamedTemporaryFile</ span >< br >
< span class = "method-name" > NamedTemporaryFile.new</ span > (< span class = "param" > suffix</ span > ) → < span class = "type" > NamedTemporaryFile</ span >< br >
< span class = "method-name" > NamedTemporaryFile.new</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > ) → < span class = "type" > NamedTemporaryFile</ span >< br >
< span class = "method-name" > NamedTemporaryFile.new</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > ) → < span class = "type" > NamedTemporaryFile</ span >< br >
< span class = "method-name" > NamedTemporaryFile.new</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > , < span class = "param" > delete</ span > ) → < span class = "type" > NamedTemporaryFile</ span >
</ div >
< ul class = "param-list" >
< li >< span class = "param-name" > suffix</ span > < span class = "param-type" > (String)</ span > - Suffix for the filename (default: < code > ""</ code > )</ li >
< li >< span class = "param-name" > prefix</ span > < span class = "param-type" > (String)</ span > - Prefix for the filename (default: < code > "tmp"</ code > )</ li >
< li >< span class = "param-name" > dir</ span > < span class = "param-type" > (String|Null)</ span > - Directory for the file (default: < code > null</ code > , uses < code > TempFile.gettempdir()</ code > )</ li >
< li >< span class = "param-name" > delete</ span > < span class = "param-type" > (Bool)</ span > - Whether to delete the file on close (default: < code > true</ code > )</ li >
</ ul >
< h3 > Properties</ h3 >
< div class = "method-signature" >
< span class = "method-name" > .name</ span > → < span class = "type" > String</ span >
</ div >
< p > The full path of the temporary file.</ p >
< div class = "method-signature" >
< span class = "method-name" > .path</ span > → < span class = "type" > Path</ span >
</ div >
< p > A < code > Path</ code > object for the temporary file.</ p >
< div class = "method-signature" >
< span class = "method-name" > .delete</ span > → < span class = "type" > Bool</ span >
</ div >
< p > Whether the file will be deleted on close. Can be set.</ p >
< div class = "method-signature" >
< span class = "method-name" > .closed</ span > → < span class = "type" > Bool</ span >
</ div >
< p > Whether the file has been closed.</ p >
< h3 > Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > .write</ span > (< span class = "param" > content</ span > )
</ div >
< p > Writes string content to the file, replacing any existing content.</ p >
< div class = "method-signature" >
< span class = "method-name" > .read</ span > () → < span class = "type" > String</ span >
</ div >
< p > Reads and returns the file content as a string.</ p >
< div class = "method-signature" >
< span class = "method-name" > .close</ span > ()
</ div >
< p > Closes the file. If < code > delete</ code > is < code > true</ code > , the file is deleted from disk.</ p >
< div class = "method-signature" >
< span class = "method-name" > .use</ span > (< span class = "param" > fn</ span > ) → < span class = "type" > *</ span >
</ div >
< p > Executes < code > fn</ code > with the file as argument and guarantees cleanup afterwards, even if an error occurs. Equivalent to Python's < code > with</ code > statement.</ p >
< pre >< code > NamedTemporaryFile.new(".txt").use {|f|
f.write("temporary data")
System.print(f.read())
}
// File is automatically deleted here</ code ></ pre >
< h2 > TemporaryDirectory Class</ h2 >
< div class = "class-header" >
< h3 > TemporaryDirectory</ h3 >
< p > A temporary directory with recursive cleanup support</ p >
</ div >
< h3 > Constructors</ h3 >
< div class = "method-signature" >
< span class = "method-name" > TemporaryDirectory.new</ span > () → < span class = "type" > TemporaryDirectory</ span >< br >
< span class = "method-name" > TemporaryDirectory.new</ span > (< span class = "param" > suffix</ span > ) → < span class = "type" > TemporaryDirectory</ span >< br >
< span class = "method-name" > TemporaryDirectory.new</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > ) → < span class = "type" > TemporaryDirectory</ span >< br >
< span class = "method-name" > TemporaryDirectory.new</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > ) → < span class = "type" > TemporaryDirectory</ span >< br >
< span class = "method-name" > TemporaryDirectory.new</ span > (< span class = "param" > suffix</ span > , < span class = "param" > prefix</ span > , < span class = "param" > dir</ span > , < span class = "param" > delete</ span > ) → < span class = "type" > TemporaryDirectory</ span >
</ div >
< ul class = "param-list" >
< li >< span class = "param-name" > suffix</ span > < span class = "param-type" > (String)</ span > - Suffix for the directory name (default: < code > ""</ code > )</ li >
< li >< span class = "param-name" > prefix</ span > < span class = "param-type" > (String)</ span > - Prefix for the directory name (default: < code > "tmp"</ code > )</ li >
< li >< span class = "param-name" > dir</ span > < span class = "param-type" > (String|Null)</ span > - Parent directory (default: < code > null</ code > , uses < code > TempFile.gettempdir()</ code > )</ li >
< li >< span class = "param-name" > delete</ span > < span class = "param-type" > (Bool)</ span > - Whether to delete the directory on cleanup (default: < code > true</ code > )</ li >
</ ul >
< h3 > Properties</ h3 >
< div class = "method-signature" >
< span class = "method-name" > .name</ span > → < span class = "type" > String</ span >
</ div >
< p > The full path of the temporary directory.</ p >
< div class = "method-signature" >
< span class = "method-name" > .path</ span > → < span class = "type" > Path</ span >
</ div >
< p > A < code > Path</ code > object for the temporary directory.</ p >
< div class = "method-signature" >
< span class = "method-name" > .delete</ span > → < span class = "type" > Bool</ span >
</ div >
< p > Whether the directory will be deleted on cleanup. Can be set.</ p >
< div class = "method-signature" >
< span class = "method-name" > .closed</ span > → < span class = "type" > Bool</ span >
</ div >
< p > Whether the directory has been cleaned up.</ p >
< h3 > Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > .cleanup</ span > ()
</ div >
< p > Removes the directory and all its contents recursively (using < code > Path.rmtree()</ code > ). If < code > delete</ code > is < code > false</ code > , the directory is not removed.</ p >
< div class = "method-signature" >
< span class = "method-name" > .use</ span > (< span class = "param" > fn</ span > ) → < span class = "type" > *</ span >
</ div >
< p > Executes < code > fn</ code > with the directory as argument and guarantees cleanup afterwards, even if an error occurs.</ p >
< pre >< code > TemporaryDirectory.new().use {|d|
var path = d.name + "/data.txt"
// Create files, do work...
}
// Directory and all contents automatically removed</ code ></ pre >
< h2 > Examples</ h2 >
< h3 > Processing Files Safely</ h3 >
< pre >< code > import "tempfile" for NamedTemporaryFile
import "pathlib" for Path
NamedTemporaryFile.new(".csv", "report_").use {|tmp|
tmp.write("name,value\nalice,42\nbob,17")
var data = tmp.read()
System.print("Processing %(tmp.name)")
System.print(data)
}</ code ></ pre >
< h3 > Working Directory for Build Output</ h3 >
< pre >< code > import "tempfile" for TemporaryDirectory
import "pathlib" for Path
TemporaryDirectory.new("_build").use {|build|
var src = Path.new(build.name) / "output.txt"
src.writeText("Build artifact")
System.print("Build dir: %(build.name)")
}
// Build directory cleaned up automatically</ code ></ pre >
< h3 > Persistent Temporary Files</ h3 >
< pre >< code > import "tempfile" for NamedTemporaryFile
var tmp = NamedTemporaryFile.new(".log", "app_", null, false)
tmp.write("Application started")
tmp.close()
// File persists at tmp.name after close
System.print("Log file: %(tmp.name)")</ code ></ pre >
< div class = "admonition note" >
< div class = "admonition-title" > Note</ div >
< p > File creation via < code > mkstemp</ code > uses exclusive creation flags (< code > O_EXCL</ code > ) for atomic file creation, preventing race conditions between checking for existence and creating the file. Random suffixes are generated using < code > Crypto.randomBytes</ code > for cryptographic quality randomness.</ p >
</ div >
</ article >
< footer class = "page-footer" >
2026-01-25 12:09:28 +00:00
< a href = "sysinfo.html" class = "prev" > sysinfo</ a >
< a href = "timer.html" class = "next" > timer</ a >
2026-01-25 03:58:39 +00:00
</ footer >
</ main >
</ div >
< script src = "../js/main.js" ></ script >
</ body >
</ html >
