README.md 6.36 KB
Newer Older
Camil Staps's avatar
Camil Staps committed
1
# Cloogle
Mart Lubbers's avatar
Mart Lubbers committed
2

Camil Staps's avatar
Camil Staps committed
3 4
A Clean hoogle clone: search for functions, types, and classes from the Clean
standard libraries.
5

Camil Staps's avatar
Camil Staps committed
6
Use any of the available frontends:
Mart Lubbers's avatar
Mart Lubbers committed
7

8
- Web app at [cloogle.org](https://cloogle.org/).
Camil Staps's avatar
Camil Staps committed
9 10
- The `!cloogle` bang on DuckDuckGo.
- [@CloogleBot](https://telegram.me/CloogleBot) on Telegram (see
Camil Staps's avatar
Camil Staps committed
11
	[CloogleBot](https://github.com/clean-cloogle/CloogleBot)).
Camil Staps's avatar
Camil Staps committed
12 13
- [cloogle-cli](https://github.com/clean-cloogle/cloogle-cli), a command line
	interface to the api.
14 15
- The `:Cloogle` command in
	[camilstaps/vim-clean](https://github.com/camilstaps/vim-clean).
Camil Staps's avatar
Camil Staps committed
16
- An email to `query@cloogle.org` with the query in the subject (see
Camil Staps's avatar
Camil Staps committed
17 18
	[cloogle-mail](https://github.com/clean-cloogle/cloogle-mail) for the
	implementation).
19

Mart Lubbers's avatar
Mart Lubbers committed
20 21 22
For support and/or contact please join us at the `#cloogle` irc channel on
[freenode](https://freenode.net)

23 24
---

Camil Staps's avatar
Camil Staps committed
25
### Readme contents
26

Camil Staps's avatar
Camil Staps committed
27 28
- [HTTP API Specification](#http-api-specification)
- [TCP API Specification](#tcp-api-specification)
Camil Staps's avatar
Camil Staps committed
29
- [Library browser](#library-browser)
30
- [Statistics](#statistics)
Camil Staps's avatar
Camil Staps committed
31
- [Setup](#setup)
32
- [Authors](#authors)
33
- [Copyright & License](#copyright--license)
34 35

---
Mart Lubbers's avatar
Mart Lubbers committed
36

Camil Staps's avatar
Camil Staps committed
37
## HTTP API specification
Mart Lubbers's avatar
Mart Lubbers committed
38
`api.php` should be called with a `GET` request where the `str` variable
Camil Staps's avatar
Camil Staps committed
39 40 41 42
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.).

Camil Staps's avatar
Camil Staps committed
43
The API will return a JSON formatted data structure containing the following
Camil Staps's avatar
Camil Staps committed
44
fields:
Mart Lubbers's avatar
Mart Lubbers committed
45

Mart Lubbers's avatar
Mart Lubbers committed
46
- `return`
Mart Lubbers's avatar
Mart Lubbers committed
47

Camil Staps's avatar
Camil Staps committed
48 49 50
	Return code:

	* `0`: success
Mart Lubbers's avatar
Mart Lubbers committed
51
	* `1`: cache hit, thus success
Camil Staps's avatar
Camil Staps committed
52 53
	* `127`: no results
	* `128`: ununderstandable input (usually shouldn't happen)
Camil Staps's avatar
Camil Staps committed
54 55
	* `129`: invalid name field
	* `130`: couldn't parse unify field as a type
Camil Staps's avatar
Camil Staps committed
56 57 58
	* `150`: the Clean backend could not be reached
	* `151`: invalid request type (should use GET)
	* `152`: no input (GET variable `str` should be set to the search string)
Camil Staps's avatar
Camil Staps committed
59
	* `153`: the Clean backend timed out
60
	* `154`: you have sent too many requests; try again later (DoS protection)
Camil Staps's avatar
Camil Staps committed
61

Mart Lubbers's avatar
Mart Lubbers committed
62
- `msg`
Mart Lubbers's avatar
Mart Lubbers committed
63 64

	A human friendly message representing the return code.
Camil Staps's avatar
Camil Staps committed
65

Mart Lubbers's avatar
Mart Lubbers committed
66
- `data`
Mart Lubbers's avatar
Mart Lubbers committed
67

68
	An array of search results. A result is an array of three elements. The first
Camil Staps's avatar
Camil Staps committed
69
	determines the kind of result. It may be `FunctionResult`, `TypeResult`,
Camil Staps's avatar
Camil Staps committed
70 71
	`ClassResult`, `MacroResult` or `ModuleResult`. The second contains general
	data, in particular the following fields:
Camil Staps's avatar
Camil Staps committed
72 73 74

	* `library`
	* `modul`: the module the result was found in (not a typo)
Camil Staps's avatar
Camil Staps committed
75 76
	* `filename`: the filename of the definition module
	* `dcl_line`: the line where the definition is found
Camil Staps's avatar
Camil Staps committed
77 78 79
	* `distance`: the distance measure we use to sort the results (lower is
		better)

80
	The third element of the array contains data specific to the kind of result.
81 82 83
	It is easiest to look in
	[`Cloogle.dcl`](https://github.com/clean-cloogle/libcloogle/blob/master/Cloogle.dcl)
	at the types
Camil Staps's avatar
Camil Staps committed
84 85 86
	`FunctionResultExtras`, `TypeResultExtras`, `ClassResultExtras`,
	`MacroResultExtras` and `ModuleResultExtras` to get an idea of the fields
	that may be returned.
87

Camil Staps's avatar
Camil Staps committed
88 89 90 91
- `more_available`

	If there are more results that can be found using pagination, this will be
	the number of results that have a higher distance than the last result sent.
Camil Staps's avatar
Camil Staps committed
92
	If there are no more results, this field *may* be zero or may not be present.
Camil Staps's avatar
Camil Staps committed
93

94 95 96
- `suggestions`

	If there are similar searches that may return more results, this will be an
97 98
	array of two-tuples with the alternative search (which has the same fields as
	a request) and the number of results.
99

Camil Staps's avatar
Camil Staps committed
100
## TCP API Specification
Camil Staps's avatar
Camil Staps committed
101
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
102 103 104 105 106
JSON request with at least one of the following fields:

* `unify`, the type to search for as a string.
* `name`, the name of the function to search for.
* `className`, the name of the class to search for.
Camil Staps's avatar
Camil Staps committed
107
* `typeName`, the name of the type to search for.
Camil Staps's avatar
Camil Staps committed
108 109
* `libraries`, a list of names of libraries to search in.
* `include_builtins`, a boolean, whether language builtins should be searched or not.
110
* `include_core`, a boolean, whether library cores should be searched or not.
111 112
* `modules`, a list of names of modules to search in.
* `page`: 0 for the first *n* results, 1 for the next *n*, etc.
Camil Staps's avatar
Camil Staps committed
113

114
All fields are optional. If `className` is present, `unify` and `name` will be
Camil Staps's avatar
Camil Staps committed
115 116
ignored. If `typeName` is present (and `className` is not), `unify` and `name`
will be ignored.
Camil Staps's avatar
Camil Staps committed
117 118 119 120 121

The Clean backend will return a JSON string, similar to the output of the PHP
script described above. The error codes above 150 are specific to the script
and cannot be returned by the Clean backend.

Camil Staps's avatar
Camil Staps committed
122 123 124 125 126
## 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
127 128 129 130 131
## Statistics
A websocket server on port 31216 provides you with the realtime log.

On [cloogle.org/stats/live.html](https://cloogle.org/stats/live.html), a
realtime usage chart is shown.
Camil Staps's avatar
Camil Staps committed
132

Camil Staps's avatar
Camil Staps committed
133 134 135
For longterm statistics you can see
[cloogle.org/stats/longterm.html](https://cloogle.org/stats/longterm.html).

Camil Staps's avatar
Camil Staps committed
136 137 138
## Setup
After installing
[docker-compose](https://www.docker.com/products/docker-compose) run the
139
following commands:
Camil Staps's avatar
Camil Staps committed
140 141

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

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

	ServerAdmin webmaster@cloogle.org

	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/cloogle.org.log combined

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

Camil Staps's avatar
Camil Staps committed
183
## Authors
Camil Staps's avatar
Camil Staps committed
184 185 186 187 188 189 190
Maintainers:

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

Contributors:

191
- [ErinvanderVeen](https://github.com/ErinvanderVeen) (logo and UI design)
Camil Staps's avatar
Camil Staps committed
192
- [KDercksen](https://github.com/KDercksen) (searching on module; help text)
Camil Staps's avatar
Camil Staps committed
193

194 195 196
## Copyright &amp; License
Copyright &copy; Mart Lubbers and Camil Staps.
Licensed under MIT; See the `LICENSE` file.