Help with function documentation

I'm trying to build some print resources to keep near as a reference as I explore, however when I look up a function it's not totally clear to me what the syntax notation indicates.

for instance:

'offadd :: Num a => Pattern Time -> Pattern a -> Pattern a -> Pattern a'

seems to indicate the command is followed by a number and acts upon Pattern time, but what are the differences between the => and -> and why are there 3 "Pattern a ->" listed after while other functions list only two?

With juxBy:

juxBy :: Pattern Double -> (ControlPattern -> ControlPattern) -> ControlPattern -> ControlPattern

I know that the the command is followed by a double, but is it also ok to use a pattern of doubles? '"0.1 0.3 0.5 0.7"' for instance? I've seen the parenthetical passed functions chained with a "." does that account for the extra ControlPattern in the parenthesis?

I see there are a lot of types of patterns, for instance what is the distinction between ControlPattern, Pattern a, Pattern b, and Pattern ControlMap?

One other thing I was thinking regarding tutorial worksheets:
What if the worksheets were downloadable .tidal documents where the example code could be evaluated on the page. Not to say students shouldn't be practicing entering commands, but it could be something like:

Here's how to use suchAndSuch:

   d1 $ suchAndSuch 2 

That format also works for otherFunction why don't you try entering that here:

I can see it being really useful to have those saved as an interactive encyclopedia of sorts. Perhaps that idea in itself would be useful, to make the function reference an interactive .tidal document? Does that already exist? I'd love to get other peoples take on this

I appreciate any help with this. It's been about a year since my last stab at learning this and I already feel much more capable than I did my first go. Thank Yaxu for putting this together.
Cheers,
Jesse

1 Like

I might try to help here since I've been studying Haskell from its basics and this sounds like a good way to check whether I understand stuff :slight_smile:

The => you find after :: represents a class constraint: when it says Num a it means that whenever you see the a as input argument, it has to belong to the Num typeclass -- and all numbers belong to this class. Furthermore, if you have two Pattern Double as input, you will get a Pattern Double as input. The a here means that the pattern could be of any type within the Num typeclass.

As per the number of arguments, I understand that the last Pattern a is what the function returns and the others are input args. Therefore you happen to have a function that asks for 3 arguments as input. The -> separates the function parameters (if it has some more meaning, this I don't know sorry).

So, the way I would read the function declaration is: offadd takes a pattern of time, two numeric patterns and returns a numeric pattern.

2 Likes

Thanks @mattia.paterna !

In case others are put off by this theoretical side, don’t worry, we’ll be keeping things hands-on and practical for the most part. I’m happy to go into the theory more if you’re feeling brave though!

As for the worksheets idea - yes the idea is indeed to have downloadable .tidal files with inline notes. Probably one per video, once we start getting into tidal itself rather than installation etc.

3 Likes

Alex, for the theoretical stuff, will you set up a category or for now is it better to go to the tidal-innard channel on TOPLAP?

Maybe just create ‘uncategorized’ topics for now. We can create categories later when it’s clearer what there’s a need for.

1 Like

Hi Mattia, I really appreciate you chiming in, your response answers a lot of the questions I was having. After reading your response I went off to look up class constraints, and found some more information on classes and types in Haskell, which I’m linking here if anyone else would like to take a look.

It’s really great to have stepped into such a generous community.
Thank you,
Jesse Johannesen

4 Likes

Thanks for your words Jesse!
I am exactly following LYAH, I love it. The hard bit here, at least for me, is to apply what I learn to tweaking things in Tidal.
Please reach out if you want to discuss and/or deep-dive into these things!

1 Like

I think I will create an ‘innards’ category later. I don’t really like divides between “technical” and “non technical”, as that can become a bit of a class divide, and doesn’t really make sense… All arts practice involves technical aspects. But “innards” implies topics that are more about the inner workings of tidal rather than applications of it.
I think also at some point I will open up this forum so that there isn’t a pay(as you feel)wall in front of it all, just the bits for the course materials. We’ve had a section on https://forum.toplap.org/ for a long while, but it hasn’t really had much use. I have a feeling that a tidal-specific forum could get a lot more traction, though.

1 Like

Agree with what you said @yaxu -- I think that there should be an effort to group all different resources, otherwise things get too spread.
Just as an example, if I have a more technical question right now I will have to

  • check on the toplap forum whether there is already a similar one
  • check on the #tidal-innards chat
  • check here
  • decide what to write and where