Getting started guide, or some other form of high-level documentation?

[elenakrittik]

As far as my searching "skills" go, i couldn't find any definitive reference for Trustfall. README links to a few articles and talks, but they all speak mostly in theory. This repository doesn't seem to contain any examples too. Is there a high-level overview of working with Trustfall, or should i look at, e.g., cargo-semver-checks and docs.rs in the meantime?

EDIT: Found HYTRADBOI, but will leave the issue open in case i indeed missed some resources.

[obi1kenobi]

The state of our docs is not great, and I'm going to make a major push over the next couple of months to fix that.

There are some examples mentioned in the README that are part of the trustfall crate in this repo.

We also have playgrounds where you can see Trustfall language features in action via example queries over:

• the HackerNews REST API: https://play.predr.ag/hackernews
• popular Rust crates' source code: https://play.predr.ag/rustdoc

The docs on docs.rs are more of a reference than a getting started guide, unfortunately. The most common bits of the API are documented fairly thoroughly on docs.rs, but we can and should do much better still.

To see how Trustfall powers cargo-semver-checks, you'd need to look in a few places:

• the Trustfall adapter for querying rustdoc is in its own repo, since it also powers the playground: https://github.com/obi1kenobi/trustfall-rustdoc-adapter
• to support multiple rustdoc JSON formats, we use multiple adapters (one per format) and use this crate to transparently query whichever format we happened to get: https://github.com/obi1kenobi/trustfall-rustdoc
• cargo-semver-checks has a series of lint queries defined in its src/lints/ directory, and just calls a convenience function in the above crate with the query and variables it wants to run.

Trustfall also has bindings that allow writing adapters in Python and JS/TS, but they could use a fair bit of polish. They are fully-working prototypes but have rough edges and are in need of better docs themselves.

[obi1kenobi]

I'd love to learn about your use case!

What language are you looking to use?

What data source are you looking to query? What sorts of queries do you have in mind?

[elenakrittik]

Thank you very much for a thorough explanation!

I'd love to learn about your use case!

What language are you looking to use?

What data source are you looking to query? What sorts of queries do you have in mind?

I am developing a toolkit for Godot written in Rust, which, among other features, will include a linter for Godot's purpose-made language called GDScript. While looking through Rust tools to improve my toolkit's robustness, i found cargo-semver-checks, and then due to my habit of "hmm noice thing, let's check what else the author made" i found Trustfall, and it happens so that it seems to fit my use case perfectly (as proven by semver-checks with linting Rust code). So, my primary data source will be GDScript source code (and possibly other textual formats Godot uses), and queries will search for "code smells" like "find all variables in this file that are referenced only once" (unused variables) or "find all calls of functions in this file that start with "_" and are defined elsewhere" (private function usage).

[obi1kenobi]

That sounds very cool! I think Trustfall is going to be a good fit in such a linter, and I'm happy to answer any questions that come up.

Is the toolkit open-source, or is it proprietary / commercial software? I'd love to check it out!

[elenakrittik]

That sounds very cool! I think Trustfall is going to be a good fit in such a linter, and I'm happy to answer any questions that come up.

Is the toolkit open-source, or is it proprietary / commercial software? I'd love to check it out!

Yep, here you go: https://github.com/elenakrittik/gdtk

Thanks for taking interest.

[VorpalBlade]

I would be interested in some better docs too, in particular on the query language, which seems to be entirely undocumented outside of examples?

My use case is with the existing trustfall_rustdoc adapter in order to make a tool for finding paths through From/TryFrom/etc conversion. (E.g. a simple example: u64 -> char need to go through u32 as an intermediate step)

Since rustdoc is unstable it would seem to be a good idea to piggy back on the existing parser to extract the signatures for building the search graph.

EDIT: Apparently I already asked about this in #547 for a different idea some years ago. I had forgotten about that, since that project didn't pan out. And the docs on the query syntax seem to be just as missing as before.