about summary refs log blame commit diff stats
path: root/cpp/070console
blob: 18faffb6202da8ac5d4f0c09ed1b47f43de1d2d9 (plain) (tree)

































                                                                              
//: Text-mode cursor primitives. Currently thin wrappers around ncurses calls.

:(before "End Includes")
#include<ncurses.h>

:(before "End Primitive Recipe Declarations")
CONSOLE_MODE,
:(before "End Primitive Recipe Numbers")
Recipe_number["console-mode"] = CONSOLE_MODE;
:(before "End Primitive Recipe Implementations")
case CONSOLE_MODE: {
  initscr();
  break;
}

:(before "End Primitive Recipe Declarations")
RETRO_MODE,
:(before "End Primitive Recipe Numbers")
Recipe_number["retro-mode"] = RETRO_MODE;
:(before "End Primitive Recipe Implementations")
case RETRO_MODE: {
  endwin();
  break;
}

:(before "End Primitive Recipe Declarations")
WAIT_FOR_KEY,
:(before "End Primitive Recipe Numbers")
Recipe_number["wait-for-key"] = WAIT_FOR_KEY;
:(before "End Primitive Recipe Implementations")
case WAIT_FOR_KEY: {
  getch();
  break;
}
ss='oid'>fe9ac5f7 ^
34b02351 ^
4f50b48a ^



78bfa540 ^
9ee1dd6e ^
4f50b48a ^

9a3cd69e ^
34b02351 ^
5268aada
5d6af7f5 ^
d8949a39 ^



3de0cccc ^
d8949a39 ^


c152009e ^
d8949a39 ^


c152009e ^
2014e1e0 ^
eda44e25 ^

f4d895c0 ^
9ee1dd6e ^
6de9ada2 ^
15815d72 ^
d8949a39 ^
ca86dcd3 ^
f77db0bd ^
06fbb9bc ^
f77db0bd ^





b8becdc0 ^
06fbb9bc ^
ca86dcd3 ^




618a88e0 ^
d8949a39 ^

618a88e0 ^





ca86dcd3 ^
8fd4662c ^

f646b6ca ^

e98d0ad1 ^


c152009e ^
e98d0ad1 ^



c152009e ^

e98d0ad1 ^
f646b6ca ^
0392e608 ^

053e0be9 ^

0392e608 ^
8fd4662c ^
06fbb9bc ^
f7cf612a ^

9a3cd69e ^
f7cf612a ^

a13ad5be ^
a8f05f18 ^




8fd4662c ^
a13ad5be ^

54623b97 ^
a13ad5be ^


8fd4662c ^
c152009e ^






















































94ea97fd ^



be9ba2f9 ^

c9104264 ^
be9ba2f9 ^
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
                                          
 



                                                                       
                
 

                                                                         
 
                                        

            
 





                                                                     

                                                                               
                                      
                                             

                                                                        
                          
                                                                         

                                                                          
                                                                         



                                                                              
                                                                    
 



                                                                
                                                                      
                                                      

   
           
 
                                   
 



                                                                   
                                                     


                                                                 
                                                                            


                                                        
                                                                            
         

                                                                                  
                                                                   
                               
               
 
                                   
 
                
 





                                                          
                                                 
 




                                                                            
                                                                            

                                                                       





                                                                             
 

      

                                                      


                                                                      
                                                                                



                                                                              

                                                                              
                                           
 

                                           

                                                                            
 
                                  
 

                                                                      
 

                                                                        
 




                                                                             
                                  

                                                                       
                                             


                                                                         
 






















































                                                                                



                                                                             

                                                                        
                                                                        
               
# Chawan - a web browser for your terminal

[Project page](https://sr.ht/~bptato/chawan)

![Screenshot of Chawan displaying its SourceHut page](doc/showcase.png)

## What is this?

A text-mode web browser. It displays websites in your terminal and allows
you to navigate on them.

It can also be used as a terminal pager.

## Compiling

Note: a POSIX-compliant operating system is required. (Windows is not
supported yet.)

1. Clone the Chawan repository:
   `git clone https://git.sr.ht/~bptato/chawan && cd chawan`
2. Install the Nim compiler: <https://nim-lang.org/install.html>
	* Please use 1.6.14 or newer, ideally 2.0.0. Older versions will
	  not work. (You can check your Nim compiler's version using `nim -v`.)
3. Install the following dependencies:
	* libcurl: <https://curl.se/libcurl/>
	* zlib: <https://zlib.net/>
	* pkg-config, pkgconf, or similar (must be found as "pkg-config"
	  in your `$PATH`)
	* If you are using a system where the default make program is not
          GNU make (e.g. BSD), install gmake and use that in the following
	  steps.
4. Download parts of Chawan found in other repositories: `make submodule`
5. Run `make`. (By default, this will build the whole project in release mode;
   for details, see [doc/build.md](doc/build.md).)
6. If you want manpages, run `make manpage`. (This requires pandoc to be
   installed.)
7. Finally, install using `make install` (e.g. `sudo make install`).

Then, try:

```bash
$ cha -V # open in visual mode for a list of default keybindings
$ cha example.org # open your favorite website directly from the shell
$ mancha cha # read the cha(1) man page using `mancha'
```

## Features

Currently implemented features are:

* multi-processing (several buffers can be loaded at once)
* multi-charset, double-width aware text display (but no bi-di yet)
* HTML5 support
* a CSS-capable layout engine
	* flow layout is supported (now with floats!)
	* table layout is supported, except for fixed tables
	* the box model is mostly implemented, except for borders
* forms
* incremental loading of various kinds of documents (plain text, HTML, etc.)
* JavaScript based navigation
* JavaScript support in documents
	* some basic DOM manipulation APIs are supported
        * off by default; use is discouraged until sandboxing is implemented
* cookies
* supports several protocols: HTTP(S), FTP, Gopher, Gemini, Finger, etc.
* can load user-defined protocols/file formats using [local CGI](doc/localcgi.md),
  [urimethodmap](doc/urimethodmap.md) and [mailcap](doc/mailcap.md)
* man page viewer (like w3mman)
* mouse support

...with a lot more [planned](todo).

## Documentation

* manpage: [doc/cha.1](doc/cha.1)
* configuration options: [doc/config.md](doc/config.md)
* mailcap: [doc/mailcap.md](doc/mailcap.md)
* mime.types: [doc/mime.types.md](doc/mime.types.md)
* urimethodmap: [doc/urimethodmap.md](doc/urimethodmap.md)
* local CGI: [doc/localcgi.md](doc/localcgi.md)
* protocols: [doc/protocols.md](doc/protocols.md)

## Neighbors

Many other text-based web browsers exist. Here's some recommendations if you
want to try more established ones:

* [w3m](https://github.com/tats/w3m) - A text-mode browser, extensible using
  local-cgi. Also has inline image display and very good table support.
  Inspired many features of Chawan.
* [elinks](https://github.com/rkd77/elinks) - Has CSS and JavaScript support,
  and incremental rendering (it's pretty fast.)
* [lynx](https://lynx.invisible-island.net/) - "THE text-based web browser."
* [edbrowse](http://edbrowse.org/) - This one looks more like `ed` than
  `less` or `vi`. Mainly designed for blind users.
* [browsh](https://www.brow.sh/) - Firefox in your terminal.

## FAQ

### Why does Chawan use strange/incorrect/ugly colors?

Chawan's display capabilities depend on what your terminal reports. In
particular:

* if it does not respond to querying XTGETTCAP, and the `$COLORTERM` environment
  variable is not set, then Chawan falls back to ANSI colors
* if it does not respond to querying the background color, then Chawan's color
  contrast correction will likely malfunction

You can fix this manually by adjusting the `display.default-background-color`,
`display.default-foreground-color`, and `display.color-mode` variables. See
[doc/config.md](doc/config.md) for details.

### Can I view Markdown files using Chawan?

Yes; Chawan now has a built-in markdown converter. If you don't like it, you
can always [replace it](doc/mailcap.md) with e.g. pandoc.

### Why write another web browser?

I've found other text-based web browsers insufficient for my needs, so
I thought it'd be a fun excercise to write one by myself, for myself.

Generally, I'm happy if Chawan works on websites I use frequently. If it
also works on other websites, that's a bonus.

### Where are the keybindings?

Please run `cha about:chawan` for a list of default keybindings. (By default,
this is equivalent to `cha -V`.)

### Where are the w3m keybindings?

At [bonus/w3m.toml](bonus/w3m.toml). Note that not every w3m feature is
implemented yet, so it's not 100% compatible.

I use vi for editing text, and I prefer my pager to function similarly to
my editor. Hence the default vi-like keybindings.

### Why does `$WEBSITE` look awful in Chawan?

Usually, this is because the website uses some CSS features that are not yet
implemented in Chawan. The most common offenders are flexbox, grid, and CSS
variables.

There are three ways of dealing with this:

1. The hacky solution: if the website's contents are mostly text, install
   [rdrview](https://github.com/eafer/rdrview). Then bind the following command
   to a key of your choice in the config (e.g. <space> r):<br>
   `' r' = "pager.externFilterSource('rdrview -H -u \"$CHA_URL\"')"`<br>
   This does not fix anything, but will significantly improve your reading
   experience anyway.
2. The slow solution: complain [here](https://todo.sr.ht/~bptato/chawan),
   and wait until the problem goes away.
3. If you're feeling adventurous: write a patch to fix the problem, and send it
   [here](https://lists.sr.ht/~bptato/chawan-devel).

### `$WEBSITE`'s interactive features don't work!

Some potential fixes:

* Usually logging in to websites requires cookies. Some websites also require
  cookie sharing accross domains. For security reasons, Chawan does not allow
  any of this by default, so you will have to fiddle with siteconf to fix
  it. (i.e. on all target hostnames, set `cookie` to true, `share-cookie-jar`
  to the main host, and `third-party-cookie` to all target hosts. See
  [doc/config.md#siteconf](doc/config.md#siteconf) for details.)
* Set the `referer-from` siteconf value to true; this will cause Chawan to send
  a `Referer` header when navigating to other URLs from the target URL.
* Enable JavaScript. If something broke, type M-c M-c to check the browser
  console, then follow step 3. of the previous answer.<br>
  Warning: remote JavaScript execution is inherently unsafe; more so in Chawan,
  which lacks proper sandboxing of buffer processes. Please only enable
  JavaScript on websites you trust.

### I'm interested in the technical details of Chawan.

Here's some:

* Written in Nim
* Uses QuickJS for JavaScript execution. (The QuickJS regex engine, libregexp,
  is also used for in-document searches.)
* Uses multi-processing provided by POSIX. (No threads.) Each buffer gets
  its own process; as a result, buffers can be duplicated by simply forking
  their process. File loading is done in yet another process. IPC happens
  through UNIX domain sockets.
* Layout, CSS cascading, HTML parsing, etc. are handled by built-in modules, not
  external libraries. (However, the HTML parser and the character coding library
  are available as separate libraries as well.)
* Uses termcap for basic terminal capability querying, and notcurses-style
  terminal queries for detecting "modern" features (like true color).

For further details, you will have to read the source code.

## License

Chawan is dedicated to the public domain. See the UNLICENSE file for details.

Chawan also includes and depends on several other libraries. For further
details, see [license.html](res/license.html) or check the about:license
page in Chawan.