/**
 * Wenn die Bibliothek zur Erweiterung der IDE eingebunden (`ide-lib.js`) wurde,
 * steht diese globale Variable mit Zugang zur öffentlichen Schnittstelle
 * zur Verfügung.
 */
declare const MC: MathCoach.Api;

/**
 * Der MathCoach-Namensraum ist die Sammelstelle für alle öffentlichen Schnittstellen.
 * Somit können auch externe Module (z.B. grafische Editoren) typsicher erstellt werden.
 * Als Einstiegspunkt dient das interface `MathCoach.Api` - eine Implementierung dieser Schnittstelle
 * wird von der IDE (siehe `ide-lib.js`) bereitgestellt und kann über die globale Variable 
 * `MC` zugegriffen werden. 
 */
declare namespace MathCoach {

    /**
     * Einstiegspunkt zur MathCoach API Schnittstelle 
     */
    interface Api {
        /**
         * Die Schnittstelle zur Entwicklungsumgebung (IDE) von MathCoach
         */
        readonly ide: IdeApi;
    }


    /**
    * Schnittstelle zur IDE von MathCoach
    */
    interface IdeApi {
        /**
         * Name des aktuellen Benutzers
         */
        getUserName(): Promise<string>;
        /**
         * Verweis auf die Datei, mit dem das Entwicklerwerkzeug gestartet wurde.
         */
        getContextFile(): Promise<File>;
        /**
         * Schnittstelle zum Dateisystem
         */
        readonly fs: FileSystemApi;
        /**
         * Schnittstelle zur Navigations-Vorschau
         */
        readonly navigator: NavigatorApi;
    }
    /**
     * Schnittstelle zur Navigations-Vorschau
     */
    interface NavigatorApi {
        /**
         * Navigiert die Vorschau zu einem Link.
         * @param link Web URL (z.B. zu einer Datei im WWW-Verzeichnis oder einer MathCoach-Aufgabe)
         * @param forceOpen `true` um das Anzeigen der Vorschau zu erzwingen, `false` um nur bei bereits geöffneter Vorschau zu navigieren.
         */
        navigateTo(link: string, forceOpen?: boolean): Promise<void>;
    }
    /**
     * Schnittstelle zum Dateisystem
     */
    interface FileSystemApi {
        /**
         * Liest eine Datei
         * 
         * @param file Verweis auf die Datei
         */
        readFile(file: File): Promise<string>;
        /**
         * Schreibt Text in eine Datei. 
         * 
         * @param file Verweis auf die Datei
         * @param text Der neue Inhalt der Datei
         */
        writeFile(file: File, text: string): Promise<void>;
    }
    /**
     * Eindeutiger Verweis auf eine Datei
     */
    interface File {
        /**
         * Name des Besitzers. Hinweis: Der Besitzter kann vom angemeldeten
         * Benutzer abweichen (z.B. wenn das Teilen von Inhalten zukünftig unterstützt wird)
         */
        owner: string;
        /**
         * Liegt die Datei im öffentlichen (www) oder verborgenen (vfs) Dateisystem?
         */
        part: "vfs" | "www";
        /**
         * Absoluter Pfad zur Datei. Mmuss immer mit einem Slash beginnen.
         */
        path: string;
    }
}