#
# Interface definitions for the core runtime library (work in progress!)
#
# Copyright © 2025 Samuel Lidén Borell <samuel@kodafritt.se>
#
# SPDX-License-Identifier: EUPL-1.2+ OR LGPL-2.1-or-later
#


# XXX should there be different kinds of classes for service types and givemes?

# XXX this structure makes nested (normal) classes impossible.
#     alternatives to normal nesting of classes:
#     - `nested class NC`
#     - `nested NC`
#     - `class NC = int x, bool b`
#     - different behavior in class-files
#     - `tuple NC = int x, bool b`
#     - `local class NC`  (i.e. don't allow nested classes to be visible
#       to other files)
#     - inline tuples
#        - but it might lead to lots of repetition
#        - and then they cannot have methods
#        - unless you allow `func (int,bool).somefunc`

# XXX this creates a difference between func and class
#      - no `end` for `class`
#      - but `end` required for `func`

# XXX what if this file gets really large?
#    - add a way to split it?
#    - add a way to split modules? (better?)
#    - make it more compact? is that a good idea? (documentation comments etc.)
# XXX api hashes (manual or automatic?)


###########################################################################


class CommandMain
# Service interface for the main CLI command of an application


###########################################################################


class String
# String of (possibly invalid!) UTF-8 bytes. Fully binary-safe, can contain
# non-UTF-8 bytes as well as null bytes.


###########################################################################


class MessageReporter
# A class that can be injected as a `giveme` to provide basic message
# (error/warning/info) reporting
#
# TODO stdout vs stderr

func begin_message
# Starts a new message. Nothing is actually written until `report` is called.
    String format
    # TODO
end

func add_int
# Adds a number as the next format parameter value.
    int number
end

func report
# Finishes a message, and outputs/reports it.
end


###########################################################################


class Writer
# Writes strings to some location. Can be injected as a `giveme` to get
# access to `stdout` or `stderr`.

func write_str
# Writes a string to the output.
    String s
    # String to write. If the output supports binary, then it may contain
    # binary (and invalid UTF-8). Otherwise, it should be valid UTF-8.
    # (Encoding errors could perhaps be handled like I/O errors?)
end