panglesd / diffcessible Goto Github PK
View Code? Open in Web Editor NEWLicense: MIT License
License: MIT License
Currently, we have a region at the top which displays the current operation.
However, this region is using the "diff" format. For instance, Creation of files are displayed like this:
--- a/dev/null
+++ b/path/to/new/file
It would be better to have a single, more explicit, line:
Creation of `path/to/new/file`
and similarly for other operations: rename
, deletion
, ...
This requires to replace the string_of_operation
function in interactive_viewer.ml
into a function that takes a value of type Patch.operation
and creates the relevant string from the value.
Add a panel that contains the list of keybindings with an explanation on what they do.
The panel would occupy on the whole screen, and its visibility would be toggled using a key (such as h
).
Create a README
The top bar currently displays the current operation shown.
It would be nice to also show the number of added and removed lines. This would have to be computed from the list of hunks.
Currently, it's only possible to scroll the visible part of the hunk via the mouse. This isn't a very accessible interface.
The goal of this task is to add the following key-bindings:
up
: Scrolls toward the top.down
: Scrolls toward the bottom.Scrolling is implemented by Nottui_widgets. We are currently using W.scrollbox
but we'd need to switch to W.vscroll_area
to have the keybindings above.
W.scrollbox
is a nottui widget that implements scrolling using the mouse. The "scrolling state" is hidden in the widget and we cannot add any shortcut to modify it. So, we cannot use this widget for our purpose.
W.vscroll_area
is a widget that implements (vertical) scrolling using the keyboard.
So, solving this task requires to switch to W.vscroll_area
. This function takes as input a scroll_state
and a function to modify the scroll state, that need to be create. It will be handy to be able to modify the scroll state from the outside of the function to add new keybindings.
Requires #14 to be done first.
Keyboard arrows are common to scroll, but so are j
and k
on TUIs. The goal of this task is to add the following bindings:
j
to scroll down,k
to scroll up.Keybindings can be either added in interactive_viewer.ml
alongside the other key bindings, or in the keybindings defined in the vscroll_area
function, in nottui_widgets.ml
Showing line numbers in a diff file is tricky as each line can have a different number before and after the patch is applied.
See for example, this diff from the example.diff
file:
diff --git a/bin/main.ml b/bin/main.ml
index e03c4a4..cb71f31 100644
--- a/bin/main.ml
+++ b/bin/main.ml
@@ -1,7 +1,9 @@
open Diffcessible
let main () =
- Interactive_viewer.start ()
+ let s = In_channel.input_all In_channel.stdin in
+ let patch = Patch.to_diffs s in
+ Interactive_viewer.start patch
open Cmdliner
The line numbers are start at 1
in both files, as indicated by the @@
line, but then diverges due to there being more added lines than removed lines.
The line numbers are as follow:
1 1 open Diffcessible
2 2
3 3 let main () =
4 - Interactive_viewer.start ()
4 + let s = In_channel.input_all In_channel.stdin in
5 + let patch = Patch.to_diffs s in
6 + Interactive_viewer.start patch
5 7
6 8 open Cmdliner
7 9
The OCaml community has the awesome ocaml-ci but for some reason we cannot enable it on this project until next week.
In the meantime, it would be useful to have a CI that does the following:
opam install --deps-only -t -y .
dune runtest
.dune build @fmt
.This is a medium issue.
Side-by-side diffs are added in #32
As new columns are added, it is natural to have extra columns for line numbers. Line numbers should be toggleable with a keybinding.
The file diff.example
is nice for easily and quickly trying out the program but is not enough for testing it.
We need a new diff file that contains:
Ideally, this file would be generated by first crafting two directories with slightly different files in them and running on them git diff --no-index
.
Even if they are not visible by everyone, colors help to read a diff.
It would be nice to add green and red background colors to the added and removed lines, in the output.
This issue is point of introduction to the project for Outreachy applicants.
First of all: welcome! We are happy to have you interested in the project.
In this issue, we gather many information that is relevant before contributing: more explanation on the project, but also resources worth reading, some instructions to set up the project, and a list of issues with some hint on the difficulty.
So, make sure to read this issue till the end! And do not hesitate to reply on it to ask any question that is related to the project! (For questions that are non-specific to the project, such as issues in setting up OCaml, please prefer other channel, such as the OCaml discord server).
Looking at the difference between two files is one of the most common activity in open source work.
It happens when reviewing a pull request, inspecting a commit and in many other situation.
The differences are usually displayed following a specific format, added lines being prefixed with a +
, removed ones by a -
and common one without prefix. Such format is called a "diff". Here is a simple one:
common words
- removed line
+ added line
However, in complex situation, reading such diff is not always easy. Many tools have been to made to improve the situation and make the diff reviewing easier: as shown above, the use of colours to distinguish between added and removed lines (traditionally green and red), use of a bold face to get the attention on the modified part of the line at the word level, the display of the two files side-by-side, ...
However, most of the improvements mentioned above:
The goal of this project is to develop a visualization tool on top of Git diff. The visualization tool is a terminal UI, and the main task of the internship is to make it highly accessible to screen readers.
This repository contains a minimal TUI to visualize diffs, as a starting point for the internship.
It uses several libraries:
patch
library to parse and print diffs,notty
library to "declare" terminal layout,lwd
library to make the UI reactive,nottui
library to bind lwd
and notty
,cmdliner
library to generate a command line.It is built using the dune
build system.
The project is still quite small. The bin/
directory contains the code for the command line, relying mostly on the cmdliner
library.
The lib/
directory contains the code for the UI, using lwd
and nottui
.
The vendor/
directory contains the vendored libraries: dependencies that needed to be slightly modified, and as such were included in the source. Unless for specific reasons, you won't need to modify the code in this directory. It can be useful to read though.
The rest of the files are configuration or documentation files (dune
files, README.md
, LICENSE
, ...).
Although the number of lines of code in this project is fairly small, it is very dense and can be quite hard to understand at first. But with time, work and experience it will become clear! So don't despair if at first, it seems obscure.
The first requirements to understand the code is to have the basics of OCaml: its syntax, but also the functional and declarative idioms it uses. The ocaml.org website provides some tutorials and guides, and there is also the book Real World OCaml which is available online.
Then, it is important to have a good idea on how the libraries used in this project work. Cmdliner has some documentation, that should be understood for any task that requires modifying the command line.
The Text User Interface is made using a concept called "Functional Reactive Programming". There is some explanation on that in the Lwd homepage. Basically, the UI layout is built from basic mutable variables, created with Lwd.var
. Similarly to the React framework, any change in the value of a basic variable will trigger a recomputation of the UI, which will be updated where needed.
First, you need to have OCaml up and running on your local machine. See the tutorial Installing OCaml.
Then, you need to clone this repository. Once you have that, go to the directory and install the dependencies with the following command:
$ opam install . --deps-only --with-test
Once the dependencies have been installed, try to build the project.
$ dune build
If dune
is still complaining about missing dependencies, maybe your environment is not in sync with opam
. In this case, on Linux and Mac eval $(opam env)
should fix it.
You can now run the binary created by the project:
$ dune exec diffcessible diff.example
$ # Or to see the man page of the tool:
$ dune exec -- diffcessible --help
Once you get a reasonable understanding of the code and have the project set up, you can consider contribute to the project. In order to do so, you have at the end of this section a list of good first issues.
As to avoid duplicated work, when you decide to work on an issue, you need to be assigned on it: this way, you can work on it without the pressure to finish before someone else opens a PR fixing the issue! However, in order to be assigned an issue, you need to be able to build the project first.
To be assigned an issue, comment on the issue thread with a screenshot of your computer with the --help
page, and ask to be assigned to the issue! When you are assigned an issue, we can provide more guidance on it if needed.
Good first issues:
Medium issues:
Please do ask for help if you are blocked on something!
There are two different kind of help that you might require: general help with OCaml, the tooling ; and help specific to this project.
To get general help on OCaml, the discord server might be the best option. It contains a "#outreachy" channel as well as a #beginner channel. The OCaml discuss is also a place where you can get help, it looks more like a forum compared to discord.
We want to stress that during the contribution period, AIs should be used with a lot of care. While they are a great tool both to learn and work, they can be very inadequate without mentor or critical sense, moreover they don't know OCaml very well. As mentors, we don't want to review code copy-pasted from an AI.
We are glad to have you here!
Hunks are currently stored in a list and accessed using an index. This operation have to iterate the list from the beginning to reach the desired hunk. Which is slow when looking at the end of a very large diff.
More efficient datastructures for this are: Array or Zipper.
It would be nice to display the number of hunks for the current operation, in the top status bar.
For instance:
--- a/path/to/file
+++ b/path/to/file
could become:
--- a/path/to/file
+++ b/path/to/file
7 hunks
See the example on previous repos
It would be useful to have a status bar showing contextual information, for example:
Vertical scrolling was added in #36, but long lines overflows and the content at the end is not visible.
This intermediate issue is about adding the ability to scroll horizontally.
When assigned this issue, do not hesitate to ask for more information, or help if you are blocked!
Lines in the diff can be longer than the screen and we need a way to scroll in the horizontal direction.
There is currently a vertical scroll box but not an horizontal one.
The UI is implemented using the Nottui library in interactive_viewer.ml.
Unfortunately, horizontal scrolling is not provided by the library and must be built from more primitive functions. As a reference, vertical scroll is implemented here: https://github.com/let-def/lwd/blob/master/lib/nottui/nottui_widgets.ml#L153
Currently, the executable read a file from a hardcoded path: "diff.example"
.
We need to be able to pass the file on the command line. This would be a required argument to the command line.
I am currently writing my application for this project via the Outreachy portal, and one of the prompts asks us to work with you to provide a timeline of the work we plan to accomplish on the project and what tasks we will finish at each step. May I inquire how to best answer this question and which projects you feel are great to include for this?
Thank you very much.
Best regards,
yokurang
The n
and p
shortcuts currently increment and decrement an integer. This integer is used as the index of the hunk to show on the screen.
This is a bad user experience as the integer can be incremented above the number of hunks, which has no visible effect except that the next n
will also have no visible effect.
The p
shortcuts should not set a value equal or above the number of hunks.
The n
shortcuts should not set a negative value.
Pressing n
(next) and p
(previous) navigates between operations: creation of a file, removal of file, edition, renaming, ...
Each operation contains several hunks of changes, that are displayed one after the other.
It would be nice to be able to only see one hunk, and navigate through them using f
(forward) and b
(backward).
The top status bar should ideally display the number of the visible hunk, as well as the total number of hunks.
#36 has added the ability to scroll.
It would be nice to have a keybinding to scroll back to the top of the displayed operation.
Feel free to ask for help or clarification when working on this issue!
This issue is a good first issue, and is reserved for first-time contributors!
#30 added a summary of the number of lines added and removed. It would be nice to display these numbers in red and green to improve readability.
A new entry point in the Interactive_viewer
library should be added, which allows to:
This can then be wrapped in a binary and called from a cram test.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.