Practical Guides for Topaz

This section offers a collection of practical guides and tutorials to help you accomplish common tasks using the Topaz language. These guides assume you have a basic understanding of Topaz syntax and concepts, as covered in the Getting Started and Language Reference sections.

We encourage you to experiment with the code examples. While full syntax highlighting for Topaz in these blocks is coming soon, the S-expression structure should be clear.

Working with Modules

In Topaz, modularity is key to organizing larger projects and promoting code reusability. While the precise high-level module system (defining packages, namespaces, and fine-grained import/export controls) is an area of active development and will be detailed in future updates, we can illustrate the core concept of using definitions from different files.

Conceptually, each .tpz file can be thought of as a module. Definitions (like functions or constants) made at the top level of a file can be made accessible to other files through a linking process or a future import mechanism.

(This guide will walk you through defining reusable functions in one file and using them in another. Example code and explanations on the evolving module system will be provided here as it solidifies.)

Example:

Let's say we have a utility file utils.tpz:

;; File: src/utils.tpz
;; A simple utility module.

(MODULE utils
  (EXPORT add greet)

  ;; Defines a process 'add' that takes two arguments 'a' and 'b'.
  ($ add 
    (λ (a b) 
      (+ a b) ;; '+' is a core operation
    )
  )

  ;; Another utility
  ($ greet
    (λ (name)
      (string:concat "Hello, " name "!") ;; string:concat for string concatenation
    )
  )
)

And a main file main.tpz that wants to use the add function:

;; File: src/main.tpz
;; Demonstrates using a function from another module.

;; Import the utils module with an alias
(IMPORT utils :as u)

($ main
  (λ ()
    ($ result (u:add 5 3))
    (io:print 
      (string:concat "5 + 3 = " (core:to-string result))
    )
  )
)

;; (main) ;; To run the main process

This illustrates how you might structure and use reusable code. Stay tuned for detailed specifications on Topaz's module system! Standard library usage will also be covered extensively once the core library modules are defined.

File I/O

Topaz will provide robust and straightforward operations for interacting with the file system. This is crucial for a wide range of applications, from CLI tools to data processing pipelines.

(This guide will cover reading from files (text, binary), writing to files, checking file existence, directory manipulation, and handling potential I/O errors using Topaz's error handling mechanisms. Example code and best practices will be provided.)

Conceptual Example:

;; Reading text from a file
($ file-path "data/input.txt")
($ content-result (io:read-text-file file-path)) ;; Operation returns a Result type

;; Using IF with Result type handling
(IF (result:is-ok content-result)
  (io:print (string:concat "File content: " (result:get-value content-result)))
  (io:print (string:concat "Error reading file: " (result:get-error content-result)))
)

;; Writing text to a file
($ output-path "data/output.txt")
($ write-status (io:write-text-file output-path "Hello from Topaz file I/O!"))

(IF (result:is-ok write-status)
  (io:print "Successfully wrote to file.")
  (io:print "Error writing to file.")
)

Note: READ-TEXT-FILE, WRITE-TEXT-FILE, IS-OK, GET-VALUE, GET-ERROR are illustrative names for operations and result handling functions that would be part of Topaz's I/O and error handling system.

Error Handling

Topaz is designed with robust error handling in mind, favoring explicit error management over traditional exceptions for many use cases. This aligns with its goal of producing clear, predictable, and resilient software. The primary mechanism will be Result/Option types (or similar Algebraic Data Types - ADTs).

(This guide will delve into best practices for error handling in Topaz. We'll explore how to use Result/Option types effectively, how to propagate errors, and strategies for recovering from failures gracefully. You'll learn how to write code that clearly communicates and handles potential error states.)

Conceptual Example:

;; A function that might fail, returning a Result type
($ safe-divide 
  (λ (numerator denominator)
    (IF (= denominator 0)
      (result:err "Division by zero!") ;; result:err constructor for failure
      (result:ok (/ numerator denominator)) ;; result:ok constructor for success
    )
  )
)

($ operation-result (safe-divide 10 2))
;; ($ operation-result (safe-divide 10 0)) ;; To test error case

;; Handling the result
(IF (result:is-ok operation-result)
  (io:print (string:concat "Result: " (core:to-string (result:get-value operation-result))))
  (io:print (string:concat "Error: " (result:get-error operation-result)))
)

This example assumes OK and ERR are constructors for a Result ADT, and IS-OK, GET-VALUE, GET-ERROR are helper functions/macros for working with it.

Concurrency

Topaz will support a clear and efficient concurrency model based on message passing principles (similar to the Actor Model or CSP). This approach is chosen to minimize shared state, prevent common concurrency bugs like race conditions and deadlocks, and scale effectively in multi-core and distributed environments.

(This guide will introduce Topaz's concurrency primitives, such as spawning concurrent processes (or "actors"), sending and receiving messages, and managing state in a concurrent setting. We'll cover patterns for building responsive and parallel applications.)

Conceptual Example (very high-level):

;; Define a process that acts as a "worker"
($ my-worker-process 
  (λ (message-channel)
    ;; Loop to receive messages
    (concurrent:loop
      ($ received-message (concurrent:receive message-channel))
      (io:print (string:concat "Worker received: " received-message))
      ;; ... do some work ...
    )
  )
)

;; Spawn the worker
($ worker-channel (concurrent:create-channel))
(concurrent:spawn (my-worker-process worker-channel))

;; Send a message to the worker
(concurrent:send worker-channel "Task A")

This is highly illustrative. The actual syntax for LOOP, RECEIVE, CREATE-CHANNEL, SPAWN, SEND will be defined as part of the concurrency model and standard library.

Building a Simple Web Server (Example Project)

One of the best ways to learn a language is by building something practical. Topaz, with its focus on efficiency, is well-suited for network applications.

(This guide will provide a step-by-step walkthrough of creating a basic HTTP server in Topaz from scratch, or using an early version of a standard networking library. You'll learn about handling requests, routing, and sending responses.)

(Detailed code examples and explanations for building a web server will be provided here as Topaz's networking capabilities are developed.)