File

Inherits from Object

File — File system operations.

Provides file I/O operations and lazy file streaming using Erlang's file module. All operations are class methods. Errors use structured #beamtalk_error{} records.

Examples

File exists: "test.txt"
File readAll: "test.txt"
File writeAll: "output.txt" contents: "hello"
File readBinary: "image.png"
File writeBinary: "output.bin" contents: data
File appendBinary: "log.bin" contents: data
(File lines: "data.csv") do: [:line | Transcript show: line]
File open: "data.csv" do: [:handle | handle lines take: 10]

@see System (for environment variables and OS information) @see Json (for reading/writing JSON files)

Class Methods

exists: path Sealed source

Test if a file exists at the given path (class method).

Examples

File exists: "test.txt"   // => true or false

readAll: path Sealed source

Read the entire contents of a file as a string (class method).

Returns Result ok: contents on success, or Result error: err on failure.

Examples

File readAll: "test.txt"  // => Result ok: "file contents..."

writeAll: path contents: text Sealed source

Write text to a file, creating or overwriting it (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File writeAll: "output.txt" contents: "hello"

readBinary: path Sealed source

Read the entire contents of a file as raw binary (class method).

Returns Result ok: binary on success, or Result error: err on failure. Unlike readAll:, this does not assume the contents are a UTF-8 string.

Examples

File readBinary: "image.png"  // => Result ok: <<...>>

writeBinary: path contents: binary Sealed source

Write binary data to a file, creating or overwriting it (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File writeBinary: "output.bin" contents: data

appendBinary: path contents: binary Sealed source

Append binary data to a file, creating it if needed (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File appendBinary: "log.bin" contents: data

lines: path Sealed source

Return a lazy Stream of lines from a file (class method).

Opens the file and returns Result ok: stream on success, or Result error: err on failure. The Stream reads one line at a time and closes the handle automatically when exhausted. Constant memory — safe for large files.

Cross-process constraint: file-backed Streams must be consumed by the same process that created them.

Examples

(File lines: "data.csv") unwrap take: 5
(File lines: "log.txt") unwrap select: [:l | l includesSubstring: "ERROR"]

open: path do: block Sealed source

Block-scoped file handle with automatic cleanup (class method).

Opens the file, passes a FileHandle to the block, and ensures the handle is closed when the block exits (normally or via exception). Returns Result ok: blockResult on success, or Result error: err on failure.

The handle responds to lines which returns a Stream of lines. Both the handle and any Streams derived from it must be consumed within the block — they must not escape, as the file descriptor is closed when the block returns.

Examples

(File open: "data.csv" do: [:handle |
  handle lines take: 10
]) unwrap

lastModified: path Sealed source

Get the last modification time of a file (class method).

Returns Result ok: DateTime on success, or Result error: err if the file does not exist.

Examples

File lastModified: "test.txt"  // => Result ok: a DateTime(...)

isDirectory: path Sealed source

Test if a path refers to a directory (class method).

Examples

File isDirectory: "target"   // => true or false

isFile: path Sealed source

Test if a path refers to a regular file (class method).

Examples

File isFile: "test.txt"   // => true or false

mkdir: path Sealed source

Create a directory (class method). Error if the parent does not exist.

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File mkdir: "target/mydir"

mkdirAll: path Sealed source

Create a directory and all missing parent directories (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File mkdirAll: "target/a/b/c"

listDirectory: path Sealed source

List entries in a directory as a List of Strings (class method).

Returns Result ok: list on success, or Result error: err on failure.

Examples

File listDirectory: "target"

delete: path Sealed source

Delete a file or empty directory (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File delete: "target/old.txt"

deleteAll: path Sealed source

Recursively delete a directory tree (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File deleteAll: "target/old-workspace"

rename: from to: to Sealed source

Rename or move a file or directory (class method).

Returns Result ok: nil on success, or Result error: err on failure.

Examples

File rename: "old.txt" to: "new.txt"

absolutePath: path Sealed source

Resolve a relative path to its absolute path (class method).

Returns Result ok: absPath on success, or Result error: err on failure.

Examples

File absolutePath: "target/test.txt"

cwd Sealed source

Return the current working directory (class method).

Examples

File cwd   // => "/home/user/projects/myapp"

tempDirectory Sealed source

Return the OS temporary directory path (class method).

Examples

File tempDirectory

Inherited Methods

From Object

class

Return the class of the receiver.

Examples

42 class              // => Integer
"hello" class         // => String

isNil

Test if the receiver is nil. Returns false for all objects except nil.

Examples

42 isNil              // => false
nil isNil             // => true

notNil

Test if the receiver is not nil. Returns true for all objects except nil.

Examples

42 notNil             // => true
nil notNil            // => false

ifNil: _nilBlock

If the receiver is nil, evaluate nilBlock. Otherwise return self.

Examples

42 ifNil: [0]         // => 42
nil ifNil: [0]        // => 0

ifNotNil: notNilBlock

If the receiver is not nil, evaluate notNilBlock with self.

Examples

42 ifNotNil: [:v | v + 1]   // => 43
nil ifNotNil: [:v | v + 1]  // => nil

ifNil: _nilBlock ifNotNil: notNilBlock

If nil, evaluate nilBlock; otherwise evaluate notNilBlock with self.

Examples

42 ifNil: [0] ifNotNil: [:v | v + 1]    // => 43
nil ifNil: [0] ifNotNil: [:v | v + 1]   // => 0

ifNotNil: notNilBlock ifNil: _nilBlock

If not nil, evaluate notNilBlock with self; otherwise evaluate nilBlock.

Examples

42 ifNotNil: [:v | v + 1] ifNil: [0]    // => 43
nil ifNotNil: [:v | v + 1] ifNil: [0]   // => 0

printString

Return a developer-readable string representation.

Default implementation returns "a ClassName". Subclasses such as Integer, String, and List override this to return richer output.

Examples

42 printString            // => "42"

displayString

Return a user-facing string representation for display purposes.

Default implementation delegates to printString. Subclasses such as String and Symbol override this to return a more readable form without developer annotations (e.g. no surrounding quotes or # prefix).

Examples

42 displayString             // => "42"

inspect

Inspect the receiver.

Examples

42 inspect             // => "42"

yourself Sealed

Return the receiver itself. Useful for cascading side effects.

Examples

42 yourself            // => 42

hash

Return a hash value for the receiver.

Examples

42 hash

respondsTo: selector Sealed

Test if the receiver responds to the given selector.

Examples

42 respondsTo: #abs    // => true

fieldNames Sealed

Return the names of fields.

Examples

42 fieldNames             // => #()

fieldAt: name Sealed

Return the value of the named field.

Examples

object fieldAt: #name

fieldAt: name put: value Sealed

Set the value of the named field (returns new state).

Examples

object fieldAt: #name put: "Alice"

perform: selector Sealed

Send a unary message dynamically.

Examples

42 perform: #abs       // => 42

perform: selector withArguments: args Sealed

Send a message dynamically with arguments.

Examples

3 perform: #max: withArguments: #(5)   // => 5

subclassResponsibility

Raise an error indicating this method must be overridden by a subclass.

Examples

self subclassResponsibility

notImplemented

Raise an error indicating this method has not yet been implemented.

Use this for work-in-progress stubs. Distinct from subclassResponsibility, which signals an interface contract violation.

Examples

self notImplemented

show: aValue

Send aValue to the current transcript without a trailing newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 show: "value: "

showCr: aValue

Send aValue to the current transcript followed by a newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 showCr: "hello world"

isKindOf: aClass

Test if the receiver is an instance of aClass or any of its subclasses.

Examples

42 isKindOf: Integer    // => true
42 isKindOf: Object     // => true
#foo isKindOf: Symbol   // => true
#foo isKindOf: String   // => false

error: message

Raise an error with the given message.

Examples

self error: "something went wrong"

From ProtoObject

== other

Test value equality (Erlang ==).

Examples

42 == 42           // => true
"abc" == "abc"     // => true

/= other

Test value inequality (negation of ==).

Examples

1 /= 2             // => true
42 /= 42           // => false

class

Return the class of the receiver.

Examples

42 class            // => Integer
"hello" class       // => String

doesNotUnderstand: selector args: arguments

Handle messages the receiver does not understand. Override for custom dispatch.

Examples

42 unknownMessage   // => ERROR: does_not_understand

perform: selector withArguments: arguments

Send a message dynamically with an arguments list.

Examples

42 perform: #abs withArguments: #()   // => 42

performLocally: selector withArguments: arguments

Execute a class method in the caller's process, bypassing gen_server dispatch.

The caller takes responsibility for knowing the method does not mutate class state. Useful for long-running class methods that would otherwise block the class object's gen_server.

Limitations: only resolves methods defined directly on the target class module (does not walk the superclass chain). Class variables and self are not available to the method (nil and #{} are passed).

Examples

MyClass performLocally: #run:ctx: withArguments: #(input, ctx)

perform: selector withArguments: arguments timeout: timeoutMs

Send a message dynamically with an arguments list and explicit timeout.

The timeout (in milliseconds or #infinity) applies to the gen_server:call when the receiver is an actor. For value types, timeout is ignored.

Examples

actor perform: #query withArguments: #(sql) timeout: 30000