Add example for using a custom predicate

[kevinjfoley]

I had some trouble when first using a custom predicate and so wanted to suggest/offer a section with an example on how they can be used.

[alphapapa]

Thanks for your patience. I'll take a look at this when I work on this package again.

[alphapapa]

Hi Kevin,

Thanks for your patience on this.

The specific example you gave, searching for a property value with inheritance, is one that I think needs to be covered by built-in predicates, if it isn't already. So rather than add an example which would direct users to use a custom expression for something which is, or will be, built-in, I'd rather enhance the property predicate (or add one that searches with inheritance).

It would be good to add an example of using an arbitrary expression, though. Could we find a different one that would seem realistic to use? What do you think?

[alphapapa]

Well, I made a new way to make "custom predicates". See https://github.com/alphapapa/org-ql/blob/master/examples/defpred.org :)

It would still be good to have an example like yours in the documentation though, to show how arbitrary expressions can be used as the ACTION form when searching.

[kevinjfoley]

I'm starting to think you're just determined to not merge any of my PR's 😝

Could we find a different one that would seem realistic to use? What do you think?

I agree a non built-in example would be best, however I think the difficulty is finding one that is "realistic to use" that also shouldn't be "be covered by built-in predicates". Maybe a property regexp check?

Well, I made a new way to make "custom predicates". See https://github.com/alphapapa/org-ql/blob/master/examples/defpred.org :)

This looks awesome, excited to use it!

It would still be good to have an example like yours in the documentation though, to show how arbitrary expressions can be used as the ACTION form when searching.

Would it make sense to refer to the section in my PR as "arbitrary expressions" then as opposed to "custom predicates"?

[alphapapa]

I'm starting to think you're just determined to not merge any of my PR's

D:

Could we find a different one that would seem realistic to use? What do you think?

I agree a non built-in example would be best, however I think the difficulty is finding one that is "realistic to use" that also shouldn't be "be covered by built-in predicates". Maybe a property regexp check?

Yeah, that would probably be good for a demo.

It would still be good to have an example like yours in the documentation though, to show how arbitrary expressions can be used as the ACTION form when searching.

Would it make sense to refer to the section in my PR as "arbitrary expressions" then as opposed to "custom predicates"?

Yes, I think that'd be great.

Thanks.

[alphapapa]

Revisiting this, I think the idea to show the use of custom or arbitrary predicate expressions in the docs is a good one, and I still think that whatever example we use should be one that's obviously not covered, or shouldn't be covered, by built-in predicates. Please let me know if you have any more thoughts on it.

In the interest of pushing out a stable release sooner, I'm deferring this to 0.7 (though being a simple documentation change, it can be done anytime).

[yantar92]

Revisiting this, I think the idea to show the use of custom or arbitrary predicate expressions in the docs is a good one, and I still think that whatever example we use should be one that's obviously not covered, or shouldn't be covered, by built-in predicates. Please let me know if you have any more thoughts on it.

I have a use-case that might be used as an example here:

'(and (scheduled :to 0) (if (property "SHOWFROMDATE") (ts< (ts-parse-org (org-entry-get (point) "SHOWFROMDATE")) (ts-now)) t))

This predicate expression searches headings scheduled up to today. However, if a heading has SHOWFROMDATE property, it only matches when timestamp stored in the property is in the past.