akashnag/ash

A modern terminal text editor

ash is a simple and clean terminal-based text editor, that aims to be easy to use with modern key-bindings. It is capable of handling multiple files simultaneously and has a wide array of modern features. Here is a picture of ash editing this README file:

ash is written in Python 3.8 using the curses library.

Table of Contents

• Features
• Release Notes
• Requirements
• Installation
  • Prerequisites
  • Installing ash
  • Uninstalling ash
  • Setting paths
• Prebuilt binaries
• Customization
• Usage
• Contributing
• Screenshots
• License

---

Features

The following is a list of features available in ash:

• Easy to use, clean and intuitive interface
• Common key bindings (Help on F1, Arrow keys for movement, Shift+Arrow/Home/End/PgUp/PgDown for selecting text, cut/copy/paste using Ctrl+X/C/V, undo/redo using Ctrl+Z/Y, find/replace/goto using Ctrl+F/H/G, etc.) and support for remapping key bindings to your taste
• Common editor features such as undo/redo, line numbers, find-replace, cut-copy-paste, etc.
• True support for wrapping (both hard & soft) with intuitive cursor movements along wrapped text
• Multi-file editing with support for windows and tabs
• Auto-backup
• Support for Unicode
• Project mode (opening a directory instead of individual files)
• Complete session (for projects) and undo persistence (turned on for projects opened directly from command-line)
• Live search
• Support for search/replace in all open files
• Support for searching using regular expressions
• Auto-indentation, Select+Tab/Shift-Tab to increase/decrease indent
• Auto insertion of matching braces/quotes and auto-enclosure when text is selected and braces/quotes are typed
• Support for unlimited splits per tab (subject to screen size) and support for unlimited tabs
• Support for various text-encodings
• Checks (live) and reloads (if user permits) files which have been modified externally
• Selection highlighting (highlights text under selection wherever they occur in the document)
• Color scheme customization
• View list of recent files, view project explorer (in project mode)
• Syntax highlighting (limited)
• Git integration (shows untracked, modified files, etc.)
• Multiple Cursors
• Command palette
• Basic mouse support (click to select, right-click, drag to select text, double-click to select word, triple-click to select line, drag to move dialog-boxes, etc.)
• Open terminal / execute shell commands
• Limited IDE features like compile, build, execute...
• Supports project/folder specific settings along with global settings
• Multi-language support
• Support for snippets

Requirements

1. You need a resolution of at least 102 x 22 in your terminal emulator
2. Your terminal must support Unicode and be able to display at least 256 colors with the capability of remapping color palettes (Works best on: xterm-256). Monochrome terminals are also partially supported.
3. If you are running the source distribution, you need the GNU C compiler collection besides Python 3.8, as some parts of the application are written in Cython. The first time you run the application, Cython will compile and build the *.pyx files, which may increase load time (Ignore the warnings during compilation)

ash is primarily targetted to Linux. This version of ash has only been tested on Ubuntu 20.04 with Python 3.8.2 (64-bit)

Installation

Note: Instructions provided here are for Debian/Ubuntu based systems. For your distribution, you may need to issue different instructions to install the necessary packages.

Prerequisites

You need certain packages and Python 3 itself to run ash on your system, as there are no prebuilt binaries available yet.

$ sudo apt install git
$ sudo apt install xclip
$ sudo apt install python3
$ sudo apt install python3-pip

Depending on your system, you may also need to install the following packages:

$ sudo apt install python3-devel

Installing ash

You have multiple options here:

• Install from PyPi (recommended)
• Install the latest stable release from GitHub
• Install the latest nightly release from GitHub
• Build and install from source

Install from PyPi

Execute the following instructions to install from PyPi:

$ sudo pip3 install ash-editor

The above command downloads ash and installs it locally on your system. To be able to invoke ash from anywhere, see the Setting Paths section.

Install the latest stable release

Note: the stable release may not contain all features listed above

Go to the ash Website and download the latest stable release. Then extract the downloaded tar-ball into a folder and once inside that folder, open up your terminal from there and execute:

$ sudo pip3 install .

Install the latest nightly release

The nightly builds contains all the latest features of ash. Go to the ash Website and download the latest nightly release. Then extract the downloaded tar-ball into a folder and once inside that folder, open up your terminal from there and execute:

$ sudo pip3 install .

Build from source and install

To build from source, issue the following instructions:

$ sudo apt install git
$ cd ~
$ git clone --depth 1 -b master https://github.com/akashnag/ash.git
$ cd ash
$ python3 setup.py sdist

(Though you can install it directly from here, it is not recommended) You will find the new tar-ball created under dist directory, from where you can proceed as before by first copying the tarball into a new directory, extracting it, and then installing it.

Setting paths

To run ash make sure you have :$HOME/.local/bin appended to your $PATH variable in the file ~/.bashrc (If you are using bash as your shell. If not open your corresponding .rc file). To execute ash, see the Usage section.

Uninstalling ash

To uninstall ash you can use:

$ sudo pip3 uninstall ash-editor

Prebuilt binaries

Since ash is still under development, prebuilt binaries are not yet available. You can use PyInstaller or similar tools to build one for your system.

Usage

Once you have downloaded the ash source code, and set it up as detailed above, you are ready to use it.

NOTES:

1. If you have not updated your path variable, you must specify the full path to the ash binary.
2. Your terminal resolution should be at least 102 (width) x 22 (height). Opening the editor in a lower resolution may unexpectedly crash the application. This requirement is necessary to properly display the dialog-boxes.
3. It will take a while to start up ash for the first time, this is normal. From the second time onwards, it should start up faster.

To run ash:

$ ash path/to/file.txt

or, to open an empty buffer:

$ ash

or, to open a project (directory):

$ ash path/to/directory

See the Key Bindings for help on how to navigate in ash.

Contributing

Contributing to the source code

If you find any bugs, please report them. I am also happy to accept pull requests from anyone for either bug-fixes, performance improvements, or for implementing the not-yet-implemented features listed above. Please consider contributing towards new features only when the features listed above have been fully implemented. For more information on what features to implement and the project structure, see the Contribution Guidelines

Bug-fixes and feature enhancements

You can use the GitHub issue tracker to report bugs, ask questions, or suggest new features. You can include the log if that is relevant, which can be found in ~/.config/ash-editor/log.txt.

Discussions

For discussions related to the development roadmap and the ash editor in general, you can join the ash Discord Server.

Say Thanks!

If you are not into software development, you can still contribute financially. Financial contributions help me prioritize working on this project over others and helps me know that there is a real demand for this software.

Screenshots

License

Copyright © Akash Nag. All rights reserved.

Licensed under the GPL-2.0 license.

ash's Issues

Rapid mouse clicks eventually crash Ash

When I open a file and do nothing but click the mouse rapidly in different parts of the screen, it works for a while and then crashes as below with getmouse returning ERR. I am using

on Kubuntu 20.04. I will see if I can find a more accurate method for reproducing the problem....

ash movies.html

Traceback (most recent call last):
  File "/usr/local/bin/ash", line 8, in <module>
    sys.exit(run())
  File "/usr/local/lib/python3.8/dist-packages/ash/ash_main.py", line 16, in run
    app.run()
  File "/usr/local/lib/python3.8/dist-packages/ash/main.py", line 112, in run
    ret_code = curses.wrapper(self.app_main)
  File "/usr/lib/python3.8/curses/__init__.py", line 105, in wrapper
    return func(stdscr, *args, **kwds)
  File "/usr/local/lib/python3.8/dist-packages/ash/main.py", line 182, in app_main
    self.main_window.show(welcome_msg)          # this call returns when main_window() is closed
  File "/usr/local/lib/python3.8/dist-packages/ash/gui/topLevelWindow.py", line 123, in show
    btn, y, x = KeyBindings.get_mouse(ch)
  File "/usr/local/lib/python3.8/dist-packages/ash/utils/keyUtils.py", line 55, in get_mouse
    _, x, y, _, bstate = curses.getmouse()
_curses.error: getmouse() returned ERR

No menu bar when I start Ash

Nice work! Please tell me how to get a menu bar when the editor starts? The menu bar displayed in the image below is for the terminal. It would be helpful to have a menu bar for Ash as well as displayed in the excellent screenshots in README.md .

Wont start on AWS

trying to install and run ash on Debian:

sudo pip3 install ash-editor

admin:~$ ash
Traceback (most recent call last):
  File "/usr/local/bin/ash", line 8, in <module>
    sys.exit(run())
  File "/usr/local/lib/python3.7/dist-packages/ash/ash_main.py", line 16, in run
    app.run()
  File "/usr/local/lib/python3.7/dist-packages/ash/main.py", line 112, in run
    ret_code = curses.wrapper(self.app_main)
  File "/usr/lib/python3.7/curses/__init__.py", line 94, in wrapper
    return func(stdscr, *args, **kwds)
  File "/usr/local/lib/python3.7/dist-packages/ash/main.py", line 153, in app_main
    self.theme_manager = ThemeManager(self)
  File "/usr/local/lib/python3.7/dist-packages/ash/formatting/themeManager.py", line 15, in __init__
    self.init_colors()
  File "/usr/local/lib/python3.7/dist-packages/ash/formatting/themeManager.py", line 45, in init_colors
    set_colors(colors, element_colors)
  File "/usr/local/lib/python3.7/dist-packages/ash/formatting/colors.py", line 148, in set_colors
    curses.init_color(index, rgb[0], rgb[1], rgb[2])
_curses.error: init_color() returned ERR

I'm connected via Putty, and it supports colors (eg. htop is green)

[BUG] 100% thread usage while running ash

Whenever I start ash, one of the cpu threads spikes up to 100% and stays there.

To Reproduce

1. Install ash via suggested
   sudo pip3 install ash-editor
2. Add it to path
3. Start ash
4. Observe the performance issue

Expected behavior
Less than 100% cpu usage.

Desktop (please complete the following information):

• OS: Arch 5.14.6-arch1-1
• Version: 0.1.0.dev7
• Shell: zsh

Additional context
Using bash produces the same result

Please tag a release

Hi there,

Your repository holds a “nightly build” in the dist directory. Could you instead just tag a release and upload it to PyPI?

I'm trying to build a package of your nice editor for the FreeBSD Ports Collection but the way you do provide nightly builds is very inconvenient for this purpose.

Everything black through SSH with Putty

Bug:
Installed successfully using pip3 (v23.0.1), but when typing ash nothing happens to the propmpt. Pressing CTRL-C gets back to bash. After uninstalling all packages and reinstalling on different machines, the program now actually runs on one of them (WHY? nothing has changed!), but everything on the screen is black (the screen size is more than the minimum required).

Steps to Reproduce

1. $ python3 -m pip install ash-editor
2. $ ash

OS:

• OS: Linux 5.10.0-18-686 / Devuan GNU/Linux 4 (chimaera)
• From Windows 10 Home x64 with Kitty SSH client (or also on the local linux machine, if using xfce-terminal, but it works on local machine with KDE Konsole)

THIS IS THE BEST TUI CUA TEXT EDITOR I HAVE EVER SEEN ON LINUX!

ISPF Edit

Ash reminds me strongly of the splendid and venerable ISPF editor:

https://www.ibm.com/docs/en/zos-basic-skills?topic=ispf-editor

One of the major features of this editor is that you could enter commands into the line numbers column, such as d5 to delete the next five lines or r4 to repeat the current line 4 times. Can I interest you in adding these useful row commands to Ash?

i
    Insert a line
Enter
    Press Enter without entering anything to escape insert mode
i5
    Obtain five input lines
d
    Delete a line
d5
    Delete five lines
dd/dd
    Delete a block of lines
r
    Repeat a line
rr/rr
    Repeat a block of lines
c
    With a or b: Copy a line after or before
c5
    With a or b: Copy five lines after or before
cc/cc
    With a or b: Copy a block of lines after or before
m
    Move lines. As with copy commands, m5, mm/mm and use with a or b are also valid commands.
x
    Exclude a line 

Esc does not remove the menu

After displaying the menu bar with alt+ down I have to press alt+up twice to remove the menu bar. It would be nice if I could just push Esc to remove the menu bar (and indeed any other dialog). And if there is no dialog and no menu bar present, Esc could perhaps bring the menu back again? This sequence of actions would be familiar to many people who might be unaware of the alt+down or up sequence?

[CR] Consider moving Config Files to ~/.config/ash-editor instead of creating ~/.ash-editor

Describe the change
Probably a minor thing, but it's good practice to not "clutter" the users Home directory and instead put your configs in ~/.config/ . There might be a reason not to, so this is more of a "discussion" topic, than a request.

[BUG] Error when install on Ubuntu 24.04

Describe the bug
Try to install Ash via sudo pip3 install ash-editor as described in ash readme. Got big error message:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. 
You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Do I really need venv and do other things for Ash? Excuse me for such questions, I'm newbie in python.

Desktop (please complete the following information):

• OS: Ubuntu 24.04
• Version: from python repo

[BUG] Opening a non User writable File and saving it causes a traceback

Describe the bug
When opening a non User writable file without sudo, ash open the file and let's you make changes. On Saving or Quitting ash crashes and Produces a Traceback. The changes are not written and the User doesn't get information on the issue.

To Reproduce
Steps to reproduce the behavior:

1. Open any system file that isn't writable by the user
2. Make any change to the file
3. Quit or Save and Quit
4. See error

Expected behavior
Some options:

• Inform the User on opening the file that it isn't writable
• Inform on trying to make changes that they can't be saved
• Inform on Saving the File that this isn't possible
• Don't open the file at all with a Feedback on the commandline
  The User needs to get some kind of Feedback on what's happening and some error Handling needs to be in Place.

Log

Traceback (most recent call last):
  File "/home/user/.local/bin/ash", line 33, in <module>
    sys.exit(load_entry_point('ash-editor==0.1.0.dev13', 'console_scripts', 'ash')())
  File "/home/user/.local/lib/python3.10/site-packages/ash/ash_main.py", line 16, in run
    app.run()
  File "/home/user/.local/lib/python3.10/site-packages/ash/main.py", line 128, in run
    ret_code = curses.wrapper(self.app_main)
  File "/usr/lib64/python3.10/curses/__init__.py", line 94, in wrapper
    return func(stdscr, *args, **kwds)
  File "/home/user/.local/lib/python3.10/site-packages/ash/main.py", line 197, in app_main
    self.main_window.show(welcome_msg)		# this call returns when main_window() is closed		
  File "/home/user/.local/lib/python3.10/site-packages/ash/gui/topLevelWindow.py", line 139, in show
    aed.perform_action(ch)
  File "/home/user/.local/lib/python3.10/site-packages/ash/gui/editor.py", line 170, in perform_action
    edit_made = self.keyHandler.handle_keys(ch)
  File "/home/user/.local/lib/python3.10/site-packages/ash/gui/editorKeyHandler.py", line 30, in handle_keys
    self.save_and_close()
  File "/home/user/.local/lib/python3.10/site-packages/ash/gui/editorKeyHandler.py", line 63, in save_and_close
    self.handle_save()
  File "/home/user/.local/lib/python3.10/site-packages/ash/gui/editorKeyHandler.py", line 426, in handle_save
    self.ed.buffer.write_to_disk()
  File "/home/user/.local/lib/python3.10/site-packages/ash/core/bufferManager.py", line 197, in write_to_disk
    self.write_a_copy(self.filename, self.encoding)
  File "/home/user/.local/lib/python3.10/site-packages/ash/core/bufferManager.py", line 184, in write_a_copy
    textFile = codecs.open(filename, "w", encoding)
  File "/usr/lib64/python3.10/codecs.py", line 905, in open
    file = builtins.open(filename, mode, buffering)

Desktop (please complete the following information):

• OS: Fedora 36
• Version 0.1.0 dev12

[BUG] Ash crash on window click

Whenever I click in the opened ash window it crashes. This seems to be caused by clicking on a not-yet-created-line. If I create 5 lines (hitting Enter), I can jump between them freely by clicking on them.

The KeyError is dependent on the row you clicked.

To Reproduce

1. Install ash via suggested
   sudo pip3 install ash-editor
2. Add it to path
3. Start ash
4. Click in the ash window where there are no lines
5. Observe the crash

Expected behavior
Not to crash

Desktop (please complete the following information):

• OS: Arch 5.14.6-arch1-1
• Version: 0.1.0.dev7
• Shell: zsh

Additional context
Using bash produces the same result

Here is the traceback. The KeyError is different every time

Traceback (most recent call last):
  File "/usr/bin/ash", line 33, in <module>
    sys.exit(load_entry_point('ash-editor==0.1.0.dev7', 'console_scripts', 'ash')())
  File "/usr/lib/python3.9/site-packages/ash/ash_main.py", line 16, in run
    app.run()
  File "/usr/lib/python3.9/site-packages/ash/main.py", line 112, in run
    ret_code = curses.wrapper(self.app_main)
  File "/usr/lib/python3.9/curses/__init__.py", line 94, in wrapper
    return func(stdscr, *args, **kwds)
  File "/usr/lib/python3.9/site-packages/ash/main.py", line 182, in app_main
    self.main_window.show(welcome_msg)          # this call returns when main_window() is closed
  File "/usr/lib/python3.9/site-packages/ash/gui/topLevelWindow.py", line 131, in show
    w.on_click(ry,rx)
  File "/usr/lib/python3.9/site-packages/ash/gui/editor.py", line 340, in on_click
    curpos = self.screen.get_curpos_after_click(y, x, self.buffer.lines, self.width, self.tab_size, self.word_wrap, self.hard_wrap)
  File "screen.pyx", line 702, in ash.core.screen.Screen.get_curpos_after_click
  File "screen.pyx", line 387, in ash.core.screen.Screen.translate_rendered_curpos_to_real_curpos
KeyError: 25```

Select line does not highlight the selected line

I then go to edit, choose select line and the display stays the same. I would expect the selected line to be highlighted as it is when I chose select all. It would be nice if one could type s5 in the line numbers and have the next five lines selected.

Softwrap, wrap long lines option question

Hello. New ash user here (non-technical user)

Great project, I love it. Thanks for ash.

I've tried to find the option in order to wrap the long lines. I cant find any.
Is there an option to wrap the long lines?

Add git as a prerequisite for install

I was on a fresh install trying to use and I run into the following error:

Traceback (most recent call last):
  File "/usr/local/lib/python3.7/dist-packages/git/__init__.py", line 83, in <module>
    refresh()
  File "/usr/local/lib/python3.7/dist-packages/git/__init__.py", line 73, in refresh
    if not Git.refresh(path=path):
  File "/usr/local/lib/python3.7/dist-packages/git/cmd.py", line 278, in refresh
    raise ImportError(err)
ImportError: Bad git executable.
The git executable must be specified in one of the following ways:
    - be included in your $PATH
    - be set via $GIT_PYTHON_GIT_EXECUTABLE
    - explicitly set via git.refresh()

All git commands will error until this is rectified.

This initial warning can be silenced or aggravated in the future by setting the
$GIT_PYTHON_REFRESH environment variable. Use one of the following values:
    - quiet|q|silence|s|none|n|0: for no warning or exception
    - warn|w|warning|1: for a printed warning
    - error|e|raise|r|2: for a raised exception

Example:
    export GIT_PYTHON_REFRESH=quiet

the problem went away when I installed git, so I would recommend you to add on your website for better documentation

[BUG] python3-devel is a required dependency on Fedora 36

Describe the bug
When Following the "Installation" Part of the readme and installing the Prerequisites as mentioned, launching ash fails because "Python.H" is missing. This is solved by installing python3-devel

To Reproduce
Steps to reproduce the behavior:

1. Install Prerequesits as mentioned in the readme
2. Install ash through pip
3. start ash

Expected behavior
Either ash should launch with the current installation Instructions, or they need to be updated to include the Dependency.

Log

/home/user/.pyxbld/temp.linux-x86_64-3.10/pyrex/ash/core/screen.c:6:10: schwerwiegender Fehler: Python.h: Datei oder Verzeichnis nicht gefunden
    6 | #include "Python.h"
      |          ^~~~~~~~~~
Kompilierung beendet.
Traceback (most recent call last):
  File "/usr/lib64/python3.10/distutils/unixccompiler.py", line 126, in _compile
    self.spawn(compiler_so + cc_args + [src, '-o', obj] +
  File "/usr/lib64/python3.10/distutils/ccompiler.py", line 910, in spawn
    spawn(cmd, dry_run=self.dry_run)
  File "/usr/lib64/python3.10/distutils/spawn.py", line 91, in spawn
    raise DistutilsExecError(
distutils.errors.DistutilsExecError: command '/usr/bin/gcc' failed with exit code 1

Desktop (please complete the following information):

• OS: Fedora 36
• Version 0.1.0 dev (build 12)

Problem with the name 'ash' says reddit

I've shared ash on reddit. Looks like the name ash is already taken and/or misleading.

[FEATURE]Better Mouse Support

Currently, clicking anywhere at least puts the cursor to that position. ash blocks the terminals "drag to Select" implementation and only support CTRL+Movement to mark.
While i recognize that this is a terminal first editor, some support for the mouse would be appreciated, especially when almost all alternatives support it in some from or another. Some of it seems to work already. At least the help window can be dismissed by clicking on the "x". From the top of my head:

• Drag to Select
• Mouse Wheel Scroll
• Clicking in Menus
• Shift+Click to Select
• Ctrl+Alt+Click for Multi-Edits