'st', 'stc', 'stcs', 'sta', and 'stp' dsl subs about test2-suite

[jberger]

Agreed, the whole reason for a DSL is to have a declaratively written and
easy to read syntax. Spend the extra few characters, use full words

On Tue, Sep 13, 2016 at 2:37 PM Michael G. Schwern [email protected]
wrote:

I found the comment where this is all described and updated the issue
description. Now I get it.

These names violate the UI principle that different things should look
different. These functions do rather different things, yet they're named
almost exactly the same.

The names are not descriptive. A great interface is one where the user
knows immediately what a thing does just by looking at it. A good interface
is one where the user only has to be told what a thing does once, then they
can recall what it does just by looking at it. A bad interface must be
memorized. I just read all their descriptions and I still can't remember
what stcs does.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#76 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAs6FW3BITJH21f6jqLkAIoGkuzFYatQks5qpvt3gaJpZM4J6LHS
.

[schwern]

I have no idea what those names might represent.

[schwern]

Reading through all the context in the other issues, I think the idea is to have the st salad be generic forms of various type checks to replace the "types" like array, hash, object, and so on.

Internally, whatever makes sense. But from a user perspective I think this is a terrible idea.

I could say a lot more about the UI consequences, but first let's get better names in there otherwise it will overwhelm the discussion. Even knowing all the context I have no idea what they mean and even less what they do, how they're different, and when one should be used over another.

I'll guess...

• st: Standard type?
• stc: Standard type check?
• stcs: Standard type check... seriously?
• sta: Standard type all?
• stp: I know this one! It's a brand of motor oil.

Chad, what are these things? We can come up with some better names to start.

[exodist]

• st - structure
• stc - structure component (key => val, index => val, etc)
• stcs - structure components (multiple at once, like passing several items to an array)
• sta - structure attribute, ie a method on the check you want toggled, such as check-end, no-end, filter, etc.
• stp - structure property, ie a property of the thing being checked, number of elements, blessed to what, reftype, etc.

These 5 represent everything all the other keywords do, but in the 5 generic forms.

[schwern]

I found the comment where this is all described and updated the issue description. Now I get it... except I don't.

These names violate the UI principle that different things should look different. One of these functions does a rather different thing, st, yet it's named like all the others.

The names are not descriptive. A great interface is one where the user knows immediately what a thing does just by looking at it. A good interface is one where the user only has to be told what a thing does once, then they can recall what it does just by looking at it. A bad interface must be memorized. I just read all their descriptions and I still can't remember what stcs does.

[exodist]

ok, how about these:

• struct
• comp
• components
• attr
• prop

Only the 5'th one has a conflict with current terms, but it can be expanded so that it isn't a breaking change. These are short enough to be convenient, but long enought o be descriptive.

[exodist]

'components' specifically is rarely used in my experience, so I am ok with it being longer.

[schwern]

(I keep thinking of new things to add, but I'll break myself of the habit of constantly editing my comments.)

Another UI problem is the four categories the functions are split into: "component", "components", "attribute", and "property". None of these are in my head when I think about Perl structures in part because it's hard to remember what any of them are, but also because none of them map to how Perl structures are typically thought of. They're either overly generic, or unrelated.

"attribute" is about modifying the check, not describing the thing. It's different and it should look different. The name should describe that it is altering the check itself. Also "attribute" already has a meaning in Perl.

"component" is so generic it basically has no meaning. Might as well call it "assert".

"property" is no clear meaning in Perl 5. I don't know what it means to check if a thing has a "property".

[schwern]

Rather than my bagging on this all day trying to fix this, why don't we back up and lay out what problems it's trying to solve?

[exodist]

The problem is we keep adding keywords for the same type of actions. The dsl is gaining too many keywords when it can make do with ~5. Also sometimes things that are the same type of action string(...) and array { ... } have different calling conventions

I have broken it down to these 5 actions

• define a check say a string check, a hash check, and object check, etc.
• define something that is part of the check, an array element, a hash key+value, a substring, etc.
• define multiple elements at once (ie list several array elements at once)
• define settings (attributes) for the check, check bounds, allow extra items, invert checks (negate) etc.
• check things about the value we got that are not necessarily direct items under it, such as how it is blessed, what ref type it is, how many elements, or even nest a second check for the thing itself

I will create another comment with examples of each of these from the current dsl keywords shortly.

[petdance]

Can I suggest that rewriting the DSL might be overkill?

[exodist]

@petdance, not rewriting, writing generics that can be used to avoid adding tons of inconsistent keywords.

[exodist]

Here are the real-world examples I promised.

define structure checks:

array { ... };
string("foo");

define parts/components of a structure:

array {
    item 0 => 'foo';
    item 'bar'; # defaults to next idx, 1
}

hash {
    field foo => 1;
    field bar => 1;
}

multiple components: DSL cannot actually do this yet, but we have a ticket to do it (#64)

settings/attributes:

hash {
    field foo => 1;
    end(); # <-- here, this is it
}

properties:

object {
    prop this => hash { ... }; # Check the underlying hash
    prop size => 4; #Check number of hash keys, or array elements for this object
    prop blessed => 'Foo::Bar';
    ...
}

[exodist]

Just to be clear, I don't want to remove the current dsl keywords, and I am not opposed to adding some more, but I want a generic form of the main types of actions so that we don't always NEED new keywords. Also it allows an alternative if a keyword defines common helpful syntax that you occasionally want to work around (IE requiring a block prototype the way array does).

[schwern]

I wrote up my vision for the interface as Test-More/test-more#979 that I think resolves these problems while keeping things easy to understand.

Please comment on it in Test-More/test-more#979.