# evennia.utils.evmore

EvMore - pager mechanism

This is a pager for displaying long texts and allows stepping up and down in the text (the name comes from the traditional ‘more’ unix command).

To use, simply pass the text through the EvMore object:

    from evennia.utils.evmore import EvMore

    text = some_long_text_output()
    EvMore(caller, text, always_page=False, session=None, justify_kwargs=None, **kwargs)

One can also use the convenience function msg from this module to avoid having to set up the EvMenu object manually:

    from evennia.utils import evmore

    text = some_long_text_output()
    evmore.msg(caller, text, always_page=False, session=None, justify_kwargs=None, **kwargs)

The always_page argument decides if the pager is used also if the text is not long enough to need to scroll, session is used to determine which session to relay to and justify_kwargs are kwargs to pass to utils.utils.justify in order to change the formatting of the text. The remaining **kwargs will be passed on to the caller.msg() construct every time the page is updated.

class `evennia.utils.evmore.``CmdMore`(**kwargs)

  Bases: `evennia.commands.command.Command`

  Manipulate the text paging. Catch no-input with aliases.

  `key` = '__noinput_command'
  `aliases` = ['end', 'a', 't', 'e', 'abort', 'p', 'top', 'previous', 'n', 'q', 'quit', 'next']
  `auto_help` = False
  `func`()

    Implement the command

  `help_category` = 'general'
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': 'end a t e abort p top previous n q quit next', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' end a t e abort p top previous n q quit next', 'tags': '', 'text': '\n Manipulate the text paging. Catch no-input with aliases.\n '}

class `evennia.utils.evmore.``CmdMoreExit`(**kwargs)

  Bases: `evennia.commands.command.Command`

  Any non-more command will exit the pager.

  `key` = '__nomatch_command'
  `func`()

    Exit pager and re-fire the failed command.

  `aliases` = []
  `help_category` = 'general'
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'general', 'key': '__nomatch_command', 'no_prefix': ' ', 'tags': '', 'text': '\n Any non-more command will exit the pager.\n\n '}

class `evennia.utils.evmore.``CmdSetMore`(cmdsetobj=None, key=None)

  Bases: `evennia.commands.cmdset.CmdSet`

  Stores the more command

  `key` = 'more_commands'
  `priority` = 110
  `mergetype` = 'Replace'
  `at_cmdset_creation`()

    Hook method - this should be overloaded in the inheriting class, and should take care of populating the cmdset by use of self.add().

  `path` = 'evennia.utils.evmore.CmdSetMore'

`evennia.utils.evmore.``queryset_maxsize`(qs)

class `evennia.utils.evmore.``EvMore`(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

  Bases: `object`

  The main pager object

  `__init__`(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

    Initialization of the EvMore pager.

    Parameters

      - caller (Object or Account) – Entity reading the text.

      - inp (str, EvTable, Paginator or iterator) –

        The text or data to put under paging.

        - If a string, paginage normally. If this text contains one or more \f format symbol, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

        - If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

        - Otherwise inp is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

      - always_page (bool, optional) – If False, the pager will only kick in if inp is too big to fit the screen.

      - session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

      - justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if inp is an EvTable.

      - justify_kwargs (dict, optional) – Keywords for the justify function. Used only if justify is True. If this is not set, default arguments will be used.

      - exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

      - exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

      - kwargs (any, optional) – These will be passed on to the caller.msg method.

    Examples

        super_long_text = " ... "
        EvMore(caller, super_long_text)

    Paginator

        from django.core.paginator import Paginator
        query = ObjectDB.objects.all()
        pages = Paginator(query, 10)  # 10 objs per page
        EvMore(caller, pages)

    Every page an EvTable

        from evennia import EvTable
        def _to_evtable(page):
            table = ... # convert page to a table
            return EvTable(*headers, table=table, ...)
        EvMore(caller, pages, page_formatter=_to_evtable)

  `display`(show_footer=True)

    Pretty-print the page.

  `page_top`()

    Display the top page

  `page_end`()

    Display the bottom page.

  `page_next`()

    Scroll the text to the next page. Quit if already at the end of the page.

  `page_back`()

    Scroll the text back up, at the most to the top.

  `page_quit`(quiet=False)

    Quit the pager

  `start`()

    Starts the pagination

  `paginator_index`(pageno)

    Paginate to specific, known index

  `paginator_slice`(pageno)

    Paginate by slice. This is done with an eye on memory efficiency (usually for querysets); to avoid fetching all objects at the same time.

  `paginator_django`(pageno)

    Paginate using the django queryset Paginator API. Note that his is indexed from 1.

  `init_evtable`(table)

    The input is an EvTable.

  `init_queryset`(qs)

    The input is a queryset

  `init_django_paginator`(pages)

    The input is a django Paginator object.

  `init_iterable`(inp)

    The input is something other than a string - convert to iterable of strings

  `init_f_str`(text)

    The input contains f markers. We use f to indicate the user wants to enforce their line breaks on their own. If so, we do no automatic line-breaking/justification at all.

    Parameters

      text (str) – The string to format with f-markers.

  `init_str`(text)

    The input is a string

  `init_pages`(inp)

    Initialize the pagination. By default, will analyze input type to determine how pagination automatically.

    Parameters

      inp (any) – Incoming data to be paginated. By default, handles pagination of strings, querysets, django.Paginator, EvTables and any iterables with strings.

    Notes

    If overridden, this method must perform the following actions:

    - read and re-store self._data (the incoming data set) if needed for pagination to work.

    - set self._npages to the total number of pages. Default is 1.

    - set self._paginator to a callable that will take a page number 1…N and return the data to display on that page (not any decorations or next/prev buttons). If only wanting to change the paginator, override self.paginator instead.

    - set self._page_formatter to a callable that will receive the page from self._paginator and format it with one element per line. Default is str. Or override self.page_formatter directly instead.

    By default, helper methods are called that perform these actions depending on supported inputs.

  `paginator`(pageno)

    Paginator. The data operated upon is in self._data.

    Parameters

      pageno (int) – The page number to view, from 0…N-1

    Returns

      str –

      The page to display (without any decorations, those are added

        by EvMore).

  `page_formatter`(page)

    Page formatter. Every page passes through this method. Override it to customize behavior per-page. A common use is to generate a new EvTable for every page (this is more efficient than to generate one huge EvTable across many pages and feed it into EvMore all at once).

    Parameters

      page (any) – A piece of data representing one page to display. This must

    Returns

      str –

      A ready-formatted page to display. Extra footer with help about

        switching to the next/prev page will be added automatically

`evennia.utils.evmore.``msg`(caller, text='', always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=True, **kwargs)

  > EvMore-supported version of msg, mimicking the normal msg method.

  Initialization of the EvMore pager.

  Parameters

    - caller (Object or Account) – Entity reading the text.

    - inp (str, EvTable, Paginator or iterator) –

      The text or data to put under paging.

      - If a string, paginage normally. If this text contains one or more \f format symbol, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

      - If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

      - Otherwise inp is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

    - always_page (bool, optional) – If False, the pager will only kick in if inp is too big to fit the screen.

    - session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

    - justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if inp is an EvTable.

    - justify_kwargs (dict, optional) – Keywords for the justify function. Used only if justify is True. If this is not set, default arguments will be used.

    - exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

    - exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

    - kwargs (any, optional) – These will be passed on to the caller.msg method.

  Examples

      super_long_text = " ... "
      EvMore(caller, super_long_text)

  Paginator

      from django.core.paginator import Paginator
      query = ObjectDB.objects.all()
      pages = Paginator(query, 10)  # 10 objs per page
      EvMore(caller, pages)

  Every page an EvTable

      from evennia import EvTable
      def _to_evtable(page):
          table = ... # convert page to a table
          return EvTable(*headers, table=table, ...)
      EvMore(caller, pages, page_formatter=_to_evtable)