README.md 6.23 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 32 33
- The web app at [cloogle.org][].
- The `!cloogle` bang on DuckDuckGo.
- The `:Cloogle` command or `<LocalLeader>c`in [vim-clean][].
- An email to `query@cloogle.org` with the query in the subject
  (see [cloogle-mail][]).
34 35 36 37 38 39 40
- The `!query` command of the IRC bot `clooglebot` which often resides on the
  `#cloogle` and `#cleanlang` channels on [freenode][] (see [clean-irc][]).

Old frontends:

- [@CloogleBot][] on Telegram (see [CloogleBot][]).
- [cloogle-cli][], a command line interface to the API.
Camil Staps's avatar
Camil Staps committed
41

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

Camil Staps's avatar
Camil Staps committed
47 48 49
**[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
50

Camil Staps's avatar
Camil Staps committed
51 52 53 54
**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
55

Camil Staps's avatar
Camil Staps committed
56 57 58
**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
59

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

Camil Staps's avatar
Camil Staps committed
63 64 65 66
**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).
67

Camil Staps's avatar
Camil Staps committed
68 69 70
## Interfacing with Cloogle
**TCP API**  
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
71
JSON request in the format described by the `Request` type in [Cloogle.API][],
Camil Staps's avatar
Camil Staps committed
72 73 74
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.
75

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

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

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

Camil Staps's avatar
Camil Staps committed
83 84 85 86 87 88 89
**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][].
90

Camil Staps's avatar
Camil Staps committed
91 92 93 94
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
95
by the TCP API. For the meaning of the return codes, see [Cloogle.API (icl)][].
Camil Staps's avatar
Camil Staps committed
96

Camil Staps's avatar
Camil Staps committed
97 98
## 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
99

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

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

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
140
## Authors, copyright &amp; license
Camil Staps's avatar
Camil Staps committed
141
Copyright &copy; 2016&ndash;present Mart Lubbers and Camil Staps.
Camil Staps's avatar
Camil Staps committed
142 143
Licensed under MIT; See the [LICENSE](/LICENSE) file.

144 145 146 147 148 149 150
Maintainers:

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

Contributors:

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

Camil Staps's avatar
Camil Staps committed
155
[cloogle.org]: https://cloogle.org
156 157 158 159 160
[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
[CloogleBot]: https://gitlab.science.ru.nl/cloogle/CloogleBot
Camil Staps's avatar
Camil Staps committed
161
[@CloogleBot]: https://telegram.me/CloogleBot
162
[cloogle-tags]: https://gitlab.science.ru.nl/cloogle/cloogle-tags
Camil Staps's avatar
Camil Staps committed
163
[cloogle-cli]: https://github.com/clean-cloogle/cloogle-cli
164
[cloogle-mail]: https://gitlab.science.ru.nl/cloogle/cloogle-mail
Camil Staps's avatar
Camil Staps committed
165
[clean-irc]: https://github.com/clean-cloogle/clean-irc
166
[cloogle.py]: https://gitlab.science.ru.nl/cloogle/cloogle-py
Camil Staps's avatar
Camil Staps committed
167 168

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

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