bitseme

This file provides a general overview of this project.

Status

WARNING: This project is currently in an alpha development state and is not ready for production use.

Documentation

• Building and Installing: INSTALL.md
• Required and Optional Dependencies: REQUIREMENTS.md
• Development Roadmap: ROADMAP.md

For documentation of the libbitseme library, please enable its documentation to be built (see INSTALL.md) and view the resulting output.

Description

bitseme is a browser (and manipulator) of interactive text streams.

TL;DR: Bitseme is like a more modern version of w3m or elinks (web), mutt or alpine (mail), or whatever else you want it to be like. Bitseme aims to be for text (and text-rendered graphics) what Wireshark (or, perhaps more aptly, TShark) is for packets. Bitseme provides a minimal core of system and networking primitives coupled with a scripting API, which includes backend-agnostic UI widgets, to enable customizable end-user experiences of text-based communication content.

Bitseme can be used to interactively browse any protocol, communication, or data that can be displayed textually (i.e., in a terminal). This includes HTTP and HTML, Gopher, IMAP emails, Markdown, IRC, plain text files on the local filesystem, etc. Although bitseme focuses on text, it can also render graphics (such as referenced in image tags in HTML), either natively if the terminal supports it (such as framebuffer terminals like fbterm or graphics-capable GUI terminals such as kitty or foot), or via complex character cell interpolations. More specifically, it can display anything supported by the combination of the UI rendering backend (such as notcurses) and your UI environment (such as your terminal).

Bitseme separates protocols, content, and presentation. Each aspect can be separately combined and chained with any of the others. As an example, in the typical case an HTTP protocol parser feeds content into an HTML content parser, whose results are then fed to a combined HTML and CSS renderer. The presentation can be switched to, for example, plain-text only (for viewing the original source). In this way, a markdown document or URL can be parsed and rendered as pure markdown, or it can be parsed and rendered as a finalized HTML document. Likewise, the same HTML document can be parsed and rendered the same regardless of how it is acquired, whether by the HTTP, Gopher, or Gemini protocols, or even locally from disk. CSS styling can be applied to typically non-CSS documents (Gopher text, IRC chat messages, and so on). Git commits sent by email can be viewed directly as git commits/diffs etc. over IMAP rather than having to first be run through git. It's all up to what parsers/renderers are available and how the user has configured them for the given stream.

Additionally, generic stream parsers and renderers are implemented in the core, but stream-specific parsers, renderers, etc. are in general implemented as Lua scripts. Newer protocols or data formats, as well as updates to existing ones, can be handled by creating or modifying script files without requiring recompilation or reinstallation. Even when a parser, renderer, etc. is implemented directly in C (or some other compiled language) for performance reasons, users will be able to override such items with custom functionality (e.g., via a user script).

Perhaps most importantly, the parsing and rendering are not static. Users will be able to adjust and modify these on the fly at runtime as they see fit. Bitseme intends to change the very concept of a browser. Users can be as passive and similar to traditional browsing as they like, or they can take a more active role and manipulate the text streams. Userscripts for web browsers allow for manipulation of the HTML content, but not typically the HTTP protocol, or the rendering of the final content. Additionally, there are typically no similar manipulations for non-web text streams such as emails, etc. With bitseme these become possible.

Note: while bitseme has the capability of displaying graphics such as PNG images (if built with an appropriate backend), whether it actually does so at runtime depends on how it is configured by the user.

Features and Goals

• fast and responsive
  • multi-threaded
• low resource requirements
  • low memory footprint
  • minimal dependencies
    • see BUILDING.md for details
  • works on older systems
  • works over ssh directly (no proxying needed)
  • no need for fast or low-latency connections
  • no need for VNC
  • no need for a graphical environment
  • no need for a (GP)GPU
  • warning: downloading large files still requires sufficient bandwidth or time as well as storage space
• protocol agnostic
• content (encoding, markup, mimetype, etc.) agnostic
• presentation (i.e. layout and rendering style) agnostic
• extended colors and resolutions
  • avoids arbitrary restrictions or assumptions imposed by the program
    • other TUI browsers typically limited to 16 colors regardless of terminal
    • other TUI browsers typically limited to HTTP/HTML
  • allows for different rendering backends
    • current default: notcurses
  • only restricted by your terminal environment and the rendering backend
• automation
  • every aspect of bitseme is intended to be scriptable and controllable
  • see the DESIGN document for details
• code quality, safety, stability, and maintainability are explicit goals
  • see the DESIGN document for details
• readability and code safety are emphasized over brevity and optimization
  • see the DESIGN document for details

Anti-features and Non-goals

• a text editor
  • bitseme is editor agnostic
  • editor set in the EDITOR environment variable will be used
  • default is vi if the EDITOR environment variable is unset
• a state-of-the-art (media) web browser
  • the term "web browser" has come to encompass a great deal more than it used to
  • modern web browsers are akin to mini-OSes that can run applications (SPAs or Single-Page Apps, Java applets, etc.) inside of them, typically provided from a cloud instance
  • bitseme does not aspire to match what major browsers provide
  • instead, bitseme aims to provide what other browsers do not
    • more akin to a browser framework than a typical web browser
  • you are not limited from enabling bitseme of competing with other browsers
    • bitseme can render results from RESTful apps since these return (marked-up) text anyway
    • bitseme can be made to process and execute other apps
      • this is functionality that you as the user must provide and enable
• flashy graphics
  • bitseme is first and foremost a TUI and CLI program
  • if you desire flashy graphics, you are better suited to a full GUI browser instead
  • however, bitseme is capable of much flashier graphics than traditional TUI browsers.
    • depending on the graphics backend used (currently notcurses by default)

Licenses

Source files in this repository make use of SPDX headers to indicate their respective licenses. Any file that lacks such a header is licensed under the MIT license unless specified otherwise.

Copies of the applicable licenses are included in the LICENSES directory.