You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.adoc
+42-29Lines changed: 42 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,41 +1,41 @@
1
-
= R7RS index
1
+
= Scheme index
2
2
:toc: left
3
3
4
-
R7RS index is a tool for indexing and searching through procedures and syntax from R7RS-small and R7RS-large libraries.
5
-
R7RS index can be used in 3 ways - as a site (https://r7rsindex.com), through REST API, or through stdio API
4
+
Scheme index is a tool for indexing and searching through procedures and syntax from R7RS-small, R7RS-large, select SRFI libraries.
5
+
The index may be used through a site (https://index.scheme.org), through REST API, or through stdio API.
6
6
7
7
== Userguide for site visitors
8
8
9
-
R7RS index search consists of control pane on the left, and result list in the center.
9
+
Scheme index search consists of control pane on the left, and result list in the center.
10
10
11
11
=== Control pane
12
12
13
13
In the control pane, optionally select values from the filter list, optionally enter search query in the text field, and press either enter or button with magnifying glass to display the results. If you have javascript enabled, typing in the search query field should give you auto suggestions for identifier names, although those suggestions are not filtered by current selection. If you have javascript enabled and have checked apropriate option in settings, you can use control + f to quickly focus to the query text field.
14
14
15
15
=== Result list
16
16
17
-
Each result item can be either a procedure, a macro, or a value. At the top it shows a library it is exported from. Note, that some identifiers are exported from multiple libraries. The library name can be pressed, which will result in starting new search using said library as a filter. On the right side top, associated list of tags with the result is shown. Like with library, tags are also clickable, and start a search using the clicked tag as a filter.
17
+
Each result item is one of procedure, a macro, or a value. At the top it shows a library it is exported from. Note, that some identifiers are exported from multiple libraries. The library name can be clicked, which will result in starting new search using said library as a filter. On the right side top, associated list of tags with the result is shown. Like with library, tags are also clickable, and start a search using the clicked tag as a filter.
18
18
19
-
Procedure, procedure-like macros and value names are rendered in *red*. Procedures are distinguished by being surrounded with parenthesis, as if being called. Following the name until the "=>" sign are parameters. If parameter is just a name, it means it has an unspecified type. Otherwise, parameter may be a list of type and name. Types are represented as predicate procedures. After the "=>" sign is the return type. The return can be one of:
19
+
Procedures and value names are rendered in *red*. Procedures are distinguished by being surrounded with parenthesis, as if being called. Following the name until the "=>" sign are parameters. If parameter is just a name, it means it has an unspecified type. Otherwise, parameter may be a list of type and name. Types are usually represented as predicate procedures (sometimes a type may be opaque or logical, and without a disjoint predicate function to distinguish it). It can also be a logical "or" of multiple types, separated by `/`. Due to its pervasiveness as a `NULL`, `#f` literal is also used as a type sometimes, usually as a part of the "or".
20
20
21
-
* predicate procedure name (just like parameter type);
21
+
After the "=>" sign is the return type. The return type is same as parameter type, and additionally may contain:
22
22
23
23
* a "*" symbol (meaning it returns a value of unknown type);
24
24
25
25
* a word "undefined" (meaning it returns a value which shouldn't be used in portable code);
26
26
27
27
* a list with "values" word in car position (meaning it has a multivalue return);
28
28
29
-
* a list with "or" word in car position (meaning the return type is a union between given types).
30
-
31
29
Types expressed as predicates in *blue* are links. Pressing on a type in parameter position will search using that type as *return value* filter; pressing on a type in return value position will search using that type as *parameter* filter.
32
30
33
-
Scheme is a functional language and thus it'd be useful to specify taken / returned procedure values. Therefore, if one of parameters is *procedure?*, it's signature is defined below the main procedure's signature, using parameter's name in car position. Likewise same is done if return value is a procedure; but in that case word "return" is used as a name.
31
+
If one of parameters is *procedure?*, it's signature is defined below the main procedure's signature, using parameter's name in car position. Likewise same is done if return value is a procedure; but in that case word "return" is used as a name.
34
32
35
33
Procedures can have more than one entry, even from same library. This occurs, if the procedures is has optional parameters and therefore can be called in multiple ways; or if the result type can be determined more precisely under more specific input parameters.
36
34
37
35
Macros are rendered in *green*. If macro is complex, some parts of it are grouped, and the syntax of those groups shown below the syntax of whole macro. Macro literals are also rendered in green. To make parenthesis more obvious, auxiliary parenthesis coloring is used, however this coloring doesn't signify any information.
38
36
37
+
Macros may also contain typing definition, signifying expected type during macro expansion or runtime. Unlike with procedures though, such definitions are shown in separate block as to not confuse which parenthesis are part of macro syntax, and which are used for type grouping.
38
+
39
39
=== Tags
40
40
41
41
Result items might have one or more of following tags
@@ -62,51 +62,64 @@ Selecting multiple return types will return results that match *all* of the give
62
62
The text query is parsed by edismax parser, and is used to filter by name and parameter / subsyntax names. This means it supports and interprets common searching syntax, such as using "-" in front of the word to exclude results containing said word. This has its disadvantages; eg. if you tried to search for coercion functions and typed "->string" (without quotes) into the search input field, you wouldn't find anything interesting, because the leading minus was interpreted specially. Instead, you'd have to search using "exact phrase", by putting double quotes around the search.
63
63
64
64
65
-
== Building and running
65
+
== Obtaining and running index locally
66
+
67
+
=== Download
66
68
67
-
=== Natively
69
+
Prebuilt versions are available at https://github.com/arvyy/r7rs-index-site/releases
68
70
69
-
You can build R7RS index by running `ant` from the root of the source directory. Note that the build process required following executables to be on path
71
+
Docker image (corresponding to latest deployed version) may be pulled from `arvyy/scheme-index:master`.
The built image has same structure as a native build, under path `/app` inside the image.
108
+
109
+
=== Running with docker
110
+
111
+
To run with docker, execute
98
112
99
113
```
100
-
docker run -p 8080:8080 --init r7rs-index
114
+
docker run -p 8080:8080 --init scheme-index
101
115
```
102
116
103
-
The built image has same structure as a native build inside the `/app` path.
104
-
105
-
Alternatively, you can pull latest version deployted to the web from docker hub `arvyy/r7rs-index:master`.
117
+
The application resides in `/app` location. Consult rest of the documentation for details, but in particular you might want to mount a volume
118
+
to `/app/logs` to catch log files, or a volume file to `/app/config/configuration.scm` to overwrite index config.
106
119
107
120
=== Running for development
108
121
109
-
First, install dependencies under kawa-web-collection submodule
122
+
First, install dependencies under kawa-web-collection submodule (make sure the git submodule is initialized / updated)
110
123
111
124
```
112
125
cd kawa-web-collection
@@ -258,11 +271,11 @@ Second argument is parameter type definition, as described under functions. This
258
271
259
272
=== Logging
260
273
261
-
R7RS index uses logback for logging. By default (as defined in `src/main/resources/logback.xml`) it only does rolling file logging into `./logs` directory, and not into standard output.
274
+
Scheme index uses logback for logging. By default (as defined in `src/main/resources/logback.xml`) it only does rolling file logging into `./logs` directory, and not into standard output.
262
275
You can provide custom logging configuration by running
0 commit comments