PageRenderTime 491ms CodeModel.GetById 242ms app.highlight 140ms RepoModel.GetById 91ms app.codeStats 1ms

/Doc/library/curses.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 1693 lines | 1159 code | 534 blank | 0 comment | 0 complexity | 674a04f7a5475070edd90ae3cd22d8af MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1
   2:mod:`curses` --- Terminal handling for character-cell displays
   3===============================================================
   4
   5.. module:: curses
   6   :synopsis: An interface to the curses library, providing portable terminal handling.
   7.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
   8.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
   9
  10
  11.. versionchanged:: 1.6
  12   Added support for the ``ncurses`` library and converted to a package.
  13
  14The :mod:`curses` module provides an interface to the curses library, the
  15de-facto standard for portable advanced terminal handling.
  16
  17While curses is most widely used in the Unix environment, versions are available
  18for DOS, OS/2, and possibly other systems as well.  This extension module is
  19designed to match the API of ncurses, an open-source curses library hosted on
  20Linux and the BSD variants of Unix.
  21
  22.. note::
  23
  24   Since version 5.4, the ncurses library decides how to interpret non-ASCII data
  25   using the ``nl_langinfo`` function.  That means that you have to call
  26   :func:`locale.setlocale` in the application and encode Unicode strings
  27   using one of the system's available encodings.  This example uses the
  28   system's default encoding::
  29
  30      import locale
  31      locale.setlocale(locale.LC_ALL, '')
  32      code = locale.getpreferredencoding()
  33
  34   Then use *code* as the encoding for :meth:`str.encode` calls.
  35
  36.. seealso::
  37
  38   Module :mod:`curses.ascii`
  39      Utilities for working with ASCII characters, regardless of your locale settings.
  40
  41   Module :mod:`curses.panel`
  42      A panel stack extension that adds depth to  curses windows.
  43
  44   Module :mod:`curses.textpad`
  45      Editable text widget for curses supporting  :program:`Emacs`\ -like bindings.
  46
  47   Module :mod:`curses.wrapper`
  48      Convenience function to ensure proper terminal setup and resetting on
  49      application entry and exit.
  50
  51   :ref:`curses-howto`
  52      Tutorial material on using curses with Python, by Andrew Kuchling and Eric
  53      Raymond.
  54
  55   The :file:`Demo/curses/` directory in the Python source distribution contains
  56   some example programs using the curses bindings provided by this module.
  57
  58
  59.. _curses-functions:
  60
  61Functions
  62---------
  63
  64The module :mod:`curses` defines the following exception:
  65
  66
  67.. exception:: error
  68
  69   Exception raised when a curses library function returns an error.
  70
  71.. note::
  72
  73   Whenever *x* or *y* arguments to a function or a method are optional, they
  74   default to the current cursor location. Whenever *attr* is optional, it defaults
  75   to :const:`A_NORMAL`.
  76
  77The module :mod:`curses` defines the following functions:
  78
  79
  80.. function:: baudrate()
  81
  82   Returns the output speed of the terminal in bits per second.  On software
  83   terminal emulators it will have a fixed high value. Included for historical
  84   reasons; in former times, it was used to  write output loops for time delays and
  85   occasionally to change interfaces depending on the line speed.
  86
  87
  88.. function:: beep()
  89
  90   Emit a short attention sound.
  91
  92
  93.. function:: can_change_color()
  94
  95   Returns true or false, depending on whether the programmer can change the colors
  96   displayed by the terminal.
  97
  98
  99.. function:: cbreak()
 100
 101   Enter cbreak mode.  In cbreak mode (sometimes called "rare" mode) normal tty
 102   line buffering is turned off and characters are available to be read one by one.
 103   However, unlike raw mode, special characters (interrupt, quit, suspend, and flow
 104   control) retain their effects on the tty driver and calling program.  Calling
 105   first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode.
 106
 107
 108.. function:: color_content(color_number)
 109
 110   Returns the intensity of the red, green, and blue (RGB) components in the color
 111   *color_number*, which must be between ``0`` and :const:`COLORS`.  A 3-tuple is
 112   returned, containing the R,G,B values for the given color, which will be between
 113   ``0`` (no component) and ``1000`` (maximum amount of component).
 114
 115
 116.. function:: color_pair(color_number)
 117
 118   Returns the attribute value for displaying text in the specified color.  This
 119   attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`,
 120   and the other :const:`A_\*` attributes.  :func:`pair_number` is the counterpart
 121   to this function.
 122
 123
 124.. function:: curs_set(visibility)
 125
 126   Sets the cursor state.  *visibility* can be set to 0, 1, or 2, for invisible,
 127   normal, or very visible.  If the terminal supports the visibility requested, the
 128   previous cursor state is returned; otherwise, an exception is raised.  On many
 129   terminals, the "visible" mode is an underline cursor and the "very visible" mode
 130   is a block cursor.
 131
 132
 133.. function:: def_prog_mode()
 134
 135   Saves the current terminal mode as the "program" mode, the mode when the running
 136   program is using curses.  (Its counterpart is the "shell" mode, for when the
 137   program is not in curses.)  Subsequent calls to :func:`reset_prog_mode` will
 138   restore this mode.
 139
 140
 141.. function:: def_shell_mode()
 142
 143   Saves the current terminal mode as the "shell" mode, the mode when the running
 144   program is not using curses.  (Its counterpart is the "program" mode, when the
 145   program is using curses capabilities.) Subsequent calls to
 146   :func:`reset_shell_mode` will restore this mode.
 147
 148
 149.. function:: delay_output(ms)
 150
 151   Inserts an *ms* millisecond pause in output.
 152
 153
 154.. function:: doupdate()
 155
 156   Update the physical screen.  The curses library keeps two data structures, one
 157   representing the current physical screen contents and a virtual screen
 158   representing the desired next state.  The :func:`doupdate` ground updates the
 159   physical screen to match the virtual screen.
 160
 161   The virtual screen may be updated by a :meth:`noutrefresh` call after write
 162   operations such as :meth:`addstr` have been performed on a window.  The normal
 163   :meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`;
 164   if you have to update multiple windows, you can speed performance and perhaps
 165   reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows,
 166   followed by a single :func:`doupdate`.
 167
 168
 169.. function:: echo()
 170
 171   Enter echo mode.  In echo mode, each character input is echoed to the screen as
 172   it is entered.
 173
 174
 175.. function:: endwin()
 176
 177   De-initialize the library, and return terminal to normal status.
 178
 179
 180.. function:: erasechar()
 181
 182   Returns the user's current erase character.  Under Unix operating systems this
 183   is a property of the controlling tty of the curses program, and is not set by
 184   the curses library itself.
 185
 186
 187.. function:: filter()
 188
 189   The :func:`filter` routine, if used, must be called before :func:`initscr` is
 190   called.  The effect is that, during those calls, LINES is set to 1; the
 191   capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home
 192   string is set to the value of cr. The effect is that the cursor is confined to
 193   the current line, and so are screen updates.  This may be used for enabling
 194   character-at-a-time  line editing without touching the rest of the screen.
 195
 196
 197.. function:: flash()
 198
 199   Flash the screen.  That is, change it to reverse-video and then change it back
 200   in a short interval.  Some people prefer such as 'visible bell' to the audible
 201   attention signal produced by :func:`beep`.
 202
 203
 204.. function:: flushinp()
 205
 206   Flush all input buffers.  This throws away any  typeahead  that  has been typed
 207   by the user and has not yet been processed by the program.
 208
 209
 210.. function:: getmouse()
 211
 212   After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
 213   method should be call to retrieve the queued mouse event, represented as a
 214   5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish
 215   multiple devices, and *x*, *y*, *z* are the event's coordinates.  (*z* is
 216   currently unused.).  *bstate* is an integer value whose bits will be set to
 217   indicate the type of event, and will be the bitwise OR of one or more of the
 218   following constants, where *n* is the button number from 1 to 4:
 219   :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,
 220   :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,
 221   :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.
 222
 223
 224.. function:: getsyx()
 225
 226   Returns the current coordinates of the virtual screen cursor in y and x.  If
 227   leaveok is currently true, then -1,-1 is returned.
 228
 229
 230.. function:: getwin(file)
 231
 232   Reads window related data stored in the file by an earlier :func:`putwin` call.
 233   The routine then creates and initializes a new window using that data, returning
 234   the new window object.
 235
 236
 237.. function:: has_colors()
 238
 239   Returns true if the terminal can display colors; otherwise, it returns false.
 240
 241
 242.. function:: has_ic()
 243
 244   Returns true if the terminal has insert- and delete- character capabilities.
 245   This function is included for historical reasons only, as all modern software
 246   terminal emulators have such capabilities.
 247
 248
 249.. function:: has_il()
 250
 251   Returns true if the terminal has insert- and delete-line  capabilities,  or  can
 252   simulate  them  using scrolling regions. This function is included for
 253   historical reasons only, as all modern software terminal emulators have such
 254   capabilities.
 255
 256
 257.. function:: has_key(ch)
 258
 259   Takes a key value *ch*, and returns true if the current terminal type recognizes
 260   a key with that value.
 261
 262
 263.. function:: halfdelay(tenths)
 264
 265   Used for half-delay mode, which is similar to cbreak mode in that characters
 266   typed by the user are immediately available to the program. However, after
 267   blocking for *tenths* tenths of seconds, an exception is raised if nothing has
 268   been typed.  The value of *tenths* must be a number between 1 and 255.  Use
 269   :func:`nocbreak` to leave half-delay mode.
 270
 271
 272.. function:: init_color(color_number, r, g, b)
 273
 274   Changes the definition of a color, taking the number of the color to be changed
 275   followed by three RGB values (for the amounts of red, green, and blue
 276   components).  The value of *color_number* must be between ``0`` and
 277   :const:`COLORS`.  Each of *r*, *g*, *b*, must be a value between ``0`` and
 278   ``1000``.  When :func:`init_color` is used, all occurrences of that color on the
 279   screen immediately change to the new definition.  This function is a no-op on
 280   most terminals; it is active only if :func:`can_change_color` returns ``1``.
 281
 282
 283.. function:: init_pair(pair_number, fg, bg)
 284
 285   Changes the definition of a color-pair.  It takes three arguments: the number of
 286   the color-pair to be changed, the foreground color number, and the background
 287   color number.  The value of *pair_number* must be between ``1`` and
 288   ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot
 289   be changed).  The value of *fg* and *bg* arguments must be between ``0`` and
 290   :const:`COLORS`.  If the color-pair was previously initialized, the screen is
 291   refreshed and all occurrences of that color-pair are changed to the new
 292   definition.
 293
 294
 295.. function:: initscr()
 296
 297   Initialize the library. Returns a :class:`WindowObject` which represents the
 298   whole screen.
 299
 300   .. note::
 301
 302      If there is an error opening the terminal, the underlying curses library may
 303      cause the interpreter to exit.
 304
 305
 306.. function:: isendwin()
 307
 308   Returns true if :func:`endwin` has been called (that is, the  curses library has
 309   been deinitialized).
 310
 311
 312.. function:: keyname(k)
 313
 314   Return the name of the key numbered *k*.  The name of a key generating printable
 315   ASCII character is the key's character.  The name of a control-key combination
 316   is a two-character string consisting of a caret followed by the corresponding
 317   printable ASCII character.  The name of an alt-key combination (128-255) is a
 318   string consisting of the prefix 'M-' followed by the name of the corresponding
 319   ASCII character.
 320
 321
 322.. function:: killchar()
 323
 324   Returns the user's current line kill character. Under Unix operating systems
 325   this is a property of the controlling tty of the curses program, and is not set
 326   by the curses library itself.
 327
 328
 329.. function:: longname()
 330
 331   Returns a string containing the terminfo long name field describing the current
 332   terminal.  The maximum length of a verbose description is 128 characters.  It is
 333   defined only after the call to :func:`initscr`.
 334
 335
 336.. function:: meta(yes)
 337
 338   If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0,  allow only
 339   7-bit chars.
 340
 341
 342.. function:: mouseinterval(interval)
 343
 344   Sets the maximum time in milliseconds that can elapse between press and release
 345   events in order for them to be recognized as a click, and returns the previous
 346   interval value.  The default value is 200 msec, or one fifth of a second.
 347
 348
 349.. function:: mousemask(mousemask)
 350
 351   Sets the mouse events to be reported, and returns a tuple ``(availmask,
 352   oldmask)``.   *availmask* indicates which of the specified mouse events can be
 353   reported; on complete failure it returns 0.  *oldmask* is the previous value of
 354   the given window's mouse event mask.  If this function is never called, no mouse
 355   events are ever reported.
 356
 357
 358.. function:: napms(ms)
 359
 360   Sleep for *ms* milliseconds.
 361
 362
 363.. function:: newpad(nlines, ncols)
 364
 365   Creates and returns a pointer to a new pad data structure with the given number
 366   of lines and columns.  A pad is returned as a window object.
 367
 368   A pad is like a window, except that it is not restricted by the screen size, and
 369   is not necessarily associated with a particular part of the screen.  Pads can be
 370   used when a large window is needed, and only a part of the window will be on the
 371   screen at one time.  Automatic refreshes of pads (such as from scrolling or
 372   echoing of input) do not occur.  The :meth:`refresh` and :meth:`noutrefresh`
 373   methods of a pad require 6 arguments to specify the part of the pad to be
 374   displayed and the location on the screen to be used for the display. The
 375   arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p
 376   arguments refer to the upper left corner of the pad region to be displayed and
 377   the s arguments define a clipping box on the screen within which the pad region
 378   is to be displayed.
 379
 380
 381.. function:: newwin([nlines, ncols,] begin_y, begin_x)
 382
 383   Return a new window, whose left-upper corner is at  ``(begin_y, begin_x)``, and
 384   whose height/width is  *nlines*/*ncols*.
 385
 386   By default, the window will extend from the  specified position to the lower
 387   right corner of the screen.
 388
 389
 390.. function:: nl()
 391
 392   Enter newline mode.  This mode translates the return key into newline on input,
 393   and translates newline into return and line-feed on output. Newline mode is
 394   initially on.
 395
 396
 397.. function:: nocbreak()
 398
 399   Leave cbreak mode.  Return to normal "cooked" mode with line buffering.
 400
 401
 402.. function:: noecho()
 403
 404   Leave echo mode.  Echoing of input characters is turned off.
 405
 406
 407.. function:: nonl()
 408
 409   Leave newline mode.  Disable translation of return into newline on input, and
 410   disable low-level translation of newline into newline/return on output (but this
 411   does not change the behavior of ``addch('\n')``, which always does the
 412   equivalent of return and line feed on the virtual screen).  With translation
 413   off, curses can sometimes speed up vertical motion a little; also, it will be
 414   able to detect the return key on input.
 415
 416
 417.. function:: noqiflush()
 418
 419   When the noqiflush routine is used, normal flush of input and output queues
 420   associated with the INTR, QUIT and SUSP characters will not be done.  You may
 421   want to call :func:`noqiflush` in a signal handler if you want output to
 422   continue as though the interrupt had not occurred, after the handler exits.
 423
 424
 425.. function:: noraw()
 426
 427   Leave raw mode. Return to normal "cooked" mode with line buffering.
 428
 429
 430.. function:: pair_content(pair_number)
 431
 432   Returns a tuple ``(fg, bg)`` containing the colors for the requested color pair.
 433   The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``.
 434
 435
 436.. function:: pair_number(attr)
 437
 438   Returns the number of the color-pair set by the attribute value *attr*.
 439   :func:`color_pair` is the counterpart to this function.
 440
 441
 442.. function:: putp(string)
 443
 444   Equivalent to ``tputs(str, 1, putchar)``; emits the value of a specified
 445   terminfo capability for the current terminal.  Note that the output of putp
 446   always goes to standard output.
 447
 448
 449.. function:: qiflush( [flag] )
 450
 451   If *flag* is false, the effect is the same as calling :func:`noqiflush`. If
 452   *flag* is true, or no argument is provided, the queues will be flushed when
 453   these control characters are read.
 454
 455
 456.. function:: raw()
 457
 458   Enter raw mode.  In raw mode, normal line buffering and  processing of
 459   interrupt, quit, suspend, and flow control keys are turned off; characters are
 460   presented to curses input functions one by one.
 461
 462
 463.. function:: reset_prog_mode()
 464
 465   Restores the  terminal  to "program" mode, as previously saved  by
 466   :func:`def_prog_mode`.
 467
 468
 469.. function:: reset_shell_mode()
 470
 471   Restores the  terminal  to "shell" mode, as previously saved  by
 472   :func:`def_shell_mode`.
 473
 474
 475.. function:: setsyx(y, x)
 476
 477   Sets the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
 478   leaveok is set.
 479
 480
 481.. function:: setupterm([termstr, fd])
 482
 483   Initializes the terminal.  *termstr* is a string giving the terminal name; if
 484   omitted, the value of the TERM environment variable will be used.  *fd* is the
 485   file descriptor to which any initialization sequences will be sent; if not
 486   supplied, the file descriptor for ``sys.stdout`` will be used.
 487
 488
 489.. function:: start_color()
 490
 491   Must be called if the programmer wants to use colors, and before any other color
 492   manipulation routine is called.  It is good practice to call this routine right
 493   after :func:`initscr`.
 494
 495   :func:`start_color` initializes eight basic colors (black, red,  green, yellow,
 496   blue, magenta, cyan, and white), and two global variables in the :mod:`curses`
 497   module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number
 498   of colors and color-pairs the terminal can support.  It also restores the colors
 499   on the terminal to the values they had when the terminal was just turned on.
 500
 501
 502.. function:: termattrs()
 503
 504   Returns a logical OR of all video attributes supported by the terminal.  This
 505   information is useful when a curses program needs complete control over the
 506   appearance of the screen.
 507
 508
 509.. function:: termname()
 510
 511   Returns the value of the environment variable TERM, truncated to 14 characters.
 512
 513
 514.. function:: tigetflag(capname)
 515
 516   Returns the value of the Boolean capability corresponding to the terminfo
 517   capability name *capname*.  The value ``-1`` is returned if *capname* is not a
 518   Boolean capability, or ``0`` if it is canceled or absent from the terminal
 519   description.
 520
 521
 522.. function:: tigetnum(capname)
 523
 524   Returns the value of the numeric capability corresponding to the terminfo
 525   capability name *capname*.  The value ``-2`` is returned if *capname* is not a
 526   numeric capability, or ``-1`` if it is canceled or absent from the terminal
 527   description.
 528
 529
 530.. function:: tigetstr(capname)
 531
 532   Returns the value of the string capability corresponding to the terminfo
 533   capability name *capname*.  ``None`` is returned if *capname* is not a string
 534   capability, or is canceled or absent from the terminal description.
 535
 536
 537.. function:: tparm(str[,...])
 538
 539   Instantiates the string *str* with the supplied parameters, where  *str* should
 540   be a parameterized string obtained from the terminfo  database.  E.g.
 541   ``tparm(tigetstr("cup"), 5, 3)`` could result in  ``'\033[6;4H'``, the exact
 542   result depending on terminal type.
 543
 544
 545.. function:: typeahead(fd)
 546
 547   Specifies that the file descriptor *fd* be used for typeahead checking.  If *fd*
 548   is ``-1``, then no typeahead checking is done.
 549
 550   The curses library does "line-breakout optimization" by looking for typeahead
 551   periodically while updating the screen.  If input is found, and it is coming
 552   from a tty, the current update is postponed until refresh or doupdate is called
 553   again, allowing faster response to commands typed in advance. This function
 554   allows specifying a different file descriptor for typeahead checking.
 555
 556
 557.. function:: unctrl(ch)
 558
 559   Returns a string which is a printable representation of the character *ch*.
 560   Control characters are displayed as a caret followed by the character, for
 561   example as ``^C``. Printing characters are left as they are.
 562
 563
 564.. function:: ungetch(ch)
 565
 566   Push *ch* so the next :meth:`getch` will return it.
 567
 568   .. note::
 569
 570      Only one *ch* can be pushed before :meth:`getch` is called.
 571
 572
 573.. function:: ungetmouse(id, x, y, z, bstate)
 574
 575   Push a :const:`KEY_MOUSE` event onto the input queue, associating the given
 576   state data with it.
 577
 578
 579.. function:: use_env(flag)
 580
 581   If used, this function should be called before :func:`initscr` or newterm are
 582   called.  When *flag* is false, the values of lines and columns specified in the
 583   terminfo database will be used, even if environment variables :envvar:`LINES`
 584   and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a
 585   window (in which case default behavior would be to use the window size if
 586   :envvar:`LINES` and :envvar:`COLUMNS` are not set).
 587
 588
 589.. function:: use_default_colors()
 590
 591   Allow use of default values for colors on terminals supporting this feature. Use
 592   this to support transparency in your application.  The default color is assigned
 593   to the color number -1. After calling this function,  ``init_pair(x,
 594   curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red
 595   foreground color on the default background.
 596
 597
 598.. _curses-window-objects:
 599
 600Window Objects
 601--------------
 602
 603Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
 604the following methods:
 605
 606
 607.. method:: window.addch([y, x,] ch[, attr])
 608
 609   .. note::
 610
 611      A *character* means a C character (an ASCII code), rather then a Python
 612      character (a string of length 1). (This note is true whenever the documentation
 613      mentions a character.) The builtin :func:`ord` is handy for conveying strings to
 614      codes.
 615
 616   Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
 617   character previously painter at that location.  By default, the character
 618   position and attributes are the current settings for the window object.
 619
 620
 621.. method:: window.addnstr([y, x,] str, n[, attr])
 622
 623   Paint at most *n* characters of the  string *str* at ``(y, x)`` with attributes
 624   *attr*, overwriting anything previously on the display.
 625
 626
 627.. method:: window.addstr([y, x,] str[, attr])
 628
 629   Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
 630   anything previously on the display.
 631
 632
 633.. method:: window.attroff(attr)
 634
 635   Remove attribute *attr* from the "background" set applied to all writes to the
 636   current window.
 637
 638
 639.. method:: window.attron(attr)
 640
 641   Add attribute *attr* from the "background" set applied to all writes to the
 642   current window.
 643
 644
 645.. method:: window.attrset(attr)
 646
 647   Set the "background" set of attributes to *attr*.  This set is initially 0 (no
 648   attributes).
 649
 650
 651.. method:: window.bkgd(ch[, attr])
 652
 653   Sets the background property of the window to the character *ch*, with
 654   attributes *attr*.  The change is then applied to every character position in
 655   that window:
 656
 657   * The attribute of every character in the window  is changed to the new
 658     background attribute.
 659
 660   * Wherever  the  former background character appears, it is changed to the new
 661     background character.
 662
 663
 664.. method:: window.bkgdset(ch[, attr])
 665
 666   Sets the window's background.  A window's background consists of a character and
 667   any combination of attributes.  The attribute part of the background is combined
 668   (OR'ed) with all non-blank characters that are written into the window.  Both
 669   the character and attribute parts of the background are combined with the blank
 670   characters.  The background becomes a property of the character and moves with
 671   the character through any scrolling and insert/delete line/character operations.
 672
 673
 674.. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
 675
 676   Draw a border around the edges of the window. Each parameter specifies  the
 677   character to use for a specific part of the border; see the table below for more
 678   details.  The characters can be specified as integers or as one-character
 679   strings.
 680
 681   .. note::
 682
 683      A ``0`` value for any parameter will cause the default character to be used for
 684      that parameter.  Keyword parameters can *not* be used.  The defaults are listed
 685      in this table:
 686
 687   +-----------+---------------------+-----------------------+
 688   | Parameter | Description         | Default value         |
 689   +===========+=====================+=======================+
 690   | *ls*      | Left side           | :const:`ACS_VLINE`    |
 691   +-----------+---------------------+-----------------------+
 692   | *rs*      | Right side          | :const:`ACS_VLINE`    |
 693   +-----------+---------------------+-----------------------+
 694   | *ts*      | Top                 | :const:`ACS_HLINE`    |
 695   +-----------+---------------------+-----------------------+
 696   | *bs*      | Bottom              | :const:`ACS_HLINE`    |
 697   +-----------+---------------------+-----------------------+
 698   | *tl*      | Upper-left corner   | :const:`ACS_ULCORNER` |
 699   +-----------+---------------------+-----------------------+
 700   | *tr*      | Upper-right corner  | :const:`ACS_URCORNER` |
 701   +-----------+---------------------+-----------------------+
 702   | *bl*      | Bottom-left corner  | :const:`ACS_LLCORNER` |
 703   +-----------+---------------------+-----------------------+
 704   | *br*      | Bottom-right corner | :const:`ACS_LRCORNER` |
 705   +-----------+---------------------+-----------------------+
 706
 707
 708.. method:: window.box([vertch, horch])
 709
 710   Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
 711   bs are *horch*.  The default corner characters are always used by this function.
 712
 713
 714.. method:: window.chgat([y, x, ] [num,] attr)
 715
 716   Sets the attributes of *num* characters at the current cursor position, or at
 717   position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
 718   the attribute will  be set on all the characters to the end of the line.  This
 719   function does not move the cursor. The changed line will be touched using the
 720   :meth:`touchline` method so that the contents will be redisplayed by the next
 721   window refresh.
 722
 723
 724.. method:: window.clear()
 725
 726   Like :meth:`erase`, but also causes the whole window to be repainted upon next
 727   call to :meth:`refresh`.
 728
 729
 730.. method:: window.clearok(yes)
 731
 732   If *yes* is 1, the next call to :meth:`refresh` will clear the window
 733   completely.
 734
 735
 736.. method:: window.clrtobot()
 737
 738   Erase from cursor to the end of the window: all lines below the cursor are
 739   deleted, and then the equivalent of :meth:`clrtoeol` is performed.
 740
 741
 742.. method:: window.clrtoeol()
 743
 744   Erase from cursor to the end of the line.
 745
 746
 747.. method:: window.cursyncup()
 748
 749   Updates the current cursor position of all the ancestors of the window to
 750   reflect the current cursor position of the window.
 751
 752
 753.. method:: window.delch([y, x])
 754
 755   Delete any character at ``(y, x)``.
 756
 757
 758.. method:: window.deleteln()
 759
 760   Delete the line under the cursor. All following lines are moved up by 1 line.
 761
 762
 763.. method:: window.derwin([nlines, ncols,] begin_y, begin_x)
 764
 765   An abbreviation for "derive window", :meth:`derwin` is the same as calling
 766   :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin
 767   of the window, rather than relative to the entire screen.  Returns a window
 768   object for the derived window.
 769
 770
 771.. method:: window.echochar(ch[, attr])
 772
 773   Add character *ch* with attribute *attr*, and immediately  call :meth:`refresh`
 774   on the window.
 775
 776
 777.. method:: window.enclose(y, x)
 778
 779   Tests whether the given pair of screen-relative character-cell coordinates are
 780   enclosed by the given window, returning true or false.  It is useful for
 781   determining what subset of the screen windows enclose the location of a mouse
 782   event.
 783
 784
 785.. method:: window.erase()
 786
 787   Clear the window.
 788
 789
 790.. method:: window.getbegyx()
 791
 792   Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.
 793
 794
 795.. method:: window.getch([y, x])
 796
 797   Get a character. Note that the integer returned does *not* have to be in ASCII
 798   range: function keys, keypad keys and so on return numbers higher than 256. In
 799   no-delay mode, -1 is returned if there is  no input.
 800
 801
 802.. method:: window.getkey([y, x])
 803
 804   Get a character, returning a string instead of an integer, as :meth:`getch`
 805   does. Function keys, keypad keys and so on return a multibyte string containing
 806   the key name.  In no-delay mode, an exception is raised if there is no input.
 807
 808
 809.. method:: window.getmaxyx()
 810
 811   Return a tuple ``(y, x)`` of the height and width of the window.
 812
 813
 814.. method:: window.getparyx()
 815
 816   Returns the beginning coordinates of this window relative to its parent window
 817   into two integer variables y and x.  Returns ``-1,-1`` if this window has no
 818   parent.
 819
 820
 821.. method:: window.getstr([y, x])
 822
 823   Read a string from the user, with primitive line editing capacity.
 824
 825
 826.. method:: window.getyx()
 827
 828   Return a tuple ``(y, x)`` of current cursor position  relative to the window's
 829   upper-left corner.
 830
 831
 832.. method:: window.hline([y, x,] ch, n)
 833
 834   Display a horizontal line starting at ``(y, x)`` with length *n* consisting of
 835   the character *ch*.
 836
 837
 838.. method:: window.idcok(flag)
 839
 840   If *flag* is false, curses no longer considers using the hardware insert/delete
 841   character feature of the terminal; if *flag* is true, use of character insertion
 842   and deletion is enabled.  When curses is first initialized, use of character
 843   insert/delete is enabled by default.
 844
 845
 846.. method:: window.idlok(yes)
 847
 848   If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
 849   editing facilities. Otherwise, line insertion/deletion are disabled.
 850
 851
 852.. method:: window.immedok(flag)
 853
 854   If *flag* is true, any change in the window image automatically causes the
 855   window to be refreshed; you no longer have to call :meth:`refresh` yourself.
 856   However, it may degrade performance considerably, due to repeated calls to
 857   wrefresh.  This option is disabled by default.
 858
 859
 860.. method:: window.inch([y, x])
 861
 862   Return the character at the given position in the window. The bottom 8 bits are
 863   the character proper, and upper bits are the attributes.
 864
 865
 866.. method:: window.insch([y, x,] ch[, attr])
 867
 868   Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
 869   position *x* right by one character.
 870
 871
 872.. method:: window.insdelln(nlines)
 873
 874   Inserts *nlines* lines into the specified window above the current line.  The
 875   *nlines* bottom lines are lost.  For negative *nlines*, delete *nlines* lines
 876   starting with the one under the cursor, and move the remaining lines up.  The
 877   bottom *nlines* lines are cleared.  The current cursor position remains the
 878   same.
 879
 880
 881.. method:: window.insertln()
 882
 883   Insert a blank line under the cursor. All following lines are moved down by 1
 884   line.
 885
 886
 887.. method:: window.insnstr([y, x,] str, n [, attr])
 888
 889   Insert a character string (as many characters as will fit on the line) before
 890   the character under the cursor, up to *n* characters.   If *n* is zero or
 891   negative, the entire string is inserted. All characters to the right of the
 892   cursor are shifted right, with the rightmost characters on the line being lost.
 893   The cursor position does not change (after moving to *y*, *x*, if specified).
 894
 895
 896.. method:: window.insstr([y, x, ] str [, attr])
 897
 898   Insert a character string (as many characters as will fit on the line) before
 899   the character under the cursor.  All characters to the right of the cursor are
 900   shifted right, with the rightmost characters on the line being lost.  The cursor
 901   position does not change (after moving to *y*, *x*, if specified).
 902
 903
 904.. method:: window.instr([y, x] [, n])
 905
 906   Returns a string of characters, extracted from the window starting at the
 907   current cursor position, or at *y*, *x* if specified. Attributes are stripped
 908   from the characters.  If *n* is specified, :meth:`instr` returns return a string
 909   at most *n* characters long (exclusive of the trailing NUL).
 910
 911
 912.. method:: window.is_linetouched(line)
 913
 914   Returns true if the specified line was modified since the last call to
 915   :meth:`refresh`; otherwise returns false.  Raises a :exc:`curses.error`
 916   exception if *line* is not valid for the given window.
 917
 918
 919.. method:: window.is_wintouched()
 920
 921   Returns true if the specified window was modified since the last call to
 922   :meth:`refresh`; otherwise returns false.
 923
 924
 925.. method:: window.keypad(yes)
 926
 927   If *yes* is 1, escape sequences generated by some keys (keypad,  function keys)
 928   will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
 929   left as is in the input stream.
 930
 931
 932.. method:: window.leaveok(yes)
 933
 934   If *yes* is 1, cursor is left where it is on update, instead of being at "cursor
 935   position."  This reduces cursor movement where possible. If possible the cursor
 936   will be made invisible.
 937
 938   If *yes* is 0, cursor will always be at "cursor position" after an update.
 939
 940
 941.. method:: window.move(new_y, new_x)
 942
 943   Move cursor to ``(new_y, new_x)``.
 944
 945
 946.. method:: window.mvderwin(y, x)
 947
 948   Moves the window inside its parent window.  The screen-relative parameters of
 949   the window are not changed.  This routine is used to display different parts of
 950   the parent window at the same physical position on the screen.
 951
 952
 953.. method:: window.mvwin(new_y, new_x)
 954
 955   Move the window so its upper-left corner is at ``(new_y, new_x)``.
 956
 957
 958.. method:: window.nodelay(yes)
 959
 960   If *yes* is ``1``, :meth:`getch` will be non-blocking.
 961
 962
 963.. method:: window.notimeout(yes)
 964
 965   If *yes* is ``1``, escape sequences will not be timed out.
 966
 967   If *yes* is ``0``, after a few milliseconds, an escape sequence will not be
 968   interpreted, and will be left in the input stream as is.
 969
 970
 971.. method:: window.noutrefresh()
 972
 973   Mark for refresh but wait.  This function updates the data structure
 974   representing the desired state of the window, but does not force an update of
 975   the physical screen.  To accomplish that, call  :func:`doupdate`.
 976
 977
 978.. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
 979
 980   Overlay the window on top of *destwin*. The windows need not be the same size,
 981   only the overlapping region is copied. This copy is non-destructive, which means
 982   that the current background character does not overwrite the old contents of
 983   *destwin*.
 984
 985   To get fine-grained control over the copied region, the second form of
 986   :meth:`overlay` can be used. *sminrow* and *smincol* are the upper-left
 987   coordinates of the source window, and the other variables mark a rectangle in
 988   the destination window.
 989
 990
 991.. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
 992
 993   Overwrite the window on top of *destwin*. The windows need not be the same size,
 994   in which case only the overlapping region is copied. This copy is destructive,
 995   which means that the current background character overwrites the old contents of
 996   *destwin*.
 997
 998   To get fine-grained control over the copied region, the second form of
 999   :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left
1000   coordinates of the source window, the other variables mark a rectangle in the
1001   destination window.
1002
1003
1004.. method:: window.putwin(file)
1005
1006   Writes all data associated with the window into the provided file object.  This
1007   information can be later retrieved using the :func:`getwin` function.
1008
1009
1010.. method:: window.redrawln(beg, num)
1011
1012   Indicates that the *num* screen lines, starting at line *beg*, are corrupted and
1013   should be completely redrawn on the next :meth:`refresh` call.
1014
1015
1016.. method:: window.redrawwin()
1017
1018   Touches the entire window, causing it to be completely redrawn on the next
1019   :meth:`refresh` call.
1020
1021
1022.. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])
1023
1024   Update the display immediately (sync actual screen with previous
1025   drawing/deleting methods).
1026
1027   The 6 optional arguments can only be specified when the window is a pad created
1028   with :func:`newpad`.  The additional parameters are needed to indicate what part
1029   of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
1030   left-hand corner of the rectangle to be displayed in the pad.  *sminrow*,
1031   *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
1032   displayed on the screen.  The lower right-hand corner of the rectangle to be
1033   displayed in the pad is calculated from the screen coordinates, since the
1034   rectangles must be the same size.  Both rectangles must be entirely contained
1035   within their respective structures.  Negative values of *pminrow*, *pmincol*,
1036   *sminrow*, or *smincol* are treated as if they were zero.
1037
1038
1039.. method:: window.scroll([lines=1])
1040
1041   Scroll the screen or scrolling region upward by *lines* lines.
1042
1043
1044.. method:: window.scrollok(flag)
1045
1046   Controls what happens when the cursor of a window is moved off the edge of the
1047   window or scrolling region, either as a result of a newline action on the bottom
1048   line, or typing the last character of the last line.  If *flag* is false, the
1049   cursor is left on the bottom line.  If *flag* is true, the window is scrolled up
1050   one line.  Note that in order to get the physical scrolling effect on the
1051   terminal, it is also necessary to call :meth:`idlok`.
1052
1053
1054.. method:: window.setscrreg(top, bottom)
1055
1056   Set the scrolling region from line *top* to line *bottom*. All scrolling actions
1057   will take place in this region.
1058
1059
1060.. method:: window.standend()
1061
1062   Turn off the standout attribute.  On some terminals this has the side effect of
1063   turning off all attributes.
1064
1065
1066.. method:: window.standout()
1067
1068   Turn on attribute *A_STANDOUT*.
1069
1070
1071.. method:: window.subpad([nlines, ncols,] begin_y, begin_x)
1072
1073   Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
1074   whose width/height is *ncols*/*nlines*.
1075
1076
1077.. method:: window.subwin([nlines, ncols,] begin_y, begin_x)
1078
1079   Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
1080   whose width/height is *ncols*/*nlines*.
1081
1082   By default, the sub-window will extend from the specified position to the lower
1083   right corner of the window.
1084
1085
1086.. method:: window.syncdown()
1087
1088   Touches each location in the window that has been touched in any of its ancestor
1089   windows.  This routine is called by :meth:`refresh`, so it should almost never
1090   be necessary to call it manually.
1091
1092
1093.. method:: window.syncok(flag)
1094
1095   If called with *flag* set to true, then :meth:`syncup` is called automatically
1096   whenever there is a change in the window.
1097
1098
1099.. method:: window.syncup()
1100
1101   Touches all locations in ancestors of the window that have been changed in  the
1102   window.
1103
1104
1105.. method:: window.timeout(delay)
1106
1107   Sets blocking or non-blocking read behavior for the window.  If *delay* is
1108   negative, blocking read is used (which will wait indefinitely for input).  If
1109   *delay* is zero, then non-blocking read is used, and -1 will be returned by
1110   :meth:`getch` if no input is waiting.  If *delay* is positive, then
1111   :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
1112   still no input at the end of that time.
1113
1114
1115.. method:: window.touchline(start, count[, changed])
1116
1117   Pretend *count* lines have been changed, starting with line *start*.  If
1118   *changed* is supplied, it specifies whether the affected lines are marked as
1119   having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
1120
1121
1122.. method:: window.touchwin()
1123
1124   Pretend the whole window has been changed, for purposes of drawing
1125   optimizations.
1126
1127
1128.. method:: window.untouchwin()
1129
1130   Marks all lines in  the  window  as unchanged since the last call to
1131   :meth:`refresh`.
1132
1133
1134.. method:: window.vline([y, x,] ch, n)
1135
1136   Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
1137   character *ch*.
1138
1139
1140Constants
1141---------
1142
1143The :mod:`curses` module defines the following data members:
1144
1145
1146.. data:: ERR
1147
1148   Some curses routines  that  return  an integer, such as  :func:`getch`, return
1149   :const:`ERR` upon failure.
1150
1151
1152.. data:: OK
1153
1154   Some curses routines  that  return  an integer, such as  :func:`napms`, return
1155   :const:`OK` upon success.
1156
1157
1158.. data:: version
1159
1160   A string representing the current version of the module.  Also available as
1161   :const:`__version__`.
1162
1163Several constants are available to specify character cell attributes:
1164
1165+------------------+-------------------------------+
1166| Attribute        | Meaning                       |
1167+==================+===============================+
1168| ``A_ALTCHARSET`` | Alternate character set mode. |
1169+------------------+-------------------------------+
1170| ``A_BLINK``      | Blink mode.                   |
1171+------------------+-------------------------------+
1172| ``A_BOLD``       | Bold mode.                    |
1173+------------------+-------------------------------+
1174| ``A_DIM``        | Dim mode.                     |
1175+------------------+-------------------------------+
1176| ``A_NORMAL``     | Normal attribute.             |
1177+------------------+-------------------------------+
1178| ``A_STANDOUT``   | Standout mode.                |
1179+------------------+-------------------------------+
1180| ``A_UNDERLINE``  | Underline mode.               |
1181+------------------+-------------------------------+
1182
1183Keys are referred to by integer constants with names starting with  ``KEY_``.
1184The exact keycaps available are system dependent.
1185
1186.. XXX this table is far too large! should it be alphabetized?
1187
1188+-------------------+--------------------------------------------+
1189| Key constant      | Key                                        |
1190+===================+============================================+
1191| ``KEY_MIN``       | Minimum key value                          |
1192+-------------------+--------------------------------------------+
1193| ``KEY_BREAK``     | Break key (unreliable)                     |
1194+-------------------+--------------------------------------------+
1195| ``KEY_DOWN``      | Down-arrow                                 |
1196+-------------------+--------------------------------------------+
1197| ``KEY_UP``        | Up-arrow                                   |
1198+-------------------+--------------------------------------------+
1199| ``KEY_LEFT``      | Left-arrow                                 |
1200+-------------------+--------------------------------------------+
1201| ``KEY_RIGHT``     | Right-arrow                                |
1202+-------------------+--------------------------------------------+
1203| ``KEY_HOME``      | Home key (upward+left arrow)               |
1204+-------------------+--------------------------------------------+
1205| ``KEY_BACKSPACE`` | Backspace (unreliable)                     |
1206+-------------------+--------------------------------------------+
1207| ``KEY_F0``        | Function keys.  Up to 64 function keys are |
1208|                   | supported.                                 |
1209+-------------------+--------------------------------------------+
1210| ``KEY_Fn``        | Value of function key *n*                  |
1211+-------------------+--------------------------------------------+
1212| ``KEY_DL``        | Delete line                                |
1213+-------------------+--------------------------------------------+
1214| ``KEY_IL``        | Insert line                                |
1215+-------------------+--------------------------------------------+
1216| ``KEY_DC``        | Delete character                           |
1217+-------------------+--------------------------------------------+
1218| ``KEY_IC``        | Insert char or enter insert mode           |
1219+-------------------+--------------------------------------------+
1220| ``KEY_EIC``       | Exit insert char mode                      |
1221+-------------------+--------------------------------------------+
1222| ``KEY_CLEAR``     | Clear screen                               |
1223+-------------------+--------------------------------------------+
1224| ``KEY_EOS``       | Clear to end of screen                     |
1225+-------------------+--------------------------------------------+
1226| ``KEY_EOL``       | Clear to end of line                       |
1227+-------------------+--------------------------------------------+
1228| ``KEY_SF``        | Scroll 1 line forward                      |
1229+-------------------+--------------------------------------------+
1230| ``KEY_SR``        | Scroll 1 line backward (reverse)           |
1231+-------------------+--------------------------------------------+
1232| ``KEY_NPAGE``     | Next page                                  |
1233+-------------------+--------------------------------------------+
1234| ``KEY_PPAGE``     | Previous page                              |
1235+-------------------+--------------------------------------------+
1236| ``KEY_STAB``      | Set tab                                    |
1237+-------------------+--------------------------------------------+
1238| ``KEY_CTAB``      | Clear tab                                  |
1239+-------------------+--------------------------------------------+
1240| ``KEY_CATAB``     | Clear all tabs                             |
1241+-------------------+--------------------------------------------+
1242| ``KEY_ENTER``     | Enter or send (unreliable)                 |
1243+-------------------+--------------------------------------------+
1244| ``KEY_SRESET``    | Soft (partial) reset (unreliable)          |
1245+-------------------+--------------------------------------------+
1246| ``KEY_RESET``     | Reset or hard reset (unreliable)           |
1247+-------------------+--------------------------------------------+
1248| ``KEY_PRINT``     | Print                                      |
1249+-------------------+--------------------------------------------+
1250| ``KEY_LL``        | Home down or bottom (lower left)           |
1251+-------------------+--------------------------------------------+
1252| ``KEY_A1``        | Upper left of keypad                       |
1253+-------------------+--------------------------------------------+
1254| ``KEY_A3``        | Upper right of keypad                      |
1255+-------------------+--------------------------------------------+
1256| ``KEY_B2``        | Center of keypad                           |
1257+-------------------+--------------------------------------------+
1258| ``KEY_C1``        | Lower left of keypad                       |
1259+-------------------+--------------------------------------------+
1260| ``KEY_C3``        | Lower right of keypad                      |
1261+-------------------+--------------------------------------------+
1262| ``KEY_BTAB``      | Back tab                                   |
1263+-------------------+--------------------------------------------+
1264| ``KEY_BEG``       | Beg (beginning)                            |
1265+-------------------+--------------------------------------------+
1266| ``KEY_CANCEL``    | Cancel                                     |
1267+-------------------+--------------------------------------------+
1268| ``KEY_CLOSE``     | Close                                      |
1269+-------------------+--------------------------------------------+
1270| ``KEY_COMMAND``   | Cmd (command)                              |
1271+-------------------+--------------------------------------------+
1272| ``KEY_COPY``      | Copy                                       |
1273+-------------------+--------------------------------------------+
1274| ``KEY_CREATE``    | Create                                     |
1275+-------------------+--------------------------------------------+
1276| ``KEY_END``       | End                                        |
1277+-------------------+--------------------------------------------+
1278| ``KEY_EXIT``      | Exit                                       |
1279+-------------------+--------------------------------------------+
1280| ``KEY_FIND``      | Find                                       |
1281+-------------------+--------------------------------------------+
1282| ``KEY_HELP``      | Help                                       |
1283+-------------------+--------------------------------------------+
1284| ``KEY_MARK``      | Mark                                       |
1285+-------------------+--------------------------------------------+
1286| ``KEY_MESSAGE``   | Message                                    |
1287+-------------------+--------------------------------------------+
1288| ``KEY_MOVE``      | Move                                       |
1289+-------------------+--------------------------------------------+
1290| ``KEY_NEXT``      | Next                                       |
1291+-------------------+--------------------------------------------+
1292| ``KEY_OPEN``      | Open                                       |
1293+-------------------+--------------------------------------------+
1294| ``KEY_OPTIONS``   | Options                                    |
1295+-------------------+--------------------------------------------+
1296| ``KEY_PREVIOUS``  | Prev (previous)                            |
1297+-------------------+--------------------------------------------+
1298| ``KEY_REDO``      | Redo                                       |
1299+-------------------+--------------------------------------------+
1300| ``KEY_REFERENCE`` | Ref (reference)                            |
1301+-------------------+--------------------------------------------+
1302| ``KEY_REFRESH``   | Refresh                                    |
1303+-------------------+--------------------------------------------+
1304| ``KEY_REPLACE``   | Replace                                    |
1305+-------------------+--------------------------------------------+
1306| ``KEY_RESTART``   | Restart                                    |
1307+-------------------+--------------------------------------------+
1308| ``KEY_RESUME``    | …

Large files files are truncated, but you can click here to view the full file