Example usage/tests in ucm

[EvanBurchard]

I'm not sure what the difference is between usage/examples/tests, but maybe "examples" and "tests" are the same, and "usage" just refers to a canonical example? Maybe there's a way to set a particular test as canonical?

usage

view.usage .base.Int.maxInt

          > .base.Int.maxInt
          ⧩
          +9223372036854775807

tests

view.tests .base.Int.mod

    > .base.Int.mod +12 +3
    ⧩
    +0

    > .base.Int.mod +12 +4
    ⧩
    +0

    > .base.Int.mod +12 +5
    ⧩
    +2

[atacratic]

When you mentioned this on slack I was guessing you had something like the following hypothetical command in mind, to let people explore the definition dependency graph.

.> uses-of foo

The following definitions refer to foo directly:
1. bar : Int
2. baz : '{IO} ()
3. wurp : Nat -> Nat

Try uses-of.transitive to see all definitions that depend on foo, either 
directly or indirectly.

Try used-by foo to see definitions that foo itself refers to.

I'm not totally clear on how your commands differ from this. Is it that you're only wanting watch expressions and tests? Is the motivation that you want to be able to find some code that you can actually run, that uses a given definition? Could you say a bit more about that? You're just expecting usages that already exist in the codebase, right? Is this something you think would get used like documentation?

Side note: as I write this I feel a longing for a system for composing filters for finding and processing definitions. Examples...

• uses-of.transitive foo | filter.watch | edit
• find : Foo | filter.author Alice | view One day maybe!

[EvanBurchard]

Is the motivation that you want to be able to find some code that you can actually run, that uses a given definition?

Yes, precisely this. I know that type signatures reveal a lot, but tests (and especially pointing at a specific case or two) are better (or necessary?) for beginners I think.

The examples I gave aren't what I personally need to use those functions, but "this code would work if you wrote it" might be good for people who haven't worked with haskell before. For me, the documentation on abilities is nice, but if I could see usages of io and read/write files a few times, the abstraction would sink in a little better.

The uses-of command seems good, but also a bit more advanced compared to test cases, especially one or more written specifically to be used as a reference.

[aryairani]

Would we say this is a duplicate of #802 ?

[atacratic]

Ah, hadn't seen that. But let's keep this issue open, tracking the 'show me stuff I can run' use case, i.e. filtering to watches/tests (with maybe a transitive walk through dependents).