Module B0_pager

Pager interaction.

Paging

type t

The type for pagers.

val does_page : t -> bool

does_page p is true iff p actually pages.

val find : ?search:B0_std.Cmd.tool_search -> ?cmd:B0_std.Cmd.t -> don't:bool -> unit -> (t, string) Stdlib.result

find ~search ~don't finds a suitable pager. This is (in order):

  1. Ok p if don't is true or if the TERM environment variable is dumb or undefined and cmd is unspecified. In this case does_page p is false.
  2. Ok p or Error _ if cmd is specified and according to whether Os.Cmd.get ?search cmd succeeds.
  3. Ok (Some pager) if pager is a tool invocation parsed from the PAGER environment variable that can be found via Os.Cmd.find ?search.
  4. Ok (Some pager) if either less or more can be found (in that order) via Os.Cmd.find ?search.
  5. Ok None otherwise.
val page_stdout : t -> (unit, string) Stdlib.result

page_stdout p setups the program so that if does_page p is true, the standard output of the program is redirected to a spawn of of the pager with the following twists:

  • If the environment variable LESS is undefined in the current environment it is set to LESS=FRX for the spawn of cmd.
  • A Stdlib.at_exit function is installed that flushes B0_std.Fmt.stdout and Stdlib.stdout, closes Unix.stdout and waits upon the cmd spawn termination.

If does_page p is false this function has no effect.

val page_files : t -> B0_std.Fpath.t list -> (unit, string) Stdlib.result

page_files p fs uses pager to page the files fs. If does_page p is:

  • false, each of the fs files is output on stdout, in order, separated by a file separator character (U+001C).
  • true, the pager's command is with fs as arguments, unless fs is empty in which case this is a nop.

Cli interaction

module Env : sig ... end

Environment variables.

val don't : ?docs:string -> unit -> bool Cmdliner.Term.t

don't ~docs () is a --no-pager command line option to unconditionally request not to use a pager. docs is the manual section where the option is documented, defaults to Cmdliner.Manpage.s_common_options.