// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.shell;

/// Result of a ExecutePendingInstructions.
enum ExecuteResult : uint32 {
    /// Only used for fields. This will never be used by ExecutePedningInstructions.
    UNDEF = 0;
    /// Execution finished without error.
    OK = 1;
    /// Execution finished with errors during the execution.
    EXECUTION_ERROR = 2;
    /// Execution finished with errors during the semantic/analysis passes.
    ANALYSIS_ERROR = 3;
};

/// Defines a unique identifier for an AST node.
struct NodeId {
    /// The id of the file.
    uint64 file_id;
    /// The id of the node for that file.
    uint64 node_id;
};

/// Defines a Location for an error.
table Location {
    /// Defined for error relative to an AST node. For native methods, this is not defined.
    1: NodeId node_id;
};

/// Defines the protocol to communicate with a shell interpreter.
[Discoverable]
protocol Shell {
    /// Creates an execution context.
    ///
    /// - `context_id` the id for the context. This id is provided by the client which must ensure
    ///   that the id is unique. A context_id can be reused as soon as OnExecutionDone is
    ///   received. 
    CreateExecutionContext(uint64 context_id);

    /// Executes all the pending instructions. This can generate one or several errors using
    /// OnError.
    /// When the execution is finished (all the pending instructions have been handled),
    /// OnExecutionDone is called.
    /// This will execute all the instructions added to the execution context is received.
    /// It is illegal to add more instructions once this function has been called.
    /// If you need to execute more instructions, you need to create another execution context.
    ///
    /// - `context_id` the id for the execution context previously created with
    ///   CreateExecutionContext.
    ExecuteExecutionContext(uint64 context_id);

    /// Called each time the shell detects an error.
    ///
    /// - `context_id` when the error is generated by an execution context, the id of the context.
    ///   Zero otherwise.
    /// - `locations`
    ///   For runtime errors, this is the stack frame (inner location first).
    ///   For semantic errors, this is the location of the error (only one item).
    ///   For global errors (not relative to a file), this is empty.
    /// - `error_message` the text message for the error.
    -> OnError(uint64 context_id, vector<Location>:MAX locations, string:MAX error_message);

    /// Signals that the shell has handled all the pending instructions.
    /// Once this event is called, the execution context is destroyed.
    ///
    /// - `context_id` the execution context id.
    /// - `result` the result of the execution.
    -> OnExecutionDone(uint64 context_id, ExecuteResult result);
};