summary refs log tree commit diff stats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/examples/README8
-rw-r--r--doc/examples/bash_automatic_cd.sh21
-rw-r--r--doc/examples/bash_subshell_notice.sh7
-rw-r--r--doc/examples/plugin_chmod_keybindings.py20
-rw-r--r--doc/examples/plugin_file_filter.py21
-rw-r--r--doc/examples/plugin_hello_world.py23
-rw-r--r--doc/examples/plugin_new_macro.py19
-rw-r--r--doc/examples/plugin_new_sorting_method.py9
-rw-r--r--doc/examples/rifle_different_file_opener.conf9
-rwxr-xr-xdoc/examples/rifle_sxiv.sh48
-rw-r--r--doc/examples/vim_file_chooser.vim36
-rw-r--r--doc/ranger.132
-rw-r--r--doc/ranger.pod30
-rw-r--r--doc/rifle.12
14 files changed, 57 insertions, 228 deletions
diff --git a/doc/examples/README b/doc/examples/README
deleted file mode 100644
index ca514853..00000000
--- a/doc/examples/README
+++ /dev/null
@@ -1,8 +0,0 @@
-The files in this directory contain applications or extensions of ranger which
-are put here for your inspiration and as references.
-
-In order to use a plugin from this directory, you need to copy it to
-~/.config/ranger/plugins/
-
-Note that if you update ranger to a new minor version (for example,
-from 1.6.* to 1.7.0), your outdated plugins WILL break and crash ranger.
diff --git a/doc/examples/bash_automatic_cd.sh b/doc/examples/bash_automatic_cd.sh
deleted file mode 100644
index 8d72c553..00000000
--- a/doc/examples/bash_automatic_cd.sh
+++ /dev/null
@@ -1,21 +0,0 @@
-# Compatible with ranger 1.4.2 through 1.6.*
-#
-# Automatically change the directory in bash after closing ranger
-#
-# This is a bash function for .bashrc to automatically change the directory to
-# the last visited one after ranger quits.
-# To undo the effect of this function, you can type "cd -" to return to the
-# original directory.
-
-function ranger-cd {
-    tempfile='/tmp/chosendir'
-    /usr/bin/ranger --choosedir="$tempfile" "${@:-$(pwd)}"
-    test -f "$tempfile" &&
-    if [ "$(cat -- "$tempfile")" != "$(echo -n `pwd`)" ]; then
-        cd -- "$(cat "$tempfile")"
-    fi
-    rm -f -- "$tempfile"
-}
-
-# This binds Ctrl-O to ranger-cd:
-bind '"\C-o":"ranger-cd\C-m"'
diff --git a/doc/examples/bash_subshell_notice.sh b/doc/examples/bash_subshell_notice.sh
deleted file mode 100644
index bc44d5a8..00000000
--- a/doc/examples/bash_subshell_notice.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-# Compatible with ranger 1.5.3 through 1.6.*
-#
-# Change the prompt when you open a shell from inside ranger
-#
-# Add this line to your .bashrc for it to work.
-
-[ -n "$RANGER_LEVEL" ] && PS1="$PS1"'(in ranger) '
diff --git a/doc/examples/plugin_chmod_keybindings.py b/doc/examples/plugin_chmod_keybindings.py
deleted file mode 100644
index 0ab975ed..00000000
--- a/doc/examples/plugin_chmod_keybindings.py
+++ /dev/null
@@ -1,20 +0,0 @@
-# Compatible with ranger 1.6.*
-#
-# This plugin serves as an example for adding key bindings through a plugin.
-# It could replace the ten lines in the rc.conf that create the key bindings
-# for the "chmod" command.
-
-import ranger.api
-old_hook_init = ranger.api.hook_init
-
-def hook_init(fm):
-    old_hook_init(fm)
-
-    # Generate key bindings for the chmod command
-    command = "map {0}{1}{2} shell -d chmod {1}{0}{2} %s"
-    for mode in list('ugoa') + ['']:
-        for perm in "rwxXst":
-            fm.execute_console(command.format('-', mode, perm))
-            fm.execute_console(command.format('+', mode, perm))
-
-ranger.api.hook_init = hook_init
diff --git a/doc/examples/plugin_file_filter.py b/doc/examples/plugin_file_filter.py
deleted file mode 100644
index b9bea1f3..00000000
--- a/doc/examples/plugin_file_filter.py
+++ /dev/null
@@ -1,21 +0,0 @@
-# Compatible since ranger 1.6.1, git commit c82a8a76989c
-#
-# This plugin hides the directories "/boot", "/sbin", "/proc" and "/sys" unless
-# the "show_hidden" option is activated.
-
-# Save the original filter function
-import ranger.container.directory
-old_accept_file = ranger.container.directory.accept_file
-
-HIDE_FILES = ("/boot", "/sbin", "/proc", "/sys")
-
-# Define a new one
-def custom_accept_file(file, filters):
-    if not file.fm.settings.show_hidden and file.path in HIDE_FILES:
-        return False
-    else:
-        return old_accept_file(file, filters)
-
-# Overwrite the old function
-import ranger.container.directory
-ranger.container.directory.accept_file = custom_accept_file
diff --git a/doc/examples/plugin_hello_world.py b/doc/examples/plugin_hello_world.py
deleted file mode 100644
index a803e21b..00000000
--- a/doc/examples/plugin_hello_world.py
+++ /dev/null
@@ -1,23 +0,0 @@
-# Compatible with ranger 1.6.*
-#
-# This is a sample plugin that displays "Hello World" in ranger's console after
-# it started.
-
-# We are going to extend the hook "ranger.api.hook_ready", so first we need
-# to import ranger.api:
-import ranger.api
-
-# Save the previously existing hook, because maybe another module already
-# extended that hook and we don't want to lose it:
-old_hook_ready = ranger.api.hook_ready
-
-# Create a replacement for the hook that...
-def hook_ready(fm):
-    # ...does the desired action...
-    fm.notify("Hello World")
-    # ...and calls the saved hook.  If you don't care about the return value,
-    # simply return the return value of the previous hook to be safe.
-    return old_hook_ready(fm)
-
-# Finally, "monkey patch" the existing hook_ready function with our replacement:
-ranger.api.hook_ready = hook_ready
diff --git a/doc/examples/plugin_new_macro.py b/doc/examples/plugin_new_macro.py
deleted file mode 100644
index 159a92f2..00000000
--- a/doc/examples/plugin_new_macro.py
+++ /dev/null
@@ -1,19 +0,0 @@
-# Compatible with ranger 1.6.*
-#
-# This plugin adds the new macro %date which is substituted with the current
-# date in commands that allow macros.  You can test it with the command
-# ":shell echo %date; read"
-
-# Save the original macro function
-import ranger.core.actions
-old_get_macros = ranger.core.actions.Actions._get_macros
-
-# Define a new macro function
-import time
-def get_macros_with_date(self):
-       macros = old_get_macros(self)
-       macros['date'] = time.strftime('%m/%d/%Y')
-       return macros
-
-# Overwrite the old one
-ranger.core.actions.Actions._get_macros = get_macros_with_date
diff --git a/doc/examples/plugin_new_sorting_method.py b/doc/examples/plugin_new_sorting_method.py
deleted file mode 100644
index 6b41b0e1..00000000
--- a/doc/examples/plugin_new_sorting_method.py
+++ /dev/null
@@ -1,9 +0,0 @@
-# Compatible with ranger 1.6.*
-#
-# This plugin adds the sorting algorithm called 'random'.  To enable it, type
-# ":set sort=random" or create a key binding with ":map oz set sort=random"
-
-from ranger.container.directory import Directory
-from random import random
-Directory.sort_dict['random'] = lambda path: random()
-
diff --git a/doc/examples/rifle_different_file_opener.conf b/doc/examples/rifle_different_file_opener.conf
deleted file mode 100644
index 4a8250b8..00000000
--- a/doc/examples/rifle_different_file_opener.conf
+++ /dev/null
@@ -1,9 +0,0 @@
-# Compatible with ranger 1.6.*
-#
-# Replace your rifle.conf with this file to use xdg-open as your file opener.
-# This is, of course, adaptable for use with any other file opener.
-else = xdg-open "$1"
-
-# You need an "editor" and "pager" in order to use certain functions in ranger:
-label editor = "$EDITOR" -- "$@"
-label pager  = "$PAGER" -- "$@"
diff --git a/doc/examples/rifle_sxiv.sh b/doc/examples/rifle_sxiv.sh
deleted file mode 100755
index 6307f1c2..00000000
--- a/doc/examples/rifle_sxiv.sh
+++ /dev/null
@@ -1,48 +0,0 @@
-#!/bin/sh
-# Compatible with ranger 1.6.*
-#
-# This script searches image files in a directory, opens them all with sxiv and
-# sets the first argument to the first image displayed by sxiv.
-#
-# This is supposed to be used in rifle.conf as a workaround for the fact that
-# sxiv takes no file name arguments for the first image, just the number.  Copy
-# this file somewhere into your $PATH and add this at the top of rifle.conf:
-#
-#   mime ^image, has sxiv, X, flag f = path/to/this/script -- "$@"
-#
-# Implementation notes: this script is quite slow because of POSIX limitations
-# and portability concerns. First calling the shell function 'abspath' is
-# quicker than calling 'realpath' because it would fork a whole process, which
-# is slow. Second, we need to append a file list to sxiv, which can only be done
-# properly in two ways: arrays (which are not POSIX) or \0 sperated
-# strings. Unfortunately, assigning \0 to a variable is not POSIX either (will
-# not work in dash and others), so we cannot store the result of listfiles to a
-# variable.
-
-if [ $# -eq 0 ]; then
-    echo "Usage: ${0##*/} PICTURES"
-    exit
-fi
-
-[ "$1" == '--' ] && shift
-
-abspath () {
-    case "$1" in
-        /*) printf "%s\n" "$1";;
-        *)  printf "%s\n" "$PWD/$1";;
-    esac
-}
-
-listfiles () {
-    find -L "$(dirname "$target")" -maxdepth 1 -type f -iregex \
-      '.*\(jpe?g\|bmp\|png\|gif\)$' -print0 | sort -z
-}
-
-target="$(abspath "$1")"
-count="$(listfiles | grep -m 1 -ZznF "$target" | cut -d: -f1)"
-
-if [ -n "$count" ]; then
-    listfiles | xargs -0 sxiv -n "$count" --
-else
-    sxiv -- "$@" # fallback
-fi
diff --git a/doc/examples/vim_file_chooser.vim b/doc/examples/vim_file_chooser.vim
deleted file mode 100644
index aa3af763..00000000
--- a/doc/examples/vim_file_chooser.vim
+++ /dev/null
@@ -1,36 +0,0 @@
-" Compatible with ranger 1.4.2 through 1.6.*
-"
-" Add ranger as a file chooser in vim
-"
-" If you add this code to the .vimrc, ranger can be started using the command
-" ":RangerChooser" or the keybinding "<leader>r".  Once you select one or more
-" files, press enter and ranger will quit again and vim will open the selected
-" files.
-
-function! RangeChooser()
-    let temp = tempname()
-    " The option "--choosefiles" was added in ranger 1.5.1. Use the next line
-    " with ranger 1.4.2 through 1.5.0 instead.
-    "exec 'silent !ranger --choosefile=' . shellescape(temp)
-    exec 'silent !ranger --choosefiles=' . shellescape(temp)
-    if !filereadable(temp)
-        redraw!
-        " Nothing to read.
-        return
-    endif
-    let names = readfile(temp)
-    if empty(names)
-        redraw!
-        " Nothing to open.
-        return
-    endif
-    " Edit the first item.
-    exec 'edit ' . fnameescape(names[0])
-    " Add any remaning items to the arg list/buffer list.
-    for name in names[1:]
-        exec 'argadd ' . fnameescape(name)
-    endfor
-    redraw!
-endfunction
-command! -bar RangerChooser call RangeChooser()
-nnoremap <leader>r :<C-U>RangerChooser<CR>
diff --git a/doc/ranger.1 b/doc/ranger.1
index 7c01dc26..426ec0cf 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.6.1" "03/31/2015" "ranger manual"
+.TH RANGER 1 "ranger-1.7.0" "04/13/2015" "ranger manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -162,8 +162,13 @@ The \fI\s-1README\s0\fR contains install instructions.
 The file \fI\s-1HACKING\s0.md\fR contains guidelines for code modification.
 .PP
 The directory \fIdoc/configs\fR contains configuration files.  They are usually
-installed to \fI/usr/lib/python*/site\-packages/ranger/config\fR and can be
-obtained with ranger's \-\-copy\-config option.
+installed to \fI/usr/share/doc/ranger/config\fR and can be obtained with ranger's
+\&\-\-copy\-config option.
+.PP
+The directory \fIexamples\fR contains reference implementations for ranger
+plugins, sample configuration files and some programs for integrating ranger
+with other software.  They are usually installed to
+\&\fI/usr/share/doc/ranger/examples\fR.
 .PP
 The man page of \fIrifle\fR\|(1) describes the functions of the file opener
 .PP
@@ -320,6 +325,14 @@ Macros for file paths are generally shell-escaped so they can be used in the
 Additionally, if you create a key binding that uses <any>, a special statement
 which accepts any key, then the macro \f(CW%any\fR (or \f(CW%any0\fR, \f(CW%any1\fR, \f(CW%any2\fR, ...) can be
 used in the command to get the key that was pressed.
+.PP
+The macro \f(CW%rangerdir\fR expands to the directory of ranger's python library, you
+can use it for something like this command:
+  alias show_commands shell less \f(CW%rangerdir\fR/config/commands.py
+.PP
+The macro \f(CW%space\fR expands to a space character. You can use it to add spaces to
+the end of a command when needed, while preventing editors to strip spaces off
+the end of the line automatically.
 .SS "\s-1BOOKMARKS\s0"
 .IX Subsection "BOOKMARKS"
 Type \fB<C\-x>rm<key>\fR to bookmark the current directory. You can
@@ -841,6 +854,7 @@ including their parameters, excluding descriptions:
 \& find pattern
 \& flat level
 \& grep pattern
+\& help
 \& linemode linemodename
 \& load_copy_buffer
 \& map key command
@@ -862,6 +876,7 @@ including their parameters, excluding descriptions:
 \& search pattern
 \& search_inc pattern
 \& set option value
+\& setintag tags option value
 \& setlocal [path=<path>] option value
 \& shell [\-FLAGS] command
 \& terminal
@@ -994,12 +1009,16 @@ values \-2 and less are invalid.
 .IP "grep \fIpattern\fR" 2
 .IX Item "grep pattern"
 Looks for a string in all marked files or directories.
+.IP "help" 2
+.IX Item "help"
+Provides a quick way to view ranger documentations.
 .IP "linemode \fIlinemodename\fR" 2
 .IX Item "linemode linemodename"
 Sets the linemode of all files in the current directory.  The linemode may be:
 .Sp
-.Vb 5
+.Vb 6
 \& "filename": display each line as "<basename>...<size>"
+\& "fileinfo": display each line as "<basename>...<file(1) output>"
 \& "permissions": display each line as "<permissions> <owner> <group> <basename>"
 \& "metatitle": display metadata from .metadata.json files if
 \&     available, fall back to the "filename" linemode if no
@@ -1140,6 +1159,11 @@ doesn't work for functions and regular expressions. Valid values are:
 \& list           | 1,2,3,4
 \& none           | none
 .Ve
+.IP "setintag \fItags\fR \fIoption\fR \fIvalue\fR" 2
+.IX Item "setintag tags option value"
+Assigns a new value to an option, but locally for the directories that are
+marked with \fItag\fR.  This means, that this option only takes effect when
+visiting that directory.
 .IP "setlocal [path=\fIpath\fR] \fIoption\fR \fIvalue\fR" 2
 .IX Item "setlocal [path=path] option value"
 Assigns a new value to an option, but locally for the directory given by
diff --git a/doc/ranger.pod b/doc/ranger.pod
index 5ebdbc98..eea82c3e 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -35,8 +35,13 @@ The F<README> contains install instructions.
 The file F<HACKING.md> contains guidelines for code modification.
 
 The directory F<doc/configs> contains configuration files.  They are usually
-installed to F</usr/lib/python*/site-packages/ranger/config> and can be
-obtained with ranger's --copy-config option.
+installed to F</usr/share/doc/ranger/config> and can be obtained with ranger's
+--copy-config option.
+
+The directory F<examples> contains reference implementations for ranger
+plugins, sample configuration files and some programs for integrating ranger
+with other software.  They are usually installed to
+F</usr/share/doc/ranger/examples>.
 
 The man page of rifle(1) describes the functions of the file opener
 
@@ -217,6 +222,14 @@ Additionally, if you create a key binding that uses <any>, a special statement
 which accepts any key, then the macro %any (or %any0, %any1, %any2, ...) can be
 used in the command to get the key that was pressed.
 
+The macro %rangerdir expands to the directory of ranger's python library, you
+can use it for something like this command:
+  alias show_commands shell less %rangerdir/config/commands.py
+
+The macro %space expands to a space character. You can use it to add spaces to
+the end of a command when needed, while preventing editors to strip spaces off
+the end of the line automatically.
+
 =head2 BOOKMARKS
 
 Type B<E<lt>C-xE<gt>rm<keyE<gt>> to bookmark the current directory. You can
@@ -848,6 +861,7 @@ including their parameters, excluding descriptions:
  find pattern
  flat level
  grep pattern
+ help
  linemode linemodename
  load_copy_buffer
  map key command
@@ -869,6 +883,7 @@ including their parameters, excluding descriptions:
  search pattern
  search_inc pattern
  set option value
+ setintag tags option value
  setlocal [path=<path>] option value
  shell [-FLAGS] command
  terminal
@@ -1024,11 +1039,16 @@ values -2 and less are invalid.
 
 Looks for a string in all marked files or directories.
 
+=item help
+
+Provides a quick way to view ranger documentations.
+
 =item linemode I<linemodename>
 
 Sets the linemode of all files in the current directory.  The linemode may be:
 
  "filename": display each line as "<basename>...<size>"
+ "fileinfo": display each line as "<basename>...<file(1) output>"
  "permissions": display each line as "<permissions> <owner> <group> <basename>"
  "metatitle": display metadata from .metadata.json files if
      available, fall back to the "filename" linemode if no
@@ -1183,6 +1203,12 @@ doesn't work for functions and regular expressions. Valid values are:
  list           | 1,2,3,4
  none           | none
 
+=item setintag I<tags> I<option> I<value>
+
+Assigns a new value to an option, but locally for the directories that are
+marked with I<tag>.  This means, that this option only takes effect when
+visiting that directory.
+
 =item setlocal [path=I<path>] I<option> I<value>
 
 Assigns a new value to an option, but locally for the directory given by
diff --git a/doc/rifle.1 b/doc/rifle.1
index f7e9df78..95010452 100644
--- a/doc/rifle.1
+++ b/doc/rifle.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RIFLE 1"
-.TH RIFLE 1 "rifle-1.6.1" "03/31/2015" "rifle manual"
+.TH RIFLE 1 "rifle-1.7.0" "04/13/2015" "rifle manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
/a> 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152
-- text editor, particularly text drawing, horizontal wrap, vertical scrolling
Text = {}

-- draw a line starting from startpos to screen at y between State.left and State.right
-- return y for the next line
function Text.draw(State, line_index, y, startpos, hide_cursor, show_line_numbers)
  local line = State.lines[line_index]
  local line_cache = State.line_cache[line_index]
  line_cache.starty = y
  line_cache.startpos = startpos
  -- wrap long lines
  Text.populate_screen_line_starting_pos(State, line_index)
  Text.populate_link_offsets(State, line_index)
  if show_line_numbers then
    App.color(Line_number_color)
    love.graphics.print(line_index, State.left-Line_number_width*State.font:getWidth('m')+10,y)
  end
  initialize_color()
  assert(#line_cache.screen_line_starting_pos >= 1, 'line cache missing screen line info')
  for i=1,#line_cache.screen_line_starting_pos do
    local pos = line_cache.screen_line_starting_pos[i]
    if pos < startpos then
      -- render nothing
--?       print('skipping', screen_line)
    else
      local screen_line = Text.screen_line(line, line_cache, i)
--?       print('text.draw:', screen_line, 'at', line_index,pos, 'after', x,y)
      local frag_len = utf8.len(screen_line)
      -- render any highlights
      for _,link_offsets in ipairs(line_cache.link_offsets) do
        -- render link decorations
        local s,e,filename = unpack(link_offsets)
        local lo, hi = Text.clip_wikiword_with_screen_line(State.font, line, line_cache, i, s, e)
        if lo then
          button(State, 'link', {x=State.left+lo, y=y, w=hi-lo, h=State.line_height,
            icon = icon.hyperlink_decoration,
            onpress1 = function()
                         if file_exists(filename) then
                           source.switch_to_file(filename)
                         end
                       end,
          })
        end
      end
      if State.selection1.line then
        local lo, hi = Text.clip_selection(State, line_index, pos, pos+frag_len)
        Text.draw_highlight(State, line, State.left,y, pos, lo,hi)
      end
      if not hide_cursor and line_index == State.cursor1.line then
        -- render search highlight or cursor
        if State.search_term then
          local data = State.lines[State.cursor1.line].data
          local cursor_offset = Text.offset(data, State.cursor1.pos)
          if data:sub(cursor_offset, cursor_offset+#State.search_term-1) == State.search_term then
            local save_selection = State.selection1
            State.selection1 = {line=line_index, pos=State.cursor1.pos+utf8.len(State.search_term)}
            local lo, hi = Text.clip_selection(State, line_index, pos, pos+frag_len)
            Text.draw_highlight(State, line, State.left,y, pos, lo,hi)
            State.selection1 = save_selection
          end
        elseif Focus == 'edit' then
          if pos <= State.cursor1.pos and pos + frag_len > State.cursor1.pos then
            Text.draw_cursor(State, State.left+Text.x(State.font, screen_line, State.cursor1.pos-pos+1), y)
          elseif pos + frag_len == State.cursor1.pos then
            -- Show cursor at end of line.
            -- This place also catches end of wrapping screen lines. That doesn't seem worth distinguishing.
            -- It seems useful to see a cursor whether your eye is on the left or right margin.
            Text.draw_cursor(State, State.left+Text.x(State.font, screen_line, State.cursor1.pos-pos+1), y)
          end
        end
      end
      -- render colorized text
      local x = State.left
      for frag in screen_line:gmatch('%S*%s*') do
        select_color(frag)
        App.screen.print(frag, x,y)
        x = x+State.font:getWidth(frag)
      end
      y = y + State.line_height
      if y >= App.screen.height then
        break
      end
    end
  end
  return y
end

function Text.screen_line(line, line_cache, i)
  local pos = line_cache.screen_line_starting_pos[i]
  local offset = Text.offset(line.data, pos)
  if i >= #line_cache.screen_line_starting_pos then
    return line.data:sub(offset)
  end
  local endpos = line_cache.screen_line_starting_pos[i+1]-1
  local end_offset = Text.offset(line.data, endpos)
  return line.data:sub(offset, end_offset)
end

function Text.draw_cursor(State, x, y)
  -- blink every 0.5s
  if math.floor(Cursor_time*2)%2 == 0 then
    App.color(Cursor_color)
    love.graphics.rectangle('fill', x,y, 3,State.line_height)
  end
  State.cursor_x = x
  State.cursor_y = y+State.line_height
end

function Text.populate_screen_line_starting_pos(State, line_index)
  local line = State.lines[line_index]
  if line.mode ~= 'text' then return end
  local line_cache = State.line_cache[line_index]
  if line_cache.screen_line_starting_pos then
    return
  end
  line_cache.screen_line_starting_pos = {1}
  local x = 0
  local pos = 1
  -- try to wrap at word boundaries
  for frag in line.data:gmatch('%S*%s*') do
    local frag_width = State.font:getWidth(frag)
--?     print('-- frag:', frag, pos, x, frag_width, State.width)
    while x + frag_width > State.width do
--?       print('frag:', frag, pos, x, frag_width, State.width)
      if x < 0.8 * State.width then
        -- long word; chop it at some letter
        -- We're not going to reimplement TeX here.
        local bpos = Text.nearest_pos_less_than(State.font, frag, State.width - x)
        if x == 0 and bpos == 0 then
          assert(false, ("Infinite loop while line-wrapping. Editor is %dpx wide; window is %dpx wide"):format(State.width, App.screen.width))
        end
        pos = pos + bpos
        local boffset = Text.offset(frag, bpos+1)  -- byte _after_ bpos
        frag = string.sub(frag, boffset)
--?         if bpos > 0 then
--?           print('after chop:', frag)
--?         end
        frag_width = State.font:getWidth(frag)
      end
--?       print('screen line:', pos)
      table.insert(line_cache.screen_line_starting_pos, pos)
      x = 0  -- new screen line
    end
    x = x + frag_width
    pos = pos + utf8.len(frag)
  end
end

function Text.populate_link_offsets(State, line_index)
  local line = State.lines[line_index]
  if line.mode ~= 'text' then return end
  local line_cache = State.line_cache[line_index]
  if line_cache.link_offsets then
    return
  end
  line_cache.link_offsets = {}
  local pos = 1
  -- try to wrap at word boundaries
  local s, e = 1, 0
  while s <= #line.data do
    s, e = line.data:find('%[%[%S+%]%]', s)
    if s == nil then break end
    local word = line.data:sub(s+2, e-2)  -- strip out surrounding '[[..]]'
--?     print('wikiword:', s, e, word)
    table.insert(line_cache.link_offsets, {s, e, word})
    s = e + 1
  end
end

-- Intersect the filename between byte offsets s,e with the bounds of screen line i.
-- Return the left/right pixel coordinates of of the intersection,
-- or nil if it doesn't intersect with screen line i.
function Text.clip_wikiword_with_screen_line(font, line, line_cache, i, s, e)
  local spos = line_cache.screen_line_starting_pos[i]
  local soff = Text.offset(line.data, spos)
  if e < soff then
    return
  end
  local eoff
  if i < #line_cache.screen_line_starting_pos then
    local epos = line_cache.screen_line_starting_pos[i+1]
    eoff = Text.offset(line.data, epos)
    if s > eoff then
      return
    end
  end
  local loff = math.max(s, soff)
  local hoff
  if eoff then
    hoff = math.min(e, eoff)
  else
    hoff = e
  end
--?   print(s, e, soff, eoff, loff, hoff)
  return font:getWidth(line.data:sub(soff, loff-1)), font:getWidth(line.data:sub(soff, hoff))
end

function Text.text_input(State, t)
  if App.mouse_down(1) then return end
  if App.any_modifier_down() then
    if App.key_down(t) then
      -- The modifiers didn't change the key. Handle it in keychord_pressed.
      return
    else
      -- Key mutated by the keyboard layout. Continue below.
    end
  end
  local before = snapshot(State, State.cursor1.line)
--?   print(State.screen_top1.line, State.screen_top1.pos, State.cursor1.line, State.cursor1.pos)
  Text.insert_at_cursor(State, t)
  if State.cursor_y > App.screen.height - State.line_height then
    Text.populate_screen_line_starting_pos(State, State.cursor1.line)
    Text.snap_cursor_to_bottom_of_screen(State, State.left, State.right)
  end
  record_undo_event(State, {before=before, after=snapshot(State, State.cursor1.line)})
end

function Text.insert_at_cursor(State, t)
  assert(State.lines[State.cursor1.line].mode == 'text', 'line is not text')
  local byte_offset = Text.offset(State.lines[State.cursor1.line].data, State.cursor1.pos)
  State.lines[State.cursor1.line].data = string.sub(State.lines[State.cursor1.line].data, 1, byte_offset-1)..t..string.sub(State.lines[State.cursor1.line].data, byte_offset)
  Text.clear_screen_line_cache(State, State.cursor1.line)
  State.cursor1.pos = State.cursor1.pos+1
end

-- Don't handle any keys here that would trigger text_input above.
function Text.keychord_press(State, chord)
--?   print('chord', chord, State.selection1.line, State.selection1.pos)
  --== shortcuts that mutate text
  if chord == 'return' then
    local before_line = State.cursor1.line
    local before = snapshot(State, before_line)
    Text.insert_return(State)
    State.selection1 = {}
    if State.cursor_y > App.screen.height - State.line_height then
      Text.snap_cursor_to_bottom_of_screen(State, State.left, State.right)
    end
    schedule_save(State)
    record_undo_event(State, {before=before, after=snapshot(State, before_line, State.cursor1.line)})
  elseif chord == 'tab' then
    local before = snapshot(State, State.cursor1.line)
--?     print(State.screen_top1.line, State.screen_top1.pos, State.cursor1.line, State.cursor1.pos)
    Text.insert_at_cursor(State, '\t')
    if State.cursor_y > App.screen.height - State.line_height then
      Text.populate_screen_line_starting_pos(State, State.cursor1.line)
      Text.snap_cursor_to_bottom_of_screen(State, State.left, State.right)
--?       print('=>', State.screen_top1.line, State.screen_top1.pos, State.cursor1.line, State.cursor1.pos)
    end
    schedule_save(State)
    record_undo_event(State, {before=before, after=snapshot(State, State.cursor1.line)})
  elseif chord == 'backspace' then
    if State.selection1.line then
      Text.delete_selection(State, State.left, State.right)
      schedule_save(State)
      return
    end
    local before
    if State.cursor1.pos > 1 then
      before = snapshot(State, State.cursor1.line)
      local byte_start = utf8.offset(State.lines[State.cursor1.line].data, State.cursor1.pos-1)
      local byte_end = utf8.offset(State.lines[State.cursor1.line].data, State.cursor1.pos)
      if byte_start then
        if byte_end then
          State.lines[State.cursor1.line].data = string.sub(State.lines[State.cursor1.line].data, 1, byte_start-1)..string.sub(State.lines[State.cursor1.line].data, byte_end)
        else
          State.lines[State.cursor1.line].data = string.sub(State.lines[State.cursor1.line].data, 1, byte_start-1)
        end
        State.cursor1.pos = State.cursor1.pos-1
      end
    elseif State.cursor1.line > 1 then
      before = snapshot(State, State.cursor1.line-1, State.cursor1.line)
      if State.lines[State.cursor1.line-1].mode == 'drawing' then
        table.remove(State.lines, State.cursor1.line-1)
        table.remove(State.line_cache, State.cursor1.line-1)
      else
        -- join lines
        State.cursor1.pos = utf8.len(State.lines[State.cursor1.line-1].data)+1
        State.lines[State.cursor1.line-1].data = State.lines[State.cursor1.line-1].data..State.lines[State.cursor1.line].data
        table.remove(State.lines, State.cursor1.line)
        table.remove(State.line_cache, State.cursor1.line)
      end
      State.cursor1.line = State.cursor1.line-1
    end
    if State.screen_top1.line > #State.lines then
      Text.populate_screen_line_starting_pos(State, #State.lines)
      local line_cache = State.line_cache[#State.line_cache]
      State.screen_top1 = {line=#State.lines, pos=line_cache.screen_line_starting_pos[#line_cache.screen_line_starting_pos]}
    elseif Text.lt1(State.cursor1, State.screen_top1) then
      State.screen_top1 = {
        line=State.cursor1.line,
        pos=Text.pos_at_start_of_screen_line(State, State.cursor1),
      }
      Text.redraw_all(State)  -- if we're scrolling, reclaim all fragments to avoid memory leaks
    end
    Text.clear_screen_line_cache(State, State.cursor1.line)
    assert(Text.le1(State.screen_top1, State.cursor1), ('screen_top (line=%d,pos=%d) is below cursor (line=%d,pos=%d)'):format(State.screen_top1.line, State.screen_top1.pos, State.cursor1.line, State.cursor1.pos))
    schedule_save(State)
    record_undo_event(State, {before=before, after=snapshot(State, State.cursor1.line)})
  elseif chord == 'delete' then
    if State.selection1.line then
      Text.delete_selection(State, State.left, State.right)
      schedule_save(State)
      return
    end
    local before
    if State.cursor1.pos <= utf8.len(State.lines[State.cursor1.line].data) then
      before = snapshot(State, State.cursor1.line)
    else
      before = snapshot(State, State.cursor1.line, State.cursor1.line+1)
    end
    if State.cursor1.pos <= utf8.len(State.lines[State.cursor1.line].data) then
      local byte_start = utf8.offset(State.lines[State.cursor1.line].data, State.cursor1.pos)
      local byte_end = utf8.offset(State.lines[State.cursor1.line].data, State.cursor1.pos+1)
      if byte_start then
        if byte_end then
          State.lines[State.cursor1.line].data = string.sub(State.lines[State.cursor1.line].data, 1, byte_start-1)..string.sub(State.lines[State.cursor1.line].data, byte_end)
        else
          State.lines[State.cursor1.line].data = string.sub(State.lines[State.cursor1.line].data, 1, byte_start-1)
        end
        -- no change to State.cursor1.pos
      end
    elseif State.cursor1.line < #State.lines then
      if State.lines[State.cursor1.line+1].mode == 'text' then
        -- join lines
        State.lines[State.cursor1.line].data = State.lines[State.cursor1.line].data..State.lines[State.cursor1.line+1].data
      end
      table.remove(State.lines, State.cursor1.line+1)
      table.remove(State.line_cache, State.cursor1.line+1)
    end
    Text.clear_screen_line_cache(State, State.cursor1.line)
    schedule_save(State)
    record_undo_event(State, {before=before, after=snapshot(State, State.cursor1.line)})
  --== shortcuts that move the cursor
  elseif chord == 'left' then
    Text.left(State)
    State.selection1 = {}
  elseif chord == 'right' then
    Text.right(State)
    State.selection1 = {}
  elseif chord == 'S-left' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.left(State)
  elseif chord == 'S-right' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.right(State)
  -- C- hotkeys reserved for drawings, so we'll use M-
  elseif chord == 'M-left' then
    Text.word_left(State)
    State.selection1 = {}
  elseif chord == 'M-right' then
    Text.word_right(State)
    State.selection1 = {}
  elseif chord == 'M-S-left' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.word_left(State)
  elseif chord == 'M-S-right' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.word_right(State)
  elseif chord == 'home' then
    Text.start_of_line(State)
    State.selection1 = {}
  elseif chord == 'end' then
    Text.end_of_line(State)
    State.selection1 = {}
  elseif chord == 'S-home' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.start_of_line(State)
  elseif chord == 'S-end' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.end_of_line(State)
  elseif chord == 'up' then
    Text.up(State)
    State.selection1 = {}
  elseif chord == 'down' then
    Text.down(State)
    State.selection1 = {}
  elseif chord == 'S-up' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.up(State)
  elseif chord == 'S-down' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.down(State)
  elseif chord == 'pageup' then
    Text.pageup(State)
    State.selection1 = {}
  elseif chord == 'pagedown' then
    Text.pagedown(State)
    State.selection1 = {}
  elseif chord == 'S-pageup' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.pageup(State)
  elseif chord == 'S-pagedown' then
    if State.selection1.line == nil then
      State.selection1 = {line=State.cursor1.line, pos=State.cursor1.pos}
    end
    Text.pagedown(State)
  end
end

function Text.insert_return(State)
  local byte_offset = Text.offset(State.lines[State.cursor1.line].data, State.cursor1.pos)
  table.insert(State.lines, State.cursor1.line+1, {mode='text', data=string.sub(State.lines[State.cursor1.line].data, byte_offset)})
  table.insert(State.line_cache, State.cursor1.line+1, {})
  State.lines[State.cursor1.line].data = string.sub(State.lines[State.cursor1.line].data, 1, byte_offset-1)
  Text.clear_screen_line_cache(State, State.cursor1.line)
  State.cursor1 = {line=State.cursor1.line+1, pos=1}
end

function Text.pageup(State)
  State.screen_top1 = Text.previous_screen_top1(State)
  State.cursor1 = {line=State.screen_top1.line, pos=State.screen_top1.pos}
  Text.move_cursor_down_to_next_text_line_while_scrolling_again_if_necessary(State)
  Text.redraw_all(State)  -- if we're scrolling, reclaim all fragments to avoid memory leaks
end

function Text.previous_screen_top1(State)
  -- duplicate some logic from love.draw
  -- does not modify State (except to populate line_cache)
  local loc2 = Text.to2(State, State.screen_top1)
  local y = App.screen.height - State.line_height
  while y >= State.top do
    if loc2.line == 1 and loc2.screen_line == 1 and loc2.screen_pos == 1 then break end
    if State.lines[loc2.line].mode == 'text' then
      y = y - State.line_height
    elseif State.lines[loc2.line].mode == 'drawing' then
      y = y - Drawing_padding_height - Drawing.pixels(State.lines[loc2.line].h, State.width)
    end
    loc2 = Text.previous_screen_line(State, loc2)
  end
  return Text.to1(State, loc2)
end

function Text.pagedown(State)
  State.screen_top1 = Text.screen_bottom1(State)
  State.cursor1 = {line=State.screen_top1.line, pos=State.screen_top1.pos}
  Text.move_cursor_down_to_next_text_line_while_scrolling_again_if_necessary(State)
  Text.redraw_all(State)  -- if we're scrolling, reclaim all fragments to avoid memory leaks
end

-- return the location of the start of the bottom-most line on screen
function Text.screen_bottom1(State)
  -- duplicate some logic from love.draw
  -- does not modify State (except to populate line_cache)
  local loc2 = Text.to2(State, State.screen_top1)
  local y = State.top
  while true do
    if State.lines[loc2.line].mode == 'text' then
      y = y + State.line_height
    elseif State.lines[loc2.line].mode == 'drawing' then
      y = y + Drawing_padding_height + Drawing.pixels(State.lines[loc2.line].h, State.width)
    end
    if y + State.line_height > App.screen.height then break end
    local next_loc2 = Text.next_screen_line(State, loc2)
    if Text.eq2(next_loc2, loc2) then break end
    loc2 = next_loc2
  end
  return Text.to1(State, loc2)
end

function Text.up(State)
  assert(State.lines[State.cursor1.line].mode == 'text', 'line is not text')
--?   print('up', State.cursor1.line, State.cursor1.pos, State.screen_top1.line, State.screen_top1.pos)
  local screen_line_starting_pos, screen_line_index = Text.pos_at_start_of_screen_line(State, State.cursor1)
  if screen_line_starting_pos == 1 then
--?     print('cursor is at first screen line of its line')
    -- line is done; skip to previous text line
    local new_cursor_line = State.cursor1.line
    while new_cursor_line > 1 do
      new_cursor_line = new_cursor_line-1
      if State.lines[new_cursor_line].mode == 'text' then
--?         print('found previous text line')
        State.cursor1 = {line=new_cursor_line, pos=nil}
        Text.populate_screen_line_starting_pos(State, State.cursor1.line)
        -- previous text line found, pick its final screen line
--?         print('has multiple screen lines')
        local screen_line_starting_pos = State.line_cache[State.cursor1.line].screen_line_starting_pos
--?         print(#screen_line_starting_pos)
        screen_line_starting_pos = screen_line_starting_pos[#screen_line_starting_pos]
        local screen_line_starting_byte_offset = Text.offset(State.lines[State.cursor1.line].data, screen_line_starting_pos)
        local s = string.sub(State.lines[State.cursor1.line].data, screen_line_starting_byte_offset)
        State.cursor1.pos = screen_line_starting_pos + Text.nearest_cursor_pos(State.font, s, State.cursor_x, State.left) - 1
        break
      end
    end
  else
    -- move up one screen line in current line
    assert(screen_line_index > 1, 'bumped up against top screen line in line')
    local new_screen_line_starting_pos = State.line_cache[State.cursor1.line].screen_line_starting_pos[screen_line_index-1]
    local new_screen_line_starting_byte_offset = Text.offset(State.lines[State.cursor1.line].data, new_screen_line_starting_pos)
    local s = string.sub(State.lines[State.cursor1.line].data, new_screen_line_starting_byte_offset)
    State.cursor1.pos = new_screen_line_starting_pos + Text.nearest_cursor_pos(State.font, s, State.cursor_x, State.left) - 1
--?     print('cursor pos is now '..tostring(State.cursor1.pos))
  end
  if Text.lt1(State.cursor1, State.screen_top1) then
    State.screen_top1 = {
      line=State.cursor1.line,
      pos=Text.pos_at_start_of_screen_line(State, State.cursor1),
    }
    Text.redraw_all(State)  -- if we're scrolling, reclaim all fragments to avoid memory leaks
  end
end

function Text.down(State)
  assert(State.lines[State.cursor1.line].mode == 'text', 'line is not text')
--?   print('down', State.cursor1.line, State.cursor1.pos, State.screen_top1.line, State.screen_top1.pos)
  assert(State.cursor1.pos, 'cursor has no pos')
  if Text.cursor_at_final_screen_line(State) then
    -- line is done, skip to next text line
--?     print('cursor at final screen line of its line')
    local new_cursor_line = State.cursor1.line
    while new_cursor_line < #State.lines do
      new_cursor_line = new_cursor_line+1
      if State.lines[new_cursor_line].mode == 'text' then
        State.cursor1 = {
          line = new_cursor_line,
          pos = Text.nearest_cursor_pos(State.font, State.lines[new_cursor_line].data, State.cursor_x, State.left),
        }
--?         print(State.cursor1.pos)
        break
      end
    end
    local screen_bottom1 = Text.screen_bottom1(State)
--?   print('down 2', State.cursor1.line, State.cursor1.pos, State.screen_top1.line, State.screen_top1.pos, screen_bottom1.line, screen_bottom1.pos)
    if State.cursor1.line > screen_bottom1.line then
--?       print('screen top before:', State.screen_top1.line, State.screen_top1.pos)
--?       print('scroll up preserving cursor')
      Text.snap_cursor_to_bottom_of_screen(State)
--?       print('screen top after:', State.screen_top1.line, State.screen_top1.pos)
    end
  else
    -- move down one screen line in current line
    local screen_bottom1 = Text.screen_bottom1(State)
    local scroll_down = Text.le1(screen_bottom1, State.cursor1)
--?     print('cursor is NOT at final screen line of its line')
    local screen_line_starting_pos, screen_line_index = Text.pos_at_start_of_screen_line(State, State.cursor1)
    Text.populate_screen_line_starting_pos(State, State.cursor1.line)
    local new_screen_line_starting_pos = State.line_cache[State.cursor1.line].screen_line_starting_pos[screen_line_index+1]
--?     print('switching pos of screen line at cursor from '..tostring(screen_line_starting_pos)..' to '..tostring(new_screen_line_starting_pos))
    local new_screen_line_starting_byte_offset = Text.offset(State.lines[State.cursor1.line].data, new_screen_line_starting_pos)
    local s = string.sub(State.lines[State.cursor1.line].data, new_screen_line_starting_byte_offset)
    State.cursor1.pos = new_screen_line_starting_pos + Text.nearest_cursor_pos(State.font, s, State.cursor_x, State.left) - 1
--?     print('cursor pos is now', State.cursor1.line, State.cursor1.pos)
    if scroll_down then
--?       print('scroll up preserving cursor')
      Text.snap_cursor_to_bottom_of_screen(State)
--?       print('screen top after:', State.screen_top1.line, State.screen_top1.pos)
    end
  end
--?   print('=>', State.cursor1.line, State.cursor1.pos, State.screen_top1.line, State.screen_top1.pos)
end

function Text.start_of_line(State)
  State.cursor1.pos = 1
  if Text.lt1(State.cursor1, State.screen_top1) then
    State.screen_top1 = {line=State.cursor1.line, pos=State.cursor1.pos}  -- copy
  end
end

function Text.end_of_line(State)
  State.cursor1.pos = utf8.len(State.lines[State.cursor1.line].data) + 1
  if Text.cursor_out_of_screen(State) then
    Text.snap_cursor_to_bottom_of_screen(State)
  end
end

function Text.word_left(State)
  -- skip some whitespace
  while true do
    if State.cursor1.pos == 1 then
      break
    end
    if Text.match(State.lines[State.cursor1.line].data, State.cursor1.pos-1, '%S') then
      break
    end
    Text.left(State)
  end
  -- skip some non-whitespace
  while true do
    Text.left(State)
    if State.cursor1.pos == 1 then
      break
    end
    assert(State.cursor1.pos > 1, 'bumped up against start of line')
    if Text.match(State.lines[State.cursor1.line].data, State.cursor1.pos-1, '%s') then
      break
    end
  end
end

function Text.word_right(State)
  -- skip some whitespace
  while true do
    if State.cursor1.pos > utf8.len(State.lines[State.cursor1.line].data) then
      break
    end
    if Text.match(State.lines[State.cursor1.line].data, State.cursor1.pos, '%S') then
      break
    end
    Text.right_without_scroll(State)
  end
  while true do
    Text.right_without_scroll(State)
    if State.cursor1.pos > utf8.len(State.lines[State.cursor1.line].data) then
      break
    end
    if Text.match(State.lines[State.cursor1.line].data, State.cursor1.pos, '%s') then
      break
    end
  end
  if Text.cursor_out_of_screen(State) then
    Text.snap_cursor_to_bottom_of_screen(State)
  end
end

function Text.match(s, pos, pat)
  local start_offset = Text.offset(s, pos)
  local end_offset = Text.offset(s, pos+1)
  assert(end_offset > start_offset, ('end_offset %d not > start_offset %d'):format(end_offset, start_offset))
  local curr = s:sub(start_offset, end_offset-1)
  return curr:match(pat)
end

function Text.left(State)
  assert(State.lines[State.cursor1.line].mode == 'text', 'line is not text')
  if State.cursor1.pos > 1 then
    State.cursor1.pos = State.cursor1.pos-1
  else
    local new_cursor_line = State.cursor1.line
    while new_cursor_line > 1 do
      new_cursor_line = new_cursor_line-1
      if State.lines[new_cursor_line].mode == 'text' then
        State.cursor1 = {
          line = new_cursor_line,
          pos = utf8.len(State.lines[new_cursor_line].data) + 1,
        }
        break
      end
    end
  end
  if Text.lt1(State.cursor1, State.screen_top1) then
    State.screen_top1 = {
      line=State.cursor1.line,
      pos=Text.pos_at_start_of_screen_line(State, State.cursor1),
    }
    Text.redraw_all(State)  -- if we're scrolling, reclaim all fragments to avoid memory leaks
  end
end

function Text.right(State)
  Text.right_without_scroll(State)
  if Text.cursor_out_of_screen(State) then
    Text.snap_cursor_to_bottom_of_screen(State)
  end
end

function Text.right_without_scroll(State)
  assert(State.lines[State.cursor1.line].mode == 'text', 'line is not text')
  if State.cursor1.pos <= utf8.len(State.lines[State.cursor1.line].data) then
    State.cursor1.pos = State.cursor1.pos+1
  else
    local new_cursor_line = State.cursor1.line
    while new_cursor_line <= #State.lines-1 do
      new_cursor_line = new_cursor_line+1
      if State.lines[new_cursor_line].mode == 'text' then
        State.cursor1 = {line=new_cursor_line, pos=1}
        break
      end
    end
  end
end

-- result: pos, index of screen line
function Text.pos_at_start_of_screen_line(State, loc1)
  Text.populate_screen_line_starting_pos(State, loc1.line)
  local line_cache = State.line_cache[loc1.line]
  for i=#line_cache.screen_line_starting_pos,1,-1 do
    local spos = line_cache.screen_line_starting_pos[i]
    if spos <= loc1.pos then
      return spos,i
    end
  end
  assert(false, ('invalid pos %d'):format(loc1.pos))
end

function Text.pos_at_end_of_screen_line(State, loc1)
  assert(State.lines[loc1.line].mode == 'text')
  Text.populate_screen_line_starting_pos(State, loc1.line)
  local line_cache = State.line_cache[loc1.line]
  local most_recent_final_pos = utf8.len(State.lines[loc1.line].data)+1
  for i=#line_cache.screen_line_starting_pos,1,-1 do
    local spos = line_cache.screen_line_starting_pos[i]
    if spos <= loc1.pos then
      return most_recent_final_pos
    end
    most_recent_final_pos = spos-1
  end
  assert(false, ('invalid pos %d'):format(loc1.pos))
end

function Text.final_text_loc_on_screen(State)
  local screen_bottom1 = Text.screen_bottom1(State)
  if State.lines[screen_bottom1.line].mode == 'text' then
    return {
      line=screen_bottom1.line,
      pos=Text.pos_at_end_of_screen_line(State, screen_bottom1),
    }
  end
  local loc2 = Text.to2(State, screen_bottom1)
  while true do
    if State.lines[loc2.line].mode == 'text' then break end
    assert(loc2.line > 1 or loc2.screen_line > 1 and loc2.screen_pos > 1)  -- elsewhere we're making sure there's always at least one text line on screen
    loc2 = Text.previous_screen_line(State, loc2)
  end
  local result = Text.to1(State, loc2)
  result.pos = Text.pos_at_end_of_screen_line(State, result)
  return result
end

function Text.cursor_at_final_screen_line(State)
  Text.populate_screen_line_starting_pos(State, State.cursor1.line)
  local screen_lines = State.line_cache[State.cursor1.line].screen_line_starting_pos
--?   print(screen_lines[#screen_lines], State.cursor1.pos)
  return screen_lines[#screen_lines] <= State.cursor1.pos
end

function Text.move_cursor_down_to_next_text_line_while_scrolling_again_if_necessary(State)
  local y = State.top
  while State.cursor1.line <= #State.lines do
    if State.lines[State.cursor1.line].mode == 'text' then
      break
    end
--?     print('cursor skips', State.cursor1.line)
    y = y + Drawing_padding_height + Drawing.pixels(State.lines[State.cursor1.line].h, State.width)
    State.cursor1.line = State.cursor1.line + 1
  end
  if State.cursor1.pos == nil then
    State.cursor1.pos = 1
  end
  -- hack: insert a text line at bottom of file if necessary
  if State.cursor1.line > #State.lines then
    assert(State.cursor1.line == #State.lines+1, 'tried to ensure bottom line of file is text, but failed')
    table.insert(State.lines, {mode='text', data=''})
    table.insert(State.line_cache, {})
  end
--?   print(y, App.screen.height, App.screen.height-State.line_height)
  if y > App.screen.height - State.line_height then
--?     print('scroll up')
    Text.snap_cursor_to_bottom_of_screen(State)
  end
end

-- should never modify State.cursor1
function Text.snap_cursor_to_bottom_of_screen(State)
--?   print('to2:', State.cursor1.line, State.cursor1.pos)
  local top2 = Text.to2(State, State.cursor1)
--?   print('to2: =>', top2.line, top2.screen_line, top2.screen_pos)
  -- slide to start of screen line
  top2.screen_pos = 1  -- start of screen line
--?   print('snap', State.screen_top1.line, State.screen_top1.pos, State.cursor1.line, State.cursor1.pos)
--?   print('cursor pos '..tostring(State.cursor1.pos)..' is on the #'..tostring(top2.screen_line)..' screen line down')
  local y = App.screen.height - State.line_height
  -- duplicate some logic from love.draw
  while true do
--?     print(y, 'top2:', top2.line, top2.screen_line, top2.screen_pos)
    if top2.line == 1 and top2.screen_line == 1 then break end
    if top2.screen_line > 1 or State.lines[top2.line-1].mode == 'text' then
      local h = State.line_height
      if y - h < State.top then
        break
      end
      y = y - h
    else
      assert(top2.line > 1, 'tried to snap cursor to buttom of screen but failed')
      assert(State.lines[top2.line-1].mode == 'drawing', "expected a drawing but it's not")
      -- We currently can't draw partial drawings, so either skip it entirely
      -- or not at all.
      local h = Drawing_padding_height + Drawing.pixels(State.lines[top2.line-1].h, State.width)
      if y - h < State.top then
        break
      end
--?       print('skipping drawing of height', h)
      y = y - h
    end
    top2 = Text.previous_screen_line(State, top2)
  end
--?   print('top2 finally:', top2.line, top2.screen_line, top2.screen_pos)
  State.screen_top1 = Text.to1(State, top2)
--?   print('top1 finally:', State.screen_top1.line, State.screen_top1.pos)
--?   print('snap =>', State.screen_top1.line, State.screen_top1.pos, State.cursor1.line, State.cursor1.pos)
  Text.redraw_all(State)  -- if we're scrolling, reclaim all fragments to avoid memory leaks
end

function Text.in_line(State, line_index, x,y)
  local line = State.lines[line_index]
  local line_cache = State.line_cache[line_index]
  if line_cache.starty == nil then return false end  -- outside current page
  if y < line_cache.starty then return false end
  Text.populate_screen_line_starting_pos(State, line_index)
  return y < line_cache.starty + State.line_height*(#line_cache.screen_line_starting_pos - Text.screen_line_index(line_cache.screen_line_starting_pos, line_cache.startpos) + 1)
end

-- convert mx,my in pixels to schema-1 coordinates
function Text.to_pos_on_line(State, line_index, mx, my)
  local line = State.lines[line_index]
  local line_cache = State.line_cache[line_index]
  assert(my >= line_cache.starty, 'failed to map y pixel to line')
  -- duplicate some logic from Text.draw
  local y = line_cache.starty
  local start_screen_line_index = Text.screen_line_index(line_cache.screen_line_starting_pos, line_cache.startpos)
  for screen_line_index = start_screen_line_index,#line_cache.screen_line_starting_pos do
    local screen_line_starting_pos = line_cache.screen_line_starting_pos[screen_line_index]
    local screen_line_starting_byte_offset = Text.offset(line.data, screen_line_starting_pos)
--?     print('iter', y, screen_line_index, screen_line_starting_pos, string.sub(line.data, screen_line_starting_byte_offset))
    local nexty = y + State.line_height
    if my < nexty then
      -- On all wrapped screen lines but the final one, clicks past end of
      -- line position cursor on final character of screen line.
      -- (The final screen line positions past end of screen line as always.)
      if screen_line_index < #line_cache.screen_line_starting_pos and mx > State.left + Text.screen_line_width(State, line_index, screen_line_index) then
--?         print('past end of non-final line; return')
        return line_cache.screen_line_starting_pos[screen_line_index+1]
      end
      local s = string.sub(line.data, screen_line_starting_byte_offset)
--?       print('return', mx, Text.nearest_cursor_pos(State.font, s, mx, State.left), '=>', screen_line_starting_pos + Text.nearest_cursor_pos(State.font, s, mx, State.left) - 1)
      return screen_line_starting_pos + Text.nearest_cursor_pos(State.font, s, mx, State.left) - 1
    end
    y = nexty
  end
  assert(false, 'failed to map y pixel to line')
end

function Text.screen_line_width(State, line_index, i)
  local line = State.lines[line_index]
  local line_cache = State.line_cache[line_index]
  local start_pos = line_cache.screen_line_starting_pos[i]
  local start_offset = Text.offset(line.data, start_pos)
  local screen_line
  if i < #line_cache.screen_line_starting_pos then
    local past_end_pos = line_cache.screen_line_starting_pos[i+1]
    local past_end_offset = Text.offset(line.data, past_end_pos)
    screen_line = string.sub(line.data, start_offset, past_end_offset-1)
  else
    screen_line = string.sub(line.data, start_pos)
  end
  return State.font:getWidth(screen_line)
end

function Text.screen_line_index(screen_line_starting_pos, pos)
  for i = #screen_line_starting_pos,1,-1 do
    if screen_line_starting_pos[i] <= pos then
      return i
    end
  end
end

-- convert x pixel coordinate to pos
-- oblivious to wrapping
-- result: 1 to len+1
function Text.nearest_cursor_pos(font, line, x, left)
  if x < left then
    return 1
  end
  local len = utf8.len(line)
  local max_x = left+Text.x(font, line, len+1)
  if x > max_x then
    return len+1
  end
  local leftpos, rightpos = 1, len+1
--?   print('-- nearest', x)
  while true do
--?     print('nearest', x, '^'..line..'$', leftpos, rightpos)
    if leftpos == rightpos then
      return leftpos
    end
    local curr = math.floor((leftpos+rightpos)/2)
    local currxmin = left+Text.x(font, line, curr)
    local currxmax = left+Text.x(font, line, curr+1)
--?     print('nearest', x, leftpos, rightpos, curr, currxmin, currxmax)
    if currxmin <= x and x < currxmax then
      if x-currxmin < currxmax-x then
        return curr
      else
        return curr+1
      end
    end
    if leftpos >= rightpos-1 then
      return rightpos
    end
    if currxmin > x then
      rightpos = curr
    else
      leftpos = curr
    end
  end
  assert(false, 'failed to map x pixel to pos')
end

-- return the nearest index of line (in utf8 code points) which lies entirely
-- within x pixels of the left margin
-- result: 0 to len+1
function Text.nearest_pos_less_than(font, line, x)
--?   print('', '-- nearest_pos_less_than', line, x)
  local len = utf8.len(line)
  local max_x = Text.x_after(font, line, len)
  if x > max_x then
    return len+1
  end
  local left, right = 0, len+1
  while true do
    local curr = math.floor((left+right)/2)
    local currxmin = Text.x_after(font, line, curr+1)
    local currxmax = Text.x_after(font, line, curr+2)
--?     print('', x, left, right, curr, currxmin, currxmax)
    if currxmin <= x and x < currxmax then
      return curr
    end
    if left >= right-1 then
      return left
    end
    if currxmin > x then
      right = curr
    else
      left = curr
    end
  end
  assert(false, 'failed to map x pixel to pos')
end

function Text.x_after(font, s, pos)
  local len = utf8.len(s)
  local offset = Text.offset(s, math.min(pos+1, len+1))
  local s_before = s:sub(1, offset-1)
--?   print('^'..s_before..'$')
  return font:getWidth(s_before)
end

function Text.x(font, s, pos)
  local offset = Text.offset(s, pos)
  local s_before = s:sub(1, offset-1)
  return font:getWidth(s_before)
end

function Text.to2(State, loc1)
  if State.lines[loc1.line].mode == 'drawing' then
    return {line=loc1.line, screen_line=1, screen_pos=1}
  end
  local result = {line=loc1.line}
  local line_cache = State.line_cache[loc1.line]
  Text.populate_screen_line_starting_pos(State, loc1.line)
  for i=#line_cache.screen_line_starting_pos,1,-1 do
    local spos = line_cache.screen_line_starting_pos[i]
    if spos <= loc1.pos then
      result.screen_line = i
      result.screen_pos = loc1.pos - spos + 1
      break
    end
  end
  assert(result.screen_pos, 'failed to convert schema-1 coordinate to schema-2')
  return result
end

function Text.to1(State, loc2)
  local result = {line=loc2.line, pos=loc2.screen_pos}
  if loc2.screen_line > 1 then
    result.pos = State.line_cache[loc2.line].screen_line_starting_pos[loc2.screen_line] + loc2.screen_pos - 1
  end
  return result
end

function Text.eq1(a, b)
  return a.line == b.line and a.pos == b.pos
end

function Text.lt1(a, b)
  if a.line < b.line then
    return true
  end
  if a.line > b.line then
    return false
  end
  return a.pos < b.pos
end

function Text.le1(a, b)
  if a.line < b.line then
    return true
  end
  if a.line > b.line then
    return false
  end
  return a.pos <= b.pos
end

function Text.eq2(a, b)
  return a.line == b.line and a.screen_line == b.screen_line and a.screen_pos == b.screen_pos
end

function Text.offset(s, pos1)
  if pos1 == 1 then return 1 end
  local result = utf8.offset(s, pos1)
  if result == nil then
    assert(false, ('Text.offset(%d) called on a string of length %d (byte size %d); this is likely a failure to handle utf8\n\n^%s$\n'):format(pos1, utf8.len(s), #s, s))
  end
  return result
end

function Text.previous_screen_line(State, loc2)
  if loc2.screen_line > 1 then
    return {line=loc2.line, screen_line=loc2.screen_line-1, screen_pos=1}
  elseif loc2.line == 1 then
    return loc2
  elseif State.lines[loc2.line-1].mode == 'drawing' then
    return {line=loc2.line-1, screen_line=1, screen_pos=1}
  else
    local l = State.lines[loc2.line-1]
    Text.populate_screen_line_starting_pos(State, loc2.line-1)
    return {line=loc2.line-1, screen_line=#State.line_cache[loc2.line-1].screen_line_starting_pos, screen_pos=1}
  end
end

function Text.next_screen_line(State, loc2)
  if State.lines[loc2.line].mode == 'drawing' then
    return {line=loc2.line+1, screen_line=1, screen_pos=1}
  end
  Text.populate_screen_line_starting_pos(State, loc2.line)
  if loc2.screen_line >= #State.line_cache[loc2.line].screen_line_starting_pos then
    if loc2.line < #State.lines then
      return {line=loc2.line+1, screen_line=1, screen_pos=1}
    else
      return loc2
    end
  else
    return {line=loc2.line, screen_line=loc2.screen_line+1, screen_pos=1}
  end
end

-- resize helper
function Text.tweak_screen_top_and_cursor(State)
  if State.screen_top1.pos == 1 then return end
  Text.populate_screen_line_starting_pos(State, State.screen_top1.line)
  local line = State.lines[State.screen_top1.line]
  local line_cache = State.line_cache[State.screen_top1.line]
  for i=2,#line_cache.screen_line_starting_pos do
    local pos = line_cache.screen_line_starting_pos[i]
    if pos == State.screen_top1.pos then
      break
    end
    if pos > State.screen_top1.pos then
      -- make sure screen top is at start of a screen line
      local prev = line_cache.screen_line_starting_pos[i-1]
      if State.screen_top1.pos - prev < pos - State.screen_top1.pos then
        State.screen_top1.pos = prev
      else
        State.screen_top1.pos = pos
      end
      break
    end
  end
  -- make sure cursor is on screen
  local screen_bottom1 = Text.screen_bottom1(State)
  if Text.lt1(State.cursor1, State.screen_top1) then
    State.cursor1 = {line=State.screen_top1.line, pos=State.screen_top1.pos}
  elseif State.cursor1.line >= screen_bottom1.line then
--?     print('too low')
    if Text.cursor_out_of_screen(State) then
--?       print('tweak')
      State.cursor1 = {
          line=screen_bottom1.line,
          pos=Text.to_pos_on_line(State, screen_bottom1.line, State.right-5, App.screen.height-5),
      }
    end
  end
end

-- slightly expensive since it redraws the screen
function Text.cursor_out_of_screen(State)
  edit.draw(State)
  return State.cursor_y == nil
end

function Text.redraw_all(State)
--?   print('clearing fragments')
  -- Perform some early sanity checking here, in hopes that we correctly call
  -- this whenever we change editor state.
  if State.right <= State.left then
    assert(false, ('Right margin %d must be to the right of the left margin %d'):format(State.right, State.left))
  end

  State.line_cache = {}
  for i=1,#State.lines do
    State.line_cache[i] = {}
  end
end

function Text.clear_screen_line_cache(State, line_index)
  State.line_cache[line_index].screen_line_starting_pos = nil
  State.line_cache[line_index].link_offsets = nil
end

function trim(s)
  return s:gsub('^%s+', ''):gsub('%s+$', '')
end

function ltrim(s)
  return s:gsub('^%s+', '')
end

function rtrim(s)
  return s:gsub('%s+$', '')
end

function starts_with(s, prefix)
  if #s < #prefix then
    return false
  end
  for i=1,#prefix do
    if s:sub(i,i) ~= prefix:sub(i,i) then
      return false
    end
  end
  return true
end

function ends_with(s, suffix)
  if #s < #suffix then
    return false
  end
  for i=0,#suffix-1 do
    if s:sub(#s-i,#s-i) ~= suffix:sub(#suffix-i,#suffix-i) then
      return false
    end
  end
  return true
end