|
#############################################################################
##
## This file is part of GAP, a system for computational discrete algebra.
## This file's authors include Frank Lübeck.
##
## Copyright of GAP belongs to its developers, whose names are too numerous
## to list here. Please refer to the COPYRIGHT file for details.
##
## SPDX-License-Identifier: GPL-2.0-or-later
##
## The files pager.g{d,i} contain the `Pager' utility. A rudimentary
## version of this was integrated in first versions of GAP's help system.
## But this utility is certainly useful for other purposes as well.
##
##
## There is a builtin pager `PAGER_BUILTIN', but at least under UNIX one
## should use an external one. This can be set via the variable
## `SetUserPreference("Pager", ...);'
## (e.g., SetUserPreference("Pager", "less");).
## Here, `less' should be in the executable
## PATH of the user and we assume that it supports an argument `+num' for
## starting display in line number `num'. Additional options can be
## given by `SetUserPreference("PagerOptions", ...);' as list of strings.
##
## The user function is `Pager'.
##
## The input of `Pager( lines )' can have one the following forms:
##
## (1) a string (i.e., lines are separated by '\n')
## (2) a list of strings (without '\n') interpreted as lines of output
## (3) a record with component .lines as in (1) or (2) and optional further
## components
##
## In (3) currently the following components are used:
##
## .formatted (true/false) If true, the builtin pager tries to avoid
## line breaks by GAP's Print.
## .start (number/string) The display is started with line .start or
## at the first line containing .start, but
## beginning is available via back scrolling.
## .exitAtEnd (true/false) If true (default), the builtin pager is
## terminated as soon as the end of the list is
## reached;
## if false, entering 'q' is necessary in order to
## return from the pager.
##
# The preferred pager can be specified via a user preference.
DeclareUserPreference( rec(
name:= [ "Pager", "PagerOptions" ],
description:= [
"For displaying help pages on screen and other things ⪆ has a rudimentary \
builtin pager. We recommend using a more sophisticated external program. \
For example, when you have the program <C>less</C> on your computer we recommend:",
" <C>Pager := \"less\";</C>",
" <C>PagerOptions := [\"-f\", \"-r\", \"-a\", \"-i\", \"-M\", \"-j2\"];</C>",
"If you want to use <C>more</C>, we suggest to use the <C>-f</C> option. \
If you want to use the pager defined in your environment then \
leave the <C>Pager</C> and <C>PagerOptions</C> preferences empty."
],
default:= function() # copied from GAPInfo.READENVPAGEREDITOR
local str, sp, pager, options;
if IsBound(GAPInfo.KernelInfo.ENVIRONMENT.PAGER) then
str := GAPInfo.KernelInfo.ENVIRONMENT.PAGER;
sp := SplitStringInternal(str, "", " \n\t\r");
if Length(sp) > 0 then
pager:= sp[1];
options:= sp{ [ 2 .. Length( sp ) ] };
# 'less' could have options in variable 'LESS'
if "less" in SplitStringInternal(sp[1], "", "/\\") then
if IsBound(GAPInfo.KernelInfo.ENVIRONMENT.LESS) then
str := GAPInfo.KernelInfo.ENVIRONMENT.LESS;
sp := SplitStringInternal(str, "", " \n\t\r");
Append( options, sp );
fi;
# make sure -r is used
Add( options, "-r" );
elif "more" in SplitStringInternal(sp[1], "", "/\\") then
if IsBound(GAPInfo.KernelInfo.ENVIRONMENT.MORE) then
# similarly for 'more'
str := GAPInfo.KernelInfo.ENVIRONMENT.MORE;
sp := SplitStringInternal(str, "", " \n\t\r");
Append( options, sp );
fi;
# make sure -f is used
Add( options, "-f" );
fi;
return [ pager, options ];
fi;
fi;
# The builtin pager does not work in HPCGAP
if IsHPCGAP then
return [ "less" , ["-f","-r","-a","-i","-M","-j2"] ];
else
return [ "builtin", [] ];
fi;
end,
) );
#############################################################################
##
#F PAGER_BUILTIN( <lines> ) . . . . . . . . . . . . . . . . format lines
##
## Show <A>lines</A> in a rudimentary pager inside the terminal.
## The argument can be either a string or a list of strings or a record.
## In the latter case, the component <C>lines</C> must be a string or a
## list of strings,
## and the following additional components are supported.
## <List>
## <Mark>formatted</Mark>
## <Item>
## <K>true</K> or <K>false</K> (default <K>false</K>),
## <K>true</K> means that lines not fitting into one terminal line
## (see <Ref Func="SizeScreen"/>) will be distributed to several lines,
## </Item>
## <Mark>start</Mark>
## <Item>
## a positive integer denoting the position of the first line that is
## shown,
## or a string meaning that the first line containing this string
## shall be shown;
## the default is 1,
## </Item>
## <Mark>exitAtEnd</Mark>
## <Item>
## <K>true</K> or <K>false</K> (default <K>true</K>),
## meaning whether the pager should terminate automatically
## once the last line is shown.
## </Item>
## </List>
##
# If the text contains ANSI color sequences we reset the terminal before
# we print the last line.
BindGlobal("PAGER_BUILTIN", function( r )
local formatted, linepos, exitAtEnd, lines, size, wd, pl, count, i, stream,
halt, lenhalt, delhaltline, from, len, emptyline, char, out;
formatted := false;
linepos := 1;
exitAtEnd:= true;
# don't print this to LOG files
out := OutputTextUser();
if IsRecord(r) then
lines := r.lines;
else
lines := r;
fi;
if IsString(lines) then
lines := SplitString(lines, "\n", "");
elif not formatted then
lines := ShallowCopy(lines);
fi;
if Length( lines ) = 0 then
return;
fi;
if IsRecord(r) then
if IsBound(r.formatted) then
formatted := r.formatted;
if formatted <> true and formatted <> false then
Error("unsupported r.formatted value: ", formatted);
fi;
fi;
if IsBound(r.start) then
if IsPosInt(r.start) then
linepos := r.start;
elif IsString(r.start) then
linepos := PositionProperty(lines,
l -> PositionSublist(l, r.start) <> fail);
if linepos = fail then
linepos := 1;
fi;
else
Error("unsupported r.start value: ", r.start);
fi;
fi;
if IsBound( r.exitAtEnd ) then
exitAtEnd:= r.exitAtEnd;
if exitAtEnd <> true and exitAtEnd <> false then
Error("unsupported r.exitAtEnd value: ", exitAtEnd);
fi;
fi;
fi;
size := SizeScreen();
wd := QuoInt(size[1]+2, 2);
# really print line without breaking it
pl := function(l, final)
local r;
r := 1;
while r*wd<=Length(l) do
PrintTo(out, l{[(r-1)*wd+1..r*wd]}, "\c");
r := r+1;
od;
if (r-1)*wd < Length(l) then
PrintTo(out, l{[(r-1)*wd+1..Length(l)]});
fi;
PrintTo(out, final);
end;
if not formatted then
# cope with overfull lines
count:=1;
while count<=Length(lines) do
if Length(lines[count])>size[1]-2 then
# find the last blank before this position
i:=size[1]-2;
while i>0 and lines[count][i]<>' ' do
i:=i-1;
od;
if i>0 then
if not IsBound(lines[count+1]) then
lines[count+1]:="";
fi;
lines[count+1]:=Concatenation(
lines[count]{[i+1..Length(lines[count])]}," ", lines[count+1]);
lines[count]:=lines[count]{[1..i-1]};
fi;
fi;
count:=count+1;
od;
fi;
stream := InputTextFile("*errin*");
count := 0;
halt :=
" -- <space> page, <n> next line, <b> back, <p> back line, <q> quit --\c";
# remember number of visible characters
lenhalt := Length(halt)-1;
if UserPreference("UseColorsInTerminal") = true then
halt := Concatenation("\033[0m", halt);
fi;
delhaltline := function()
local i;
for i in [1..lenhalt] do
PrintTo(out, "\b\c \c\b\c" );
od;
end;
from := linepos;
len := Length(lines);
emptyline:= String( "", size[1]-2 );
if len < from then
# Ignore the start line.
# (The pager 'less' shows a warning and then goes to the first line.)
from:= 1;
fi;
repeat
for i in [from..Minimum(len, from+size[2]-2)] do
pl(lines[i], "\n");
od;
if len = i then
if exitAtEnd then
break;
fi;
for i in [ len+1 .. from+size[2]-2 ] do
pl( emptyline, "\n" );
od;
fi;
pl(halt, "");
repeat
char := ReadByte(stream);
if char = fail then
char := 'q';
else
char := CHAR_INT(char);
fi;
until char in " nbpq";
if char = ' ' and i < len then
from := from+size[2]-1;
elif char = 'n' and i < len then
from := from+1;
elif char = 'p' and from>1 then
from := from-1;
elif char = 'b' then
from := Maximum(1, from-size[2]+1);
fi;
delhaltline();
until char = 'q';
CloseStream(stream);
end);
# for using `more' or `less' or ... (read from `UserPreference("Pager")')
# we assume that UserPreference("Pager") allows command line option
# +num for starting display in line num
BindGlobal("PAGER_EXTERNAL", function( lines )
local pager, linepos, str, i, cmdargs, stream;
pager := UserPreference("Pager");
if not (Length(pager) > 0 and pager[1] = '/' and IsExecutableFile(pager))
then
pager := PathSystemProgram( UserPreference("Pager") );
fi;
if pager=fail then
Error( "Pager ", UserPreference("Pager"),
" not found, reset with `SetUserPreference(\"Pager\", ...);'." );
fi;
linepos := 1;
if IsRecord(lines) then
if IsBound(lines.start) then
linepos := lines.start;
if not (IsPosInt(lines.start) or IsString(lines.start)) then
Error("unsupported lines.start value: ", linepos);
fi;
fi;
lines := lines.lines;
fi;
if not IsString(lines) then
str:="";
for i in lines do
Append(str,i);
Add(str,'\n');
od;
lines := str;
fi;
if IsString(linepos) then
cmdargs := [Concatenation("+/", linepos)];
elif linepos > 1 then
cmdargs := [Concatenation("+", String(linepos))];
else
cmdargs := [];
fi;
stream:=InputTextString(lines);
Process(DirectoryCurrent(), pager, stream, OutputTextUser(),
Concatenation( UserPreference("PagerOptions"), cmdargs ));
end);
InstallGlobalFunction("Pager", function(lines)
if UserPreference("Pager") = "builtin" then
PAGER_BUILTIN(lines);
else
PAGER_EXTERNAL(lines);
fi;
end);
BindGlobal( "PagerAsHelpViewer", function( lines )
if UserPreference( "Pager" ) = "builtin" then
if IsRecord( lines ) then
lines.exitAtEnd:= false;
else
lines:= rec( lines:= lines, exitAtEnd:= false );
fi;
PAGER_BUILTIN( lines );
else
PAGER_EXTERNAL( lines );
fi;
end );
[ zur Elbe Produktseite wechseln0.34Quellennavigators
Analyse erneut starten
]
|
