finish Lua API docs.

docs/usage-gui.md

@@ -51,7 +51,8 @@ The methods to work with the query data are likewise prefixed by `en_`.
 ### Example queries
 There are some example queries in [`example_query.lua`](../example_query.lua) in the repo root. 
 ### Available API
-The full API documentation for ENTRACE can be found in the [search module docs](../gui/src/search/lua_api.rs).
+The full API documentation for ENTRACE can be found in the [LUa API Docs](../entrace_query/api-docs/).
+Displaying the docs is also available in the GUI.
 Every function whose name starts with `en_` here implements a lua method for queries.
 
 ### Disabling parallelism

entrace_query/api-docs/en_as_string.md

@@ -1,2 +1,11 @@
-Return a reasonable string representation of the entry at id.
+Return a string representation of the entry at id.
 The format of this string should be considered unstable.
+
+## INPUT
+A span id.
+
+## OUTPUT
+A string.
+
+## EXAMPLE
+local s = en_as_string(id)

entrace_query/api-docs/en_attr_by_idx.md

@@ -0,0 +1,11 @@
+Get an attribute name and value by its index.
+
+## INPUT
+- A span id.
+- The attribute index (an integer, which starts counting from 0).
+
+## OUTPUT
+The attribute name (string) and its value.
+
+## EXAMPLE
+local name, value = en_attr_by_idx(id, 0)

entrace_query/api-docs/en_attr_by_name.md

@@ -0,0 +1,11 @@
+Get the value of an attribute by its name.
+
+## INPUT
+- A span id.
+- The attribute name (a string).
+
+## OUTPUT
+The attribute value, or nil.
+
+## EXAMPLE
+local value = en_attr_by_name(id, "my_attribute")

entrace_query/api-docs/en_attr_name.md

@@ -0,0 +1,11 @@
+Get an attribute name by its index.
+
+## INPUT
+- A span id.
+- The attribute index (an int, which starts from 0).
+
+## OUTPUT
+The attribute name (string).
+
+## EXAMPLE
+local name = en_attr_name(id, 0)

entrace_query/api-docs/en_attr_names.md

@@ -0,0 +1,13 @@
+Get a list of attribute names for an entry.
+
+## INPUT
+A span id.
+
+## OUTPUT
+list[string] of attribute names.
+
+## EXAMPLE
+local names = en_attr_names(id)
+for i, name in ipairs(names) do
+  en_log(name)
+end

entrace_query/api-docs/en_attr_value.md

@@ -0,0 +1,11 @@
+Get an attribute value of a span by its index.
+
+## INPUT
+- A span id.
+- The attribute index: an int. This starts counting from 0.
+
+## OUTPUT
+The attribute value.
+
+## EXAMPLE
+local value = en_attr_value(id, 0)

entrace_query/api-docs/en_attr_values.md

@@ -0,0 +1,13 @@
+Get a list of attribute values for an entry.
+
+## INPUT
+A span id.
+
+## OUTPUT
+list[object]: a list of attribute values.
+
+## EXAMPLE
+local values = en_attr_values(id)
+for i, value in ipairs(values) do
+  en_log(value)
+end

entrace_query/api-docs/en_attrs.md

@@ -0,0 +1,11 @@
+Get attributes of an entry as a table.
+
+## INPUT
+A span id.
+
+## OUTPUT
+A table which maps attribute names to attribute values.
+
+## EXAMPLE
+local attrs = en_attrs(id)
+local value = attrs.my_attribute

entrace_query/api-docs/en_child_cnt.md

@@ -0,0 +1,10 @@
+Get the number of children for an entry.
+
+## INPUT
+A span id.
+
+## OUTPUT
+The child count (an int).
+
+## EXAMPLE
+local count = en_child_cnt(id)

entrace_query/api-docs/en_children.md

@@ -0,0 +1,13 @@
+Get the children of an entry.
+
+## INPUT
+A span id.
+
+## OUTPUT
+The list of children (list[int]).
+
+## EXAMPLE
+local children = en_children(id)
+for i, child_id in ipairs(children) do
+  en_log(child_id)
+end

entrace_query/api-docs/en_contains_anywhere.md

@@ -0,0 +1,13 @@
+Check if the string representation of an entry contains a given substring.
+
+## INPUT
+- A span id.
+- The substring to search for.
+
+## OUTPUT
+Whether the substring appears in the entry.
+
+## EXAMPLE
+if en_contains_anywhere(id, "error") then
+  en_log("Found error in entry " .. id)
+end

entrace_query/api-docs/en_filter.md

@@ -1,8 +1,15 @@
- en_filter()
- input:
-   filter: table with
-     target: name of variable eg. "message" or "meta.filename"
-     relation: a relation, one of "EQ", "LT", "GT"
-     value: a constant to compare with
-   src: filterset
- outputs: { type = "filterset", root = 1, items = { src = 0, {type = "rel_dnf", src = 0, clauses = {{ target, relation, value}} }}},
+Apply a filter to a filterset to match only the spans matching a relation.
+
+## INPUT
+- A table describing the relation:
+  - target: name of variable, eg. "message" or "meta.filename"
+  - relation: a string, one of "EQ" | "LT" | "GT"
+  - value: a constant to compare with.
+- src: a filterset.
+
+## OUTPUT
+A filterset that matches only the spans which satisfy the relation.
+
+## EXAMPLE
+local fs = en_filterset_from_range(0, 100)
+local filtered = en_filter({target = "meta.level", relation = "EQ", value = 5}, fs)

entrace_query/api-docs/en_filterset_dnf.md

@@ -1,31 +1,19 @@
- en_filterset_dnf()
- input:
-   filters: a list of list of filter descriptions, which is interpreted as a DNF clause list.
-   (this example would be (a=1 AND c=0) OR (b=1)
-   {
-     {
-       { target = "a", relation = "EQ", value = "1", src = 0 },
-       { target = "c", relation = "EQ", value = "0", src = 0 },
-     }
-     {
-       { target = "b", relation = "EQ", value = "1", src = 0},
-     }
-   }
-   source: a filterset
- outputs: a filterset that matches an item if satisfies either of the AND clauses
- { type: "filterset",
-   root: 1,
-   items: {
-     { type = "prim_list", value = {1,2,3}},
-     { type = "rel_dnf", src = 0,
-       clauses = {
-         {
-           { target = "a", relation = "EQ", value = "1", src = 0 },
-           { target = "c", relation = "EQ", value = "0", src = 0 },
-         }
-         {
-           { target = "b", relation = "EQ", value = "1", src = 0},
-         }
-       }
-     }
- }
+Apply a filter in Disjunctive Normal Form (OR of ANDs) to a filterset.
+
+## INPUT
+- A clause list, where each clause is a list of filter descriptions accepted by en_filter.
+Such a filter description is a table that looks like:
+  - target: name of variable, eg. "message" or "meta.filename"
+  - relation: a string, one of "EQ" | "LT" | "GT"
+  - value: a constant to compare with.
+- A source filterset.
+
+## OUTPUT
+A new filterset matching spans which satisfy the DNF.
+
+## EXAMPLE
+local fs = en_filterset_from_range(0, 100)
+local level_5_or_message_error = en_filterset_dnf({
+  { {target="meta.level", relation="EQ", value=5} },
+  { {target="message", relation="EQ", value="error"} }
+}, fs)

entrace_query/api-docs/en_filterset_from_list.md

@@ -1,8 +1,10 @@
- en_filterset_from_list()
-  input: list of ids
-  outputs: a table with
-    type: "filterset"
-    root: 0
-    items: {
-      { type = "prim_list"; value = the list}
-    }
+Create a filterset from a list of span IDs.
+
+## INPUT
+A list (sequence table) of span IDs.
+
+## OUTPUT
+A filterset matching the provided spans.
+
+## EXAMPLE
+local fs = en_filterset_from_list({1, 5, 10})

entrace_query/api-docs/en_filterset_from_range.md

@@ -1,8 +1,11 @@
- en_filterset_from_range()
-  input: start, end
-  outputs: a table with
-    type: "filterset"
-    root: 0
-    items: {
-      { type = "prim_range"; start = start, end=end}
-    }
+Create a filterset from a range of span IDs.
+
+## INPUT
+- start index (int)
+- end index (int)
+
+## OUTPUT
+A filterset matching all spans in [start, end].
+
+## EXAMPLE
+local fs = en_filterset_from_range(0, 100)

entrace_query/api-docs/en_filterset_intersect.md

@@ -1,34 +1,12 @@
- en_filterset_intersect()
- input:
-   filters: a list of filtersets, e. g
-   {
-     { type: "filterset",
-       root: 1,
-       items: {
-         { type = "prim_list", value = {1,2,3}},
-         { type = "rel", target = "a", relation = "EQ", value = "1", src = 0 },
-       }
-     }
-     { type: "filterset",
-       root: 1,
-       items: {
-         {type: "prim_list", value = {1,2,3} },
-         {type: "rel", target = "b", relation = "EQ", value = "1", src = 0},
-       }
-     }
-   }
- outputs: a filterset that matches an item if it is in all input filtersets.
- This does NOT deduplicate any items, eg. for the given inputs, the result would be as follows.
- Note that en_materialize() MAY deduplicate, but there is no guarantee it will. (it currently
- doesn't, because an acyclic graph is required for evauator correctness, this might change).
- { type: "filterset",
-   root: 4,
-   items: {
-     { type = "prim_list", value = {1,2,3}},
-     { type = "rel", target = "a", relation = "EQ", value = "1", src = 0 },
-     { type: "prim_list", value = {1,2,3}},
-     { type: "rel", target = "b", relation = "EQ", value = "1", src = 2 },
-     { type: "intersect", srcs = { 1, 3 }}
- }
- Note: if you are intersecting filters on the same source filterset, en_filter_all will likely
- be faster.
+Create a filterset that matches the intersection of multiple filtersets.
+
+## INPUT
+A list of filtersets.
+
+## OUTPUT
+A filterset that matches a span only if it is matched by all of the input filtersets.
+
+## EXAMPLE
+local fs1 = en_filterset_from_range(0, 100)
+local fs2 = en_filterset_from_range(50, 150)
+local combined = en_filterset_intersect({fs1, fs2})

entrace_query/api-docs/en_filterset_materialize.md

@@ -1,3 +1,15 @@
- Materialize a filterset; which means going from the lazy representation of filters as a series
- of operations into a concrete list of matching indices.
- In some lazy languages, this operation is called "force".
+Materialize a filterset into a list of matching span IDs. 
+In some lazy languages, this operation is called *force*.
+
+## INPUT
+A filterset.
+
+## OUTPUT
+A list (sequence table) of span IDs.
+
+## EXAMPLE
+local fs = en_filterset_from_range(0, 100)
+local ids = en_filterset_materialize(fs)
+for i, id in ipairs(ids) do
+  en_log(id)
+end

entrace_query/api-docs/en_filterset_not.md

@@ -1,3 +1,11 @@
- en_filterset_not()
- input: filterset
- outputs: a filterset that matches an item exactly if it is not in the filterset.
+Invert a filterset.
+
+## INPUT
+A filterset.
+
+## OUTPUT
+A filterset that matches all spans not matched by the input filterset.
+
+## EXAMPLE
+local fs = en_filterset_from_range(0, 100)
+local inverted = en_filterset_not(fs)