README.md 6.21 KB
Newer Older
1
# cloogle.org
Mart Lubbers's avatar
Mart Lubbers committed
2

Camil Staps's avatar
Camil Staps committed
3
The [Clean][] language search engine. Cloogle lets you search for functions,
Camil Staps's avatar
Camil Staps committed
4 5 6 7 8
types, classes and modules from Clean libraries. It also has documentation for
language features, common compiler errors and ABC instructions. The web app is
available at [cloogle.org][].

Cloogle was inspired by [Hoogle][]. As of June 27, 2018, Cloogle indexes
Camil Staps's avatar
Camil Staps committed
9
100× less lines of code than Hoogle (25 thousand vs. 2.3 million). This
Camil Staps's avatar
Camil Staps committed
10 11
allows Cloogle to implement more advanced features, such as `using` queries to
find usages.
Mart Lubbers's avatar
Mart Lubbers committed
12

13 14
---

Camil Staps's avatar
Camil Staps committed
15
**Readme contents**
16

Camil Staps's avatar
Camil Staps committed
17 18 19
- [Frontends](#frontends)
- [Auxiliary tools](#auxiliary-tools)
- [Interfacing with Cloogle](#interfacing-with-cloogle)
Camil Staps's avatar
Camil Staps committed
20
- [Adding a library to the index](#adding-a-library-to-the-index)
Camil Staps's avatar
Camil Staps committed
21 22
- [Local setup](#local-setup)
- [Authors, copyright & license](#authors-copyright--license)
23 24

---
Mart Lubbers's avatar
Mart Lubbers committed
25

Camil Staps's avatar
Camil Staps committed
26 27
## Frontends
These frontends to Cloogle are currently known to us:
Mart Lubbers's avatar
Mart Lubbers committed
28

Camil Staps's avatar
Camil Staps committed
29 30 31
- The web app at [cloogle.org][].
- The `!cloogle` bang on DuckDuckGo.
- The `:Cloogle` command or `<LocalLeader>c`in [vim-clean][].
32 33 34

Old frontends:

35 36
- An email to `query@cloogle.org` with the query in the subject
  (see [cloogle-mail][]).
37
- The `!query` command of the IRC bot `clooglebot` (see [cloogle-irc][]).
38 39
- [@CloogleBot][] on Telegram (see [CloogleBot][]).
- [cloogle-cli][], a command line interface to the API.
Camil Staps's avatar
Camil Staps committed
40

Camil Staps's avatar
Camil Staps committed
41 42
## Auxiliary tools
Several tools used in Cloogle are available as separate libraries from
Camil Staps's avatar
Camil Staps committed
43 44
[gitlab.science.ru.nl/cloogle](https://gitlab.science.ru.nl/cloogle).
Additionally, these tools can be helpful:
Camil Staps's avatar
Camil Staps committed
45

Camil Staps's avatar
Camil Staps committed
46 47 48
**[Cloogle-tags][cloogle-tags]:**
This program lets you index local Clean code in *tagfiles* that can be used by
your text editor.
Mart Lubbers's avatar
Mart Lubbers committed
49

Camil Staps's avatar
Camil Staps committed
50 51 52 53
**Library browser:**
The frontend includes a library browser to browse through all known Clean
libraries. The browser can be accessed through
[cloogle.org/src](https://cloogle.org/src).
Camil Staps's avatar
Camil Staps committed
54

Camil Staps's avatar
Camil Staps committed
55 56 57
**Documentation browser:**
There is also an HTML version of the Clean Language Report, available at
[cloogle.org/doc](https://cloogle.org/doc).
Mart Lubbers's avatar
Mart Lubbers committed
58

Camil Staps's avatar
Camil Staps committed
59 60
**Logging:**
A websocket server on port 31216 provides the realtime [cloogle.org][] log.
Camil Staps's avatar
Camil Staps committed
61

Camil Staps's avatar
Camil Staps committed
62 63 64 65
**Statistics:**
On [cloogle.org/stats/live.html](https://cloogle.org/stats/live.html), a
realtime usage chart is shown. For longterm statistics you can see
[cloogle.org/stats/longterm.html](https://cloogle.org/stats/longterm.html).
Camil Staps's avatar
Camil Staps committed
66

Camil Staps's avatar
Camil Staps committed
67 68 69
## Interfacing with Cloogle
**TCP API**  
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
Camil Staps's avatar
Camil Staps committed
70
JSON request in the format described by the `Request` type in [Cloogle.API][],
Camil Staps's avatar
Camil Staps committed
71 72 73
followed by a newline character. The response is in the format described by the
`Response` type. The connection is kept alive for some time to allow further
requests.
74

Camil Staps's avatar
Camil Staps committed
75 76
To interface with Cloogle, it is recommended that you use the HTTP API rather
than the TCP API.
Camil Staps's avatar
Camil Staps committed
77

Camil Staps's avatar
Camil Staps committed
78
For a Clean interface to Cloogle, it is suggested that you use [libcloogle][].
Camil Staps's avatar
Camil Staps committed
79

Camil Staps's avatar
Camil Staps committed
80
For a Python interface to Cloogle, you can use [cloogle.py][].
81

Camil Staps's avatar
Camil Staps committed
82 83 84 85 86 87 88
**HTTP API**  
The HTTP API is a simple wrapper around the TCP API, with a more stable API.
`api.php` should be called with a `GET` request where the `str` parameter
contains the search string. You may also add `mod` (a comma-separated list of
modules to search in) and `page` (for pagination: 0 for the first *n* results,
1 for the next *n*, etc.). For the query syntax in the `str` parameter, see the
'How to use' guidelines on [cloogle.org][].
89

Camil Staps's avatar
Camil Staps committed
90 91 92 93
The API returns the same JSON as the TCP API, but may include additional
results when searched for Clean error messages (for example, `stack overflow`).
These error messages are indexed by the frontend rather than the backend.
Additionally, the HTTP API may give return codes above 150, which are not used
Camil Staps's avatar
Camil Staps committed
94
by the TCP API. For the meaning of the return codes, see [Cloogle.API (icl)][].
Camil Staps's avatar
Camil Staps committed
95

Camil Staps's avatar
Camil Staps committed
96 97
## Adding a library to the index
See [CONTRIBUTING.md](/CONTRIBUTING.md#3-i-just-want-to-add-library-x).
Camil Staps's avatar
Camil Staps committed
98

Camil Staps's avatar
Camil Staps committed
99 100
## Local setup
After installing [docker-compose][] run the following commands:
Camil Staps's avatar
Camil Staps committed
101 102

```bash
103
touch cloogle.log
104
sudo docker-compose up
Camil Staps's avatar
Camil Staps committed
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
```

Your Cloogle server now runs at port `31215` on your local machine.
The web frontend is available at port `80`, live statistics at port `31216`.

If you intend to run this on a server that has port 80 occupied already, you
can use nginx or apache2 as a proxy. Change `80:80` to `31280:80` in
`docker-compose.yml` and use the following nginx config:

```nginx
server {
	listen [::]:80;
	server_name cloogle.org;

	location / {
		proxy_pass http://127.0.0.1:31280;
		proxy_set_header Host $host;
		proxy_set_header X-Forwarded-For $remote_addr;
	}
}
```

Or the following apache2 virtualhost (be sure to enable `mod_proxy`).

```ApacheConf
<VirtualHost *:80>
	ServerName cloogle.org

	ProxyRequests off
	ProxyPass / http://localhost:31280/
	ProxyPassReverse / http://localhost:31280/
</VirtualHost>
```

Camil Staps's avatar
Camil Staps committed
139
## Authors, copyright &amp; license
Camil Staps's avatar
Camil Staps committed
140
Copyright &copy; 2016&ndash;present Mart Lubbers and Camil Staps.
Camil Staps's avatar
Camil Staps committed
141 142
Licensed under MIT; See the [LICENSE](/LICENSE) file.

Camil Staps's avatar
Camil Staps committed
143 144 145 146 147 148 149
Maintainers:

- [dopefishh](https://github.com/dopefishh)
- [Camil Staps](https://camilstaps.nl)

Contributors:

150
- [ErinvanderVeen](https://github.com/ErinvanderVeen) (logo and UI design)
Camil Staps's avatar
Camil Staps committed
151
- [KDercksen](https://github.com/KDercksen) (searching on module; help text)
Camil Staps's avatar
Camil Staps committed
152
- [SteffenMichels](https://github.com/SteffenMichels) (ABC documentation)
Camil Staps's avatar
Camil Staps committed
153

Camil Staps's avatar
Camil Staps committed
154
[cloogle.org]: https://cloogle.org
Camil Staps's avatar
Camil Staps committed
155 156 157 158
[Cloogle]: https://gitlab.science.ru.nl/cloogle/Cloogle
[libcloogle]: https://gitlab.science.ru.nl/cloogle/libcloogle
[Cloogle.API]: https://gitlab.science.ru.nl/cloogle/libcloogle/blob/master/Cloogle/API.dcl
[Cloogle.API (icl)]: https://gitlab.science.ru.nl/cloogle/libcloogle/blob/master/Cloogle/API.icl
159
[CloogleBot]: https://gitlab.science.ru.nl/cloogle/archived/CloogleBot
Camil Staps's avatar
Camil Staps committed
160
[@CloogleBot]: https://telegram.me/CloogleBot
161
[cloogle-tags]: https://gitlab.science.ru.nl/cloogle/periphery/cloogle-tags
Camil Staps's avatar
Camil Staps committed
162
[cloogle-cli]: https://gitlab.science.ru.nl/cloogle/archived/cloogle-cli
163
[cloogle-mail]: https://gitlab.science.ru.nl/cloogle/archived/cloogle-mail
164
[cloogle-irc]: https://gitlab.science.ru.nl/cloogle/archived/cloogle-irc
165
[cloogle.py]: https://gitlab.science.ru.nl/cloogle/periphery/cloogle-py
Camil Staps's avatar
Camil Staps committed
166 167

[Clean]: http://clean.cs.ru.nl
Camil Staps's avatar
Camil Staps committed
168
[vim-clean]: https://gitlab.science.ru.nl/cstaps/vim-clean
Camil Staps's avatar
Camil Staps committed
169 170 171

[docker-compose]: https://www.docker.com/products/docker-compose
[Hoogle]: https://github.com/ndmitchell/hoogle
Camil Staps's avatar
Camil Staps committed
172
[freenode]: https://freenode.net