Valacore

---

Description:

Valacore Reference Manual

libvalacore is a comprehensive core library for Vala — just add one dependency and get everything you need for daily development.

It aims to be for Vala what Boost is for C++, Base for OCaml, or the standard library for Go and Java. It provides practical APIs inspired by those ecosystems, while keeping GLib compatibility and idiomatic Vala design.

Design Goals

• **Productivity first**: frequently needed tasks should be one or two API calls.
• **Defensive behavior**: public APIs validate inputs and return explicit failure signals (`bool`/nullable).
• **Consistency**: method naming and return semantics are aligned across namespaces.
• **Testability**: APIs are designed to be easy to unit-test and compose.

Quick Start

Build and run tests:

meson setup build
meson test -C build

Install:

sudo ninja -C build install

Example usage:

using Vala.Io;
using Vala.Collections;

void main () {
    Files.writeText (new Path ("/tmp/example.txt"), "hello");

    var list = new ArrayList<int> ();
    list.add (3);
    list.add (1);
    list.add (2);
    list.sort ();
}

Namespace Guide

Only namespaces currently implemented in this version are listed below.

• Vala.Collections - Generic collections and utility algorithms (ArrayList, HashMap, Stream, Optional, etc.)
• Vala.Concurrent - Concurrency primitives (Channel, ThreadPool, Mutex, Semaphore, WaitGroup)
• Vala.Config - Configuration models and loaders (Vala.Config.Properties)
• Vala.Conv - Type conversion helpers (Vala.Conv.Convert)
• Vala.Crypto - Hash/HMAC/UUID utilities (Vala.Crypto.Hash, Vala.Crypto.Hmac, Vala.Crypto.Uuid)
• Vala.Encoding - Base64/CSV/Hex/URL encoding and decoding
• Vala.Format - Number formatting helpers (Vala.Format.NumberFormat)
• Vala.Io - File system, path, buffered I/O, scanner, atomic write, file lock, shell/process helpers
• Vala.Lang - Language-level helpers (process, environment, preconditions, random, threads)
• Vala.Log - Logging APIs (Vala.Log.Logger, Vala.Log.LogLevel)
• Vala.Math - Math and random APIs, plus big number value objects
• Vala.Net - URL and resilience primitives (Vala.Net.NetUrl, Vala.Net.Retry, Vala.Net.RateLimiter, Vala.Net.CircuitBreaker)
• Vala.Parser - Command-line parser (Vala.Parser.ArgParser)
• Vala.Regex - Compiled regex wrapper (Vala.Regex.Pattern)
• Vala.Runtime - Runtime/system property helpers ( Vala.Runtime.SystemProperties)
• Vala.Text - Text utility APIs (Vala.Text.Regex)
• Vala.Time - Date/time and duration APIs (Vala.Time.DateTime, Vala.Time.Duration, Vala.Time.Stopwatch)

Recommended Entry Points

• File operations: Vala.Io.Files, Vala.Io.Path
• Safe updates: Vala.Io.AtomicFile, Vala.Io.FileLock
• Command execution: Vala.Io.Shell, Vala.Lang.Process
• Collection processing: Vala.Collections.ArrayList, Vala.Collections.Stream, Vala.Collections.Maps
• Resilience: Vala.Net.Retry, Vala.Net.RateLimiter, Vala.Net.CircuitBreaker

Guides

• Getting Started
• I/O and Process Guide
• Resilience Guide

Documentation Notes

Each public class and method includes Valadoc comments with:

• purpose and behavior
• parameter and return descriptions
• practical examples for common use cases

Until v1.0.0, breaking changes may be introduced between minor versions.

Links

• GitHub Repository
• README
• License (Apache 2.0)

Content:

Namespaces:

• Vala
• Archive

Classes:

• Tar - Static utility methods for Tar archive creation and extraction.
• Zip - Static utility methods for Zip archive creation and extraction.

Error domains:

• TarError - Error domain for tar archive operations.
• ZipError - Error domain for zip archive operations.
• Collections

Classes:

• ArrayList - A dynamic array-backed list that grows automatically as elements are added.
• Arrays - Static utility methods for int arrays.
• BitSet - A fixed-size or dynamically growing set of bits.
• BloomFilter - Probabilistic membership filter with no false negatives.
• Deque - A double-ended queue (deque) that supports efficient insertion and removal at both ends.
• HashMap - A hash table-based map from keys to values.
• HashSet - A hash table-based set of unique elements.
• HyperLogLog - HyperLogLog cardinality estimator.
• ImmutableList - Immutable list value object.
• LinkedList - A doubly-linked list that supports efficient insertion and removal at both ends.
• Lists - Static utility methods for ArrayList operations.
• LruCache - LRU cache with optional TTL and cache-miss loader.
• Maps - Static utility methods for HashMap operations.
• MultiMap - A map that can store multiple values per key.
• Optional - A container object that may or may not contain a value.
• Pair - An immutable pair of two values.
• PriorityQueue - A priority queue backed by a binary min-heap.
• Queue - A FIFO (First-In-First-Out) queue backed by a GLib.Queue.
• Result - A container representing either a success value or an error.
• Stack - A LIFO (Last-In-First-Out) stack backed by a GLib.Queue.
• Stream - A fluent pipeline for transforming and aggregating collection data.
• TreeMap - A sorted map backed by a balanced binary search tree.
• Triple - An immutable triple of three values.

Error domains:

• BloomFilterError - Recoverable BloomFilter argument errors.
• HyperLogLogError - Recoverable HyperLogLog argument errors.
• ImmutableListError - Recoverable ImmutableList argument errors.
• LruCacheError - Recoverable LRU cache operation errors.
• StreamError - Recoverable Stream operation errors.

Delegates:

• public delegate void BiConsumerFunc<A,B> (A a, B b)
  A function that takes two arguments and returns nothing.
• public delegate bool BiPredicateFunc<A,B> (A a, B b)
  A function that takes two arguments and returns a boolean.
• public delegate V CacheLoaderFunc<K,V> (K key)
  Loader function for cache misses.
• public delegate int ComparatorFunc<T> (T a, T b)
  A function that compares two values for ordering.
• public delegate T ConflictResolverFunc<T> (T existing, T incoming)
  Resolves collision by choosing one of two values.
• public delegate void ConsumerFunc<T> (T value)
  A function that takes a value and returns nothing.
• public delegate double DoubleMapFunc<T> (T value)
  A function that maps a value to a double.
• public delegate U MapFunc<T,U> (T value)
  A function that transforms a value of type T to type U.
• public delegate bool PredicateFunc<T> (T value)
  A function that takes a value and returns a boolean.
• public delegate U ReduceFunc<T,U> (U accumulator, T element)
  A function that accumulates a value by combining an accumulator with each element.
• public delegate T SupplierFunc<T> ()
  A function that takes no arguments and returns a value.
• Compress

Classes:

• Gzip - Static utility methods for Gzip compression and decompression.
• Zlib - Static utility methods for Zlib compression and decompression.

Error domains:

• GzipError - Error domain for gzip operations.
• ZlibError - Error domain for zlib operations.
• Concurrent

Classes:

• Channel - Generic typed message-passing channel inspired by Go channels.
• ChannelBox - Boxed generic value for channel transport.
• ChannelInt - Thread-safe message-passing channel inspired by Go channels.
• ChannelString - Thread-safe string message-passing channel.
• CountDownLatch - Countdown latch for one-shot synchronization.
• Future - Represents the eventual result of an asynchronous computation.
• IntBox - Boxed int value for channel transport.
• Mutex - Mutex wrapper with utility methods.
• Once - Executes a function at most once.
• PromiseBool - Promise for a bool result from an asynchronous computation.
• PromiseDouble - Promise for a double result from an asynchronous computation.
• PromiseInt - Promise for an int result from an asynchronous computation.
• PromiseString - Promise for a string result from an asynchronous computation.
• RWMutex - Reader-writer mutex.
• Semaphore - Counting semaphore.
• SingleFlight - Suppresses duplicate concurrent work for the same key.
• StringBox - Boxed string value for channel transport.
• TaskWrapper - Internal task wrapper used by WorkerPool.
• ThreadPool - Generic fixed-size thread pool for asynchronous task execution.
• ThreadPoolTaskFunc - Wrapper for queued task function used by invokeAll.
• WaitGroup - Waits for a collection of tasks to complete.
• WorkerPool - Fixed-size worker pool for executing tasks concurrently.

Error domains:

• ChannelError - Recoverable channel operation errors.
• CountDownLatchError - Recoverable countdown latch configuration errors.
• SemaphoreError - Recoverable semaphore configuration errors.
• SingleFlightError - Recoverable SingleFlight operation errors.
• ThreadPoolError - Recoverable generic thread pool configuration errors.
• WorkerPoolError - Recoverable worker pool configuration errors.

Delegates:

• public delegate void OnceFunc ()
  Function delegate for Once execution.
• public delegate T RecoverFunc<T> (string message)
  Function used by recover to turn a failure into a value.
• public delegate T SingleFlightFunc<T> ()
  Function used by do and doFuture.
• public delegate T TaskFunc<T> ()
  Function delegate that returns a value of type T.
• public delegate void VoidTaskFunc ()
  Function delegate that takes no arguments and returns nothing.
• public delegate void WithLockFunc ()
  Function delegate for withLock blocks.
• Config

Classes:

• AppConfig - Unified application configuration from file, environment, and CLI.
• Properties - Java-like key-value properties container.

Error domains:

• AppConfigError - Recoverable AppConfig argument and lookup errors.
• Conv

Classes:

• Convert - Type conversion utility methods.

Error domains:

• ConvertError - Recoverable conversion errors.
• Crypto

Classes:

• Hash - Static utility methods for cryptographic hashes.
• Hmac - Static utility methods for HMAC.
• Identifier - Immutable identifier value object.
• Identifiers - Utility class for UUID/ULID/KSUID generation and conversion.
• Uuid - Immutable UUID value object.

Enums:

• IdentifierType - Supported identifier types.
• Distributed

Classes:

• ConsistentHash - Consistent hash ring with virtual nodes.
• RendezvousHash - Weighted rendezvous hash (highest-random-weight hashing).
• Snowflake - 64-bit Snowflake ID generator.
• SnowflakeParts - Parsed Snowflake ID components.

Error domains:

• ConsistentHashError - Recoverable ConsistentHash argument errors.
• RendezvousHashError - Recoverable RendezvousHash argument errors.
• SnowflakeError - Recoverable Snowflake generator errors.
• Encoding

Classes:

• Base64 - Static utility methods for Base64 encoding and decoding.
• Csv - Static utility methods for CSV parsing and writing.
• Hex - Static utility methods for hexadecimal encoding and decoding.
• Json - Static utility methods for JSON parsing, serialization, and querying.
• JsonArrayBuilder - Builder for constructing JSON arrays fluently.
• JsonObjectBuilder - Builder for constructing JSON objects fluently.
• JsonValue - Represents one JSON value.
• Toml - Static utility methods for TOML parsing and querying.
• TomlValue - Represents one TOML value.
• Url - Static utility methods for URL percent- encoding.
• Xml - XML parsing and serialization utilities.
• XmlNode - Represents an XML node (element or text).
• Yaml - YAML parsing, serialization, and query utilities.
• YamlValue - Represents a YAML value (scalar, mapping, or sequence).

Enums:

• JsonValueType - JSON value type.
• TomlValueType - TOML value type.

Error domains:

• Base64Error - Error domain for Base64 codec operations.
• CsvError - Recoverable CSV argument errors.
• HexError - Error domain for hex codec operations.
• JsonError - Recoverable JSON operation errors.
• UrlError - Error domain for URL codec operations.
• Event

Classes:

• EventBus - In-process publish/subscribe event bus.

Error domains:

• EventBusError - Recoverable EventBus argument errors.

Delegates:

• public delegate void EventHandler (Variant eventData)
  Event handler receiving a Variant payload.
• Format

Classes:

• NumberFormat - Number formatting utilities.
• Io - Vala.Io namespace provides file I/O, path manipulation, and string utility APIs.

Classes:

• AtomicFile - Atomic file update helper.
• BufferedReader - BufferedReader provides buffered character-input-stream reading. It wraps a GLib.DataInputStream and offers convenient line-by-line or full-text reading similar to Java's BufferedReader and Go's bufio.Scanner.
• BufferedWriter - BufferedWriter provides buffered character-output-stream writing. It wraps a GLib.DataOutputStream and offers convenient methods for writing strings and lines, similar to Java's BufferedWriter.
• Console - Console utility methods.
• FileLock - File-based inter-process lock.
• FileTree - High-level recursive directory operations.
• FileWatcher - Active filesystem watcher with callback registration.
• Files - Files class provides static utility methods for common file and directory operations.
• Filesystem - Filesystem metadata utility methods.
• Path - Path class is a value object that represents a file system path.
• Process - Process execution utility methods.
• Resource - Resource loading helper methods.
• Scanner - Scanner splits input into tokens and provides typed parsing.
• Shell - Shell command helper for quick command execution and output capture.
• ShellResult - Result of shell command execution.
• StringBuilder - StringBuilder is a mutable string buffer for efficient string construction. It wraps GLib.StringBuilder and provides a rich, Java/C#-inspired API.
• StringJoiner - StringJoiner constructs a sequence of characters separated by a delimiter and optionally starting with a prefix and ending with a suffix. This is equivalent to Java's StringJoiner.
• Strings - Strings class is a collection of static APIs for manipulating string.
• Temp - Temporary file and directory helpers.
• WatchEvent - Value object that represents one filesystem event.
• Watcher - Static factory for filesystem watchers.

Enums:

• WatchEventType - Filesystem watch event type.

Error domains:

• AtomicFileError - Recoverable AtomicFile argument errors.
• ConsoleError - Recoverable console I/O errors.
• FileLockError - Recoverable FileLock argument errors.
• FilesystemError - Recoverable filesystem metadata errors.
• ResourceError - Recoverable resource loading errors.
• ShellError - Recoverable Shell argument errors.
• WatcherError - Recoverable watcher initialization errors.

Delegates:

• public delegate void RenameCallback (WatchEvent from, WatchEvent to)
  Rename callback type.
• public delegate void TempFunc (Path path)
  Callback delegate used by temporary resource helpers.
• public delegate void WatchCallback (WatchEvent eventData)
  Watch callback type.
• public delegate bool WithFileLockFunc ()
  Callback executed while lock is held.
• Lang - Vala.Lang namespace provides language-level utilities such as null checking and OS interfaces.

Classes:

• Context - Cancellation and timeout context propagated across call boundaries.
• Exceptions - Exception utility methods.
• Objects - Utility methods for nullable object checks.
• Os - Operating-system utility methods.
• Preconditions - Utility methods for precondition checks.
• Process - Wrapper for external process execution.
• Randoms - Random utility methods.
• ShutdownHooks - Utilities for registering callbacks executed at process shutdown.
• StringEscape - String escaping utilities.
• SystemEnv - Environment variable helper methods.
• SystemInfo - System information helper methods.
• Threads - Thread utility methods.

Error domains:

• ContextError - Recoverable context argument errors.
• PreconditionError - Recoverable precondition validation errors.
• RandomsError - Recoverable random utility argument errors.

Delegates:

• public delegate void ShutdownHookFunc ()
  Callback delegate for shutdown hook handlers.
• Log

Interfaces:

• LogHandler - Log handler interface.

Classes:

• Logger - Named logger with level filtering and pluggable handlers.

Enums:

• LogLevel - Logging level.
• Math

Classes:

• BigDecimal - Immutable arbitrary-precision decimal value object.
• BigInteger - Immutable arbitrary-precision integer value object.
• Math - Static utility methods for mathematics.
• Random - Static utility methods for random values.

Error domains:

• BigDecimalError - Recoverable BigDecimal argument and arithmetic errors.
• BigIntegerError - Recoverable BigInteger argument errors.
• MathError - Recoverable argument errors for math helpers.
• RandomError - Recoverable random utility argument errors.
• Net

Classes:

• CircuitBreaker - Circuit breaker for protecting unstable dependencies.
• Http - Static utility methods for HTTP requests.
• HttpClient - Base URL HTTP client with reusable defaults.
• HttpRequestBuilder - Builder for constructing HTTP requests with custom settings.
• HttpResponse - Represents an HTTP response.
• RateLimiter - Thread-safe token-bucket rate limiter.
• Retry - Retry policy for resilient operations such as HTTP calls or lock acquisition.
• Url - Immutable URL value object.

Enums:

• CircuitState - Circuit breaker state.

Error domains:

• CircuitBreakerError - Recoverable circuit breaker configuration errors.
• NetUrlError - Recoverable URL parse errors.
• RateLimiterError - Recoverable rate limiter operation errors.
• RetryError - Recoverable retry policy configuration errors.

Delegates:

• public delegate Result<T,string> CircuitFunc<T> ()
  Callback executed through circuit breaker.
• public delegate void RetryCallback (int attempt, string reason, int64 delayMillis)
  Callback invoked before sleeping for the next retry attempt.
• public delegate bool RetryFunc ()
  Callback invoked by retry loop and interpreted as success/failure.
• public delegate bool RetryOnFunc (string reason)
  Predicate used to decide whether retry should continue.
• public delegate T RetryResultFunc<T> ()
  Callback invoked by retry loop and interpreted as nullable result.
• public delegate Result<bool,Error> RetryVoidFunc ()
  Callback invoked by retry loop with Result-style failure contract.
• public delegate void StateChangeCallback (CircuitState from, CircuitState to)
  Callback invoked when breaker state changes.
• Parser - Vala.Parser namespace provides command-line argument parsing with the Builder pattern.

Classes:

• ArgParser - ArgParse class parse application options. Options must be registered before parsing the option arguments.
• Regex

Classes:

• Pattern - Compiled regular expression wrapper.
• Runtime

Classes:

• SystemProperties - System property helper methods.
• Text

Classes:

• CompiledTemplate - A pre-compiled template for repeated rendering.
• Regex - Static utility methods for regular expressions.
• Template - Simple template engine with Mustache/Handlebars-style syntax.
• Time

Classes:

• Cron - Simple cron scheduler with interval, daily time, and limited cron expression support.
• DateTime - Immutable value object for date-time operations.
• Dates - Static utility methods for DateTime operations.
• Duration - Immutable value object that represents a duration.
• Stopwatch - Mutable stopwatch for elapsed-time measurement.

Error domains:

• CronError - Recoverable Cron configuration errors.
• DateTimeError - Recoverable DateTime argument/parse errors.

Delegates:

• public delegate void CronTask ()
  Scheduled task callback.
• Validation

Classes:

• ValidationError - Validation error for one field.
• ValidationResult - Validation result object.
• Validator - Fluent validator for user input and configuration values.