// file      : libbuild2/script/run.hxx -*- C++ -*-
// license   : MIT; see accompanying LICENSE file

#ifndef LIBBUILD2_SCRIPT_RUN_HXX
#define LIBBUILD2_SCRIPT_RUN_HXX

#include <libbuild2/types.hxx>
#include <libbuild2/utility.hxx>

#include <libbuild2/script/script.hxx>

namespace build2
{
  namespace script
  {
    // An exception that can be thrown by an expression running function to
    // exit the script with the specified exit code (for example, as a result
    // of executing the exit builtin by the below run*() functions).
    //
    struct exit
    {
      // Note that we use the 0-255 range as the lowest common denominator
      // across the supported platforms (see command_exit for details).
      //
      uint8_t code;

      explicit
      exit (uint8_t c): code (c) {}

      // Indicate whether the execution should be considered to have succeeded
      // or failed.
      //
      explicit operator bool () const {return code == 0;}
    };

    // Helpers.
    //

    // Command expression running functions.
    //
    // Index is the 1-base index of this command line in the command list.
    // If it is 0 then it means there is only one command. This information
    // can be used, for example, to derive file names.
    //
    // Location is the start position of this command line in the script. It
    // can be used in diagnostics.
    //
    // Optionally, execute the specified function at the end of the pipe,
    // potentially instead of the last command (replace_last_cmd).
    //
    void
    run (environment&,
         const command_expr&,
         const iteration_index*, size_t index,
         const location&,
         const function<command_function>& = nullptr,
         bool replace_last_cmd = false);

    bool
    run_cond (environment&,
              const command_expr&,
              const iteration_index*, size_t index,
              const location&,
              const function<command_function>& = nullptr,
              bool replace_last_cmd = false);

    // Perform the registered special file cleanups in the direct order and
    // then the regular cleanups in the reverse order.
    //
    void
    clean (environment&, const location&);

    // Print first 10 directory sub-entries to the diag record. The directory
    // must exist. Is normally used while issuing diagnostics on non-empty
    // directory removal failure.
    //
    void
    print_dir (diag_record&, const dir_path&, const location&);

    // Return the quoted path representation with the preserved trailing
    // directory separator. The path is relative if the verbosity level is
    // less than 3.
    //
    string
    diag_path (const path&);

    // Same as above, but prepends the path with a name, if present. The path
    // must be not NULL.
    //
    string
    diag_path (const dir_name_view&);

    // Read the stream content, optionally splitting the input data at
    // whitespaces or newlines and calling the specified callback function for
    // each substring (see the set builtin options for the splitting
    // semantics). If the callback function returns false, then just read out
    // and skip the remaining input data. Throw failed on io_error.
    //
    // If the stream is a pipeline's output, then the pipeline argument must
    // also be specified. Normally called from a custom command function (see
    // command_function for details) which is provided with the pipeline
    // information.
    //
    // Turn the stream into the non-blocking mode and, if the pipeline is
    // specified, read out its buffered stderr streams while waiting for the
    // input stream data. If a deadline is specified and is reached, then
    // terminate the whole pipeline, if specified, and bail out. Otherwise
    // issue diagnostics and fail. The thinking here is that in the former
    // case the caller first needs to dump the buffered stderr streams, issue
    // the appropriate diagnostics for the pipeline processes/builtins, and
    // only throw failed afterwards.
    //
    // Note that on Windows we can only turn file descriptors of the pipe type
    // into the non-blocking mode. Thus, a non-pipe descriptor is read in the
    // blocking manner (and the deadline is checked less accurately). This is
    // fine since there are no pipeline stderr streams to read out in this
    // case.
    //
    void
    read (auto_fd&&,
          bool whitespace, bool newline, bool exact,
          const function<bool (string&&)>&,
          pipe_command* pipeline,
          const optional<deadline>&,
          const location&,
          const char* what);

    // Skip all the stream data, reading out the pipeline's buffered stderr
    // and/or watching for the deadline.
    //
    void
    skip (auto_fd&&,
          pipe_command* pipeline,
          const optional<deadline>&,
          const location&,
          const char* what);
  }
}

#endif // LIBBUILD2_SCRIPT_RUN_HXX
