qwandor / anes-rs Goto Github PK

View Code? Open in Web Editor NEW

15.0 0.0 2.0 113 KB

ANSI Escape Sequence provider & parser

Home Page: https://crates.io/crates/anes

License: Apache License 2.0

Rust 99.51% Shell 0.49%

terminal console ansi rust-lang

anes-rs's Introduction

ANSI Escape Sequences provider & parser

This README file is for the anes-rs repository. If you're looking for the user documentation, please, go to anes/README.md.

Repository organisation

anes-rs
 ├ README.md        - this README
 ├ anes             - `anes` crate
 │  ├ benches       - `anes` crate benchmarks
 │  ├ examples      - `anes` crate examples
 │  ├ src           - `anes` crate source code
 │  ├ tests         - `anes` crate tests
 │  └ README.md     - `anes` crate README for crates.io site
 ├ fuzzer            - fuzzing binary targets
 ├ interactive-test  - interactive test for the `anes` crate
 └ scripts           - various scripts to run bechmarks, fuzzer, ...

Benchmarks

You can run benchmarks with the scripts/bench.sh script. criterion output is available in the anes/target/criterion folder. If you'd like to modify the parser module (anes/src/parser) in any way, please, do:

run benchmarks,
modify the parser code,
run benchmarks again.

Do not commit any change which degrades the parser performance. TIA!

Fuzzer

You can start fuzzing with the scripts/fuzz.sh script. Feel free to stop fuzzing any time with the Ctrl C, AFL allows you to continue with the scripts/fuzz-continue.sh script.

Motivation

There're couple of terminal crates like:

All these crates do share two pieces of code:

ANSI escape sequences and
input event parsers.

I think that it's a waste of resources and asked Timon (the crossterm crate maintainer) what he thinks about a new crate as a building block for the crossterm and other crates. And here we are ...

License

The ANES crate is dual-licensed under Apache 2.0 and MIT terms.

Copyrights in the ANES project are retained by their contributors. No copyright assignment is required to contribute to the ANES project.

anes-rs's People

Contributors

Stargazers

Forkers

timonpost windoze

anes-rs's Issues

no_std support

I want to use anes for Arduino serial I/O, but cannot, because it requires std. Can we make a no_std version of anes, or it's better to fork it?

Should we add unknown sequences variants?

Version 0.1.6 provides:

pub enum Sequence {
    Key(KeyCode, KeyModifiers),
    Mouse(Mouse, KeyModifiers),
    CursorPosition(u16, u16),
}

Parser throws away every csi/esc sequence without known meaning (valid sequence, but we have no idea what it is). What's the problem. Any sequence, which isn't supported by anes is trashed and crate user doesn't even know it. Is this something we should expose? Should we add Sequence::UnknownEsc(char) & Sequence::UnknownCsi(Vec<u64>, usize, char)?

Need LICENSE file for many distros

While the License is documented on crates.io, many distros (e.g. Fedora) want an actual file as part of the package. Lawyers are very pedantic.

Should we move the parser engine to a separate crate?

Version 0.1.6 hides the State, Engine & Provide types. Basically the whole src/parser/engine.rs content.

Should we move it into separate anes-parser crate for example?
Like provide a crate with the parser only (no meaning, just input -> valid generic esc/csi sequence)?

Build fails on examples/parser.rs with rust-1.66.0

error[E0432]: unresolved import `anes::parser`
 --> examples/parser.rs:6:5
  |
6 |     parser::{KeyCode, Parser, Sequence},
  |     ^^^^^^ could not find `parser` in `anes`

For more information about this error, try `rustc --explain E0432`.
error: could not compile `anes` due to previous error

Add parser

We parse all the input as u8 slice in the crossterm crate. It means that we are just matching byte sequences, but we don't know if the CSI sequence is (in)valid and thus we don't know if we should stop, start new sequence, etc.

Implement a two step parser:

parse input as CSI, ESC, ... sequences without meaning
give CSI, ESC, ... sequences meaning

You can check #15 where this kind of parser is being developed. It's gated with the parser feature.

Emitting mouse sequences?

Understandably, emitting escape sequences to generate terminal mouse sequences is rather niche, but is it within the scope of this project? I'm thinking of using it as part of a terminal multiplexer for forwarding mouse events to pseudoterminals.