lib/conutils/pager.c

/*
 * PROJECT:     ReactOS Console Utilities Library
 * LICENSE:     GPL-2.0+ (https://spdx.org/licenses/GPL-2.0+)
 * PURPOSE:     Console/terminal paging functionality.
 * COPYRIGHT:   Copyright 2017-2021 Hermes Belusca-Maito
 *              Copyright 2021 Katayama Hirofumi MZ
 */

/**
 * @file    pager.c
 * @ingroup ConUtils
 *
 * @brief   Console/terminal paging functionality.
 **/

/* FIXME: Temporary HACK before we cleanly support UNICODE functions */
#define UNICODE
#define _UNICODE

#include <windef.h>
#include <winbase.h>
// #include <winnls.h>
#include <wincon.h>  // Console APIs (only if kernel32 support included)
#include <winnls.h> // for WideCharToMultiByte
#include <strsafe.h>

#include "conutils.h"
#include "stream.h"
#include "screen.h"
#include "pager.h"

// Temporary HACK
#define CON_STREAM_WRITE    ConStreamWrite

#define CP_SHIFTJIS 932  // Japanese Shift-JIS
#define CP_HANGUL   949  // Korean Hangul/Wansung
#define CP_JOHAB    1361 // Korean Johab
#define CP_GB2312   936  // Chinese Simplified (GB2312)
#define CP_BIG5     950  // Chinese Traditional (Big5)

/* IsFarEastCP(CodePage) */
#define IsCJKCodePage(CodePage) \
    ((CodePage) == CP_SHIFTJIS || (CodePage) == CP_HANGUL || \
  /* (CodePage) == CP_JOHAB || */ \
     (CodePage) == CP_BIG5     || (CodePage) == CP_GB2312)

static inline INT
GetWidthOfCharCJK(
    IN UINT nCodePage,
    IN WCHAR ch)
{
    INT ret = WideCharToMultiByte(nCodePage, 0, &ch, 1, NULL, 0, NULL, NULL);
    if (ret == 0)
        ret = 1;
    else if (ret > 2)
        ret = 2;
    return ret;
}

/**
 * @brief   Retrieves a new text line, or continue fetching the current one.
 *
 * @remark  Manages setting Pager's CurrentLine, ichCurr, iEndLine, and the
 *          line cache (CachedLine, cchCachedLine). Other functions must not
 *          modify these values.
 **/
static BOOL
GetNextLine(
    IN OUT PCON_PAGER Pager,
    IN PCTCH TextBuff,
    IN SIZE_T cch)
{
    SIZE_T ich = Pager->ich;
    SIZE_T ichStart;
    SIZE_T cchLine;
    BOOL bCacheLine;

    Pager->ichCurr = 0;
    Pager->iEndLine = 0;

    /*
     * If we already had an existing line, then we can safely start a new one
     * and getting rid of any current cached line. Otherwise, we don't have
     * a current line and we may be caching a new one, in which case, continue
     * caching it until it becomes complete.
     */
    // INVESTIGATE: Do that only if (ichStart >= iEndLine) ??
    if (Pager->CurrentLine)
    {
        // ASSERT(Pager->CurrentLine == Pager->CachedLine);
        if (Pager->CachedLine)
        {
            HeapFree(GetProcessHeap(), 0, (PVOID)Pager->CachedLine);
            Pager->CachedLine = NULL;
            Pager->cchCachedLine = 0;
        }

        Pager->CurrentLine = NULL;
    }

    /* Nothing else to read if we are past the end of the buffer */
    if (ich >= cch)
    {
        /* If we have a pending cached line, terminate it now */
        if (Pager->CachedLine)
            goto TerminateLine;

        /* Otherwise, bail out */
        return FALSE;
    }

    /* Start a new line, or continue an existing one */
    ichStart = ich;

    /* Find where this line ends, looking for a NEWLINE character.
     * (NOTE: We cannot use strchr because the buffer is not NULL-terminated) */
    for (; ich < cch; ++ich)
    {
        if (TextBuff[ich] == TEXT('\n'))
        {
            ++ich;
            break;
        }
    }
    Pager->ich = ich;

    cchLine = (ich - ichStart);

    //
    // FIXME: Impose a maximum string limit when the line is cached, in order
    // not to potentially grow memory indefinitely. When the limit is reached,
    // terminate the line.
    //

    /*
     * If we have stopped because we have exhausted the text buffer
     * and we have not found an end-of-line character, this may mean
     * that the text line spans across different text buffers. If we
     * have been told so, cache this line: we will complete it during
     * the next call(s) and only then, display it.
     * Otherwise, consider the line to be terminated now.
     */
    bCacheLine = ((Pager->dwFlags & CON_PAGER_CACHE_INCOMPLETE_LINE) &&
                  (ich >= cch) && (TextBuff[ich - 1] != TEXT('\n')));

    /* Allocate, or re-allocate, the cached line buffer */
    if (bCacheLine && !Pager->CachedLine)
    {
        /* We start caching, allocate the cached line buffer */
        Pager->CachedLine = HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY,
                                      cchLine * sizeof(TCHAR));
        Pager->cchCachedLine = 0;

        if (!Pager->CachedLine)
        {
            SetLastError(ERROR_NOT_ENOUGH_MEMORY);
            return FALSE;
        }
    }
    else if (Pager->CachedLine)
    {
        /* We continue caching, re-allocate the cached line buffer */
        PVOID ptr = HeapReAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY,
                                (PVOID)Pager->CachedLine,
                                (Pager->cchCachedLine + cchLine) * sizeof(TCHAR));
        if (!ptr)
        {
            HeapFree(GetProcessHeap(), 0, (PVOID)Pager->CachedLine);
            Pager->CachedLine = NULL;
            Pager->cchCachedLine = 0;

            SetLastError(ERROR_NOT_ENOUGH_MEMORY);
            return FALSE;
        }
        Pager->CachedLine = ptr;
    }
    if (Pager->CachedLine)
    {
        /* Copy/append the text to the cached line buffer */
        RtlCopyMemory((PVOID)&Pager->CachedLine[Pager->cchCachedLine],
                      &TextBuff[ichStart],
                      cchLine * sizeof(TCHAR));
        Pager->cchCachedLine += cchLine;
    }
    if (bCacheLine)
    {
        /* The line is currently incomplete, don't proceed further for now */
        return FALSE;
    }

TerminateLine:
    /* The line should be complete now. If we have an existing cached line,
     * it has been completed by appending the remaining text to it. */

    /* We are starting a new line */
    Pager->ichCurr = 0;
    if (Pager->CachedLine)
    {
        Pager->iEndLine = Pager->cchCachedLine;
        Pager->CurrentLine = Pager->CachedLine;
    }
    else
    {
        Pager->iEndLine = cchLine;
        Pager->CurrentLine = &TextBuff[ichStart];
    }

    /* Increase only when we have got a NEWLINE */
    if ((Pager->iEndLine > 0) && (Pager->CurrentLine[Pager->iEndLine - 1] == TEXT('\n')))
        Pager->lineno++;

    return TRUE;
}

/**
 * @brief   Does the main paging work: fetching text lines and displaying them.
 **/
static BOOL
ConPagerWorker(
    IN PCON_PAGER Pager,
    IN PCTCH TextBuff,
    IN DWORD cch)
{
    const DWORD PageColumns = Pager->PageColumns;
    const DWORD ScrollRows = Pager->ScrollRows;

    BOOL bFinitePaging = ((PageColumns > 0) && (Pager->PageRows > 0));
    LONG nTabWidth = Pager->nTabWidth;

    PCTCH Line;
    SIZE_T ich;
    SIZE_T ichStart;
    SIZE_T iEndLine;
    DWORD iColumn = Pager->iColumn;

    UINT nCodePage = GetConsoleOutputCP();
    BOOL IsCJK = IsCJKCodePage(nCodePage);
    UINT nWidthOfChar = 1;
    BOOL IsDoubleWidthCharTrailing = FALSE;

    /* Normalize the tab width: if negative or too large,
     * cap it to the number of columns. */
    if (PageColumns > 0) // if (bFinitePaging)
    {
        if (nTabWidth < 0)
            nTabWidth = PageColumns - 1;
        else
            nTabWidth = min(nTabWidth, PageColumns - 1);
    }
    else
    {
        /* If no column width is known, default to 8 spaces if the
         * original value is negative; otherwise keep the current one. */
        if (nTabWidth < 0)
            nTabWidth = 8;
    }


    /* Continue displaying the previous line, if any, or start a new one */
    Line = Pager->CurrentLine;
    ichStart = Pager->ichCurr;
    iEndLine = Pager->iEndLine;

ProcessLine:

    /* Stop now if we have displayed more page lines than requested */
    if (bFinitePaging && (Pager->iLine >= ScrollRows))
        goto End;

    if (!Line || (ichStart >= iEndLine))
    {
        /* Start a new line */
        if (!GetNextLine(Pager, TextBuff, cch))
            goto End;

        Line = Pager->CurrentLine;
        ichStart = Pager->ichCurr;
        iEndLine = Pager->iEndLine;
    }
    else
    {
        /* Continue displaying the current line */
    }

    // ASSERT(Line && ((ichStart < iEndLine) || (ichStart == iEndLine && iEndLine == 0)));

    /* Determine whether this line segment (from the current position till the end) should be displayed */
    Pager->iColumn = iColumn;
    if (Pager->PagerLine && Pager->PagerLine(Pager, &Line[ichStart], iEndLine - ichStart))
    {
        iColumn = Pager->iColumn;

        /* Done with this line; start a new one */
        Pager->nSpacePending = 0; // And reset any pending space.
        ichStart = iEndLine;
        goto ProcessLine;
    }
    // else: Continue displaying the line.


    /* Print out any pending TAB expansion */
    if (Pager->nSpacePending > 0)
    {
ExpandTab:
        while (Pager->nSpacePending > 0)
        {
            /* Print filling spaces */
            CON_STREAM_WRITE(Pager->Screen->Stream, TEXT(" "), 1);
            --(Pager->nSpacePending);
            ++iColumn;

            /* Check whether we are going across the column */
            if ((PageColumns > 0) && (iColumn % PageColumns == 0))
            {
                // Pager->nSpacePending = 0; // <-- This is the mode of most text editors...

                /* Reposition the cursor to the next line, first column */
                if (!bFinitePaging || (PageColumns < Pager->Screen->csbi.dwSize.X))
                    CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);

                Pager->iLine++;

                /* Restart at the character */
                // ASSERT(ichStart == ich);
                goto ProcessLine;
            }
        }
    }


    /* Find, within this line segment (starting from its
     * beginning), until where we can print to the page. */
    for (ich = ichStart; ich < iEndLine; ++ich)
    {
        /* NEWLINE character */
        if (Line[ich] == TEXT('\n'))
        {
            /* We should stop now */
            // ASSERT(ich == iEndLine - 1);
            break;
        }

        /* TAB character */
        if (Line[ich] == TEXT('\t') &&
            (Pager->dwFlags & CON_PAGER_EXPAND_TABS))
        {
            /* We should stop now */
            break;
        }

        /* FORM-FEED character */
        if (Line[ich] == TEXT('\f') &&
            (Pager->dwFlags & CON_PAGER_EXPAND_FF))
        {
            /* We should stop now */
            break;
        }

        /* Other character - Handle double-width for CJK */

        if (IsCJK)
            nWidthOfChar = GetWidthOfCharCJK(nCodePage, Line[ich]);

        /* Care about CJK character presentation only when outputting
         * to a device where the number of columns is known. */
        if ((PageColumns > 0) && IsCJK)
        {
            IsDoubleWidthCharTrailing = (nWidthOfChar == 2) &&
                                        ((iColumn + 1) % PageColumns == 0);
            if (IsDoubleWidthCharTrailing)
            {
                /* Reserve this character for the next line */
                ++iColumn; // Count a blank instead.
                /* We should stop now */
                break;
            }
        }

        iColumn += nWidthOfChar;

        /* Check whether we are going across the column */
        if ((PageColumns > 0) && (iColumn % PageColumns == 0))
        {
            ++ich;
            break;
        }
    }

    /* Output the pending line segment */
    if (ich - ichStart > 0)
        CON_STREAM_WRITE(Pager->Screen->Stream, &Line[ichStart], ich - ichStart);

    /* Have we finished the line segment? */
    if (ich >= iEndLine)
    {
        /* Restart at the character */
        ichStart = ich;
        goto ProcessLine;
    }

    /* Handle special characters */

    /* NEWLINE character */
    if (Line[ich] == TEXT('\n'))
    {
        // ASSERT(ich == iEndLine - 1);

        /* Reposition the cursor to the next line, first column */
        CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);

        Pager->iLine++;
        iColumn = 0;

        /* Done with this line; start a new one */
        Pager->nSpacePending = 0; // And reset any pending space.
        ichStart = iEndLine;
        goto ProcessLine;
    }

    /* TAB character */
    if (Line[ich] == TEXT('\t') &&
        (Pager->dwFlags & CON_PAGER_EXPAND_TABS))
    {
        /* Perform TAB expansion, unless the tab width is zero */
        if (nTabWidth == 0)
        {
            ichStart = ++ich;
            goto ProcessLine;
        }

        ichStart = ++ich;
        /* Reset the number of spaces needed to develop this TAB character */
        Pager->nSpacePending = nTabWidth - (iColumn % nTabWidth);
        goto ExpandTab;
    }

    /* FORM-FEED character */
    if (Line[ich] == TEXT('\f') &&
        (Pager->dwFlags & CON_PAGER_EXPAND_FF))
    {
        if (bFinitePaging)
        {
            /* Clear until the end of the page */
            while (Pager->iLine < ScrollRows)
            {
                /* Call the user paging function in order to know
                 * whether we need to output the blank lines. */
                Pager->iColumn = iColumn;
                if (Pager->PagerLine && Pager->PagerLine(Pager, TEXT("\n"), 1))
                {
                    /* Only one blank line displayed, that counts in the line count */
                    Pager->iLine++;
                    break;
                }
                else
                {
                    CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);
                    Pager->iLine++;
                }
            }
        }
        else
        {
            /* Just output a FORM-FEED and a NEWLINE */
            CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\f\n"), 2);
            Pager->iLine++;
        }

        iColumn = 0;
        Pager->nSpacePending = 0; // And reset any pending space.

        /* Skip and restart past the character */
        ichStart = ++ich;
        goto ProcessLine;
    }

    /* If we output a double-width character that goes across the column,
     * fill with blank and display the character on the next line. */
    if (IsDoubleWidthCharTrailing)
    {
        IsDoubleWidthCharTrailing = FALSE; // Reset the flag.
        CON_STREAM_WRITE(Pager->Screen->Stream, TEXT(" "), 1);
        /* Fall back below */
    }

    /* Are we wrapping the line? */
    if ((PageColumns > 0) && (iColumn % PageColumns == 0))
    {
        /* Reposition the cursor to the next line, first column */
        if (!bFinitePaging || (PageColumns < Pager->Screen->csbi.dwSize.X))
            CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);

        Pager->iLine++;
    }

    /* Restart at the character */
    ichStart = ich;
    goto ProcessLine;


End:
    /*
     * We are exiting, either because we displayed all the required lines
     * (iLine >= ScrollRows), or, because we don't have more data to display.
     */

    Pager->ichCurr = ichStart;
    Pager->iColumn = iColumn;
    // INVESTIGATE: Can we get rid of CurrentLine here? // if (ichStart >= iEndLine) ...

    /* Return TRUE if we displayed all the required lines; FALSE otherwise */
    if (bFinitePaging && (Pager->iLine >= ScrollRows))
    {
        Pager->iLine = 0; /* Reset the count of lines being printed */
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}


/**
 * @name ConWritePaging
 *     Pages the contents of a user-specified character buffer on the screen.
 *
 * @param[in]   Pager
 *     Pager object that describes where the paged output is issued.
 *
 * @param[in]   PagePrompt
 *     A user-specific callback, called when a page has been displayed.
 *
 * @param[in]   StartPaging
 *     Set to TRUE for initializing the paging operation; FALSE during paging.
 *
 * @param[in]   szStr
 *     Pointer to the character buffer whose contents are to be paged.
 *
 * @param[in]   len
 *     Length of the character buffer pointed by @p szStr, specified
 *     in number of characters.
 *
 * @return
 *     TRUE when all the contents of the character buffer has been displayed;
 *     FALSE if the paging operation has been stopped (controlled via @p PagePrompt).
 **/
BOOL
ConWritePaging(
    IN PCON_PAGER Pager,
    IN PAGE_PROMPT PagePrompt,
    IN BOOL StartPaging,
    IN PCTCH szStr,
    IN DWORD len)
{
    CONSOLE_SCREEN_BUFFER_INFO csbi;
    BOOL bIsConsole;

    /* Parameters validation */
    if (!Pager)
        return FALSE;

    /* Get the size of the visual screen that can be printed to */
    bIsConsole = ConGetScreenInfo(Pager->Screen, &csbi);
    if (bIsConsole)
    {
        /* Calculate the console screen extent */
        Pager->PageColumns = csbi.dwSize.X;
        Pager->PageRows = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
    }
    else
    {
        /* We assume it's a file handle */
        Pager->PageColumns = 0;
        Pager->PageRows = 0;
    }

    if (StartPaging)
    {
        if (bIsConsole && (Pager->PageRows >= 2))
        {
            /* Reset to display one page by default */
            Pager->ScrollRows = Pager->PageRows - 1;
        }
        else
        {
            /* File output, or single line: all lines are displayed at once; reset to a default value */
            Pager->ScrollRows = 0;
        }

        /* Reset the internal data buffer */
        Pager->CachedLine = NULL;
        Pager->cchCachedLine = 0;

        /* Reset the paging state */
        Pager->CurrentLine = NULL;
        Pager->ichCurr = 0;
        Pager->iEndLine = 0;
        Pager->nSpacePending = 0;
        Pager->iColumn = 0;
        Pager->iLine = 0;
        Pager->lineno = 0;
    }

    /* Reset the reading index in the user-provided source buffer */
    Pager->ich = 0;

    /* Run the pager even when the user-provided source buffer is
     * empty, in case we need to flush any remaining cached line. */
    if (!Pager->CachedLine)
    {
        /* No cached line, bail out now */
        if (len == 0 || szStr == NULL)
            return TRUE;
    }

    while (ConPagerWorker(Pager, szStr, len))
    {
        /* Prompt the user only when we display to a console and the screen
         * is not too small: at least one line for the actual paged text and
         * one line for the prompt. */
        if (bIsConsole && (Pager->PageRows >= 2))
        {
            /* Reset to display one page by default */
            Pager->ScrollRows = Pager->PageRows - 1;

            /* Prompt the user; give him some values for statistics */
            // FIXME: Doesn't reflect what's currently being displayed.
            if (!PagePrompt(Pager, Pager->ich, len))
                return FALSE;
        }

        /* If we display to a console, recalculate its screen extent
         * in case the user has redimensioned it during the prompt. */
        if (bIsConsole && ConGetScreenInfo(Pager->Screen, &csbi))
        {
            Pager->PageColumns = csbi.dwSize.X;
            Pager->PageRows = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
        }
    }

    return TRUE;
}

BOOL
ConPutsPaging(
    IN PCON_PAGER Pager,
    IN PAGE_PROMPT PagePrompt,
    IN BOOL StartPaging,
    IN PCTSTR szStr)
{
    DWORD len;

    /* Return if no string has been given */
    if (szStr == NULL)
        return TRUE;

    len = wcslen(szStr);
    return ConWritePaging(Pager, PagePrompt, StartPaging, szStr, len);
}

BOOL
ConResPagingEx(
    IN PCON_PAGER Pager,
    IN PAGE_PROMPT PagePrompt,
    IN BOOL StartPaging,
    IN HINSTANCE hInstance OPTIONAL,
    IN UINT uID)
{
    INT Len;
    PCWSTR szStr = NULL;

    Len = K32LoadStringW(hInstance, uID, (PWSTR)&szStr, 0);
    if (szStr && Len)
        return ConWritePaging(Pager, PagePrompt, StartPaging, szStr, Len);
    else
        return TRUE;
}

BOOL
ConResPaging(
    IN PCON_PAGER Pager,
    IN PAGE_PROMPT PagePrompt,
    IN BOOL StartPaging,
    IN UINT uID)
{
    return ConResPagingEx(Pager, PagePrompt, StartPaging,
                          NULL /*GetModuleHandleW(NULL)*/, uID);
}

/* EOF */