session method

Future<CliSession> session()

The inline session of the interactive mode, opened the first time it is asked for and kept until close: what the prompts and progress of this package mount their widgets in, and where a program mounts a live widget (CliSession.mount) to show it below the lines it logs, which are committed above it.

A session that ended, by a Ctrl+C (the process going on where it handles SIGINT) or by its own CliSession.close, leaves the next asking to open a new one, as the terminal's input is left as it was; keep the session for no longer than CliSession.isOpen says. A StateError in another mode, so check mode first, or once the console is closed.

Future<void> watch(Cli cli) async {
  if (cli.mode != CliMode.interactive) {
    cli.info('watching');
    return;
  }
  final session = await cli.session();
  final live = session.mount(const Text('watching'));
  cli.info('started');
  live.update(const Text('still watching'));
  live.remove();
}

Implementation

Future<CliSession> session() {
  if (mode != CliMode.interactive) {
    throw StateError('no inline session in the ${mode.name} mode');
  }
  if (_closed) {
    throw StateError('the console is closed');
  }
  if (_session case final ended? when !ended.isOpen) {
    _forgetSession();
  }
  return _opening ??=
      CliSession.open(
        terminal,
        theme: theme.data,
        strings: strings,
        onInterrupt: _interrupted,
        onWarning: warn,
      ).then(
        (session) {
          _probedUnderlines = session.styledUnderlines;
          return _session = session;
        },
        onError: (Object e, StackTrace s) {
          // no session is opening any more: what is written goes as
          // without one, at once
          _openFailed = true;
          Error.throwWithStackTrace(e, s);
        },
      );
}