hkit interface challenges

[Drew McLellan]

Looking for some opinions/advice on how hkit should be developed
moving forward.

One of my goals with hkit was always to make the interface (and here I
guess I'm primarily talking about the output from a parse) easy to use
for a php coder of pretty much any level. I can recall countless times
when I've downloaded some library or other only to find that so little
thought has gone into designing the interface that it's easier to
write my own version than to figure out how to use the library. Partly
that comes down to documentation and tutorials, but also it comes down
to design and using the simplest thing possible.

This is why hkit outputs a simple array structure, and not a bunch of
oblique objects. Any novice can print_r() the output and understand
what they're dealing with. The other advantage is that it becomes
trivial to convert that array into json - something that is essential
to maintain.

That said, as we add more features to the parser, it becomes more of a
challenge to keep the interface simple.

I'm trying to figure out the best way to present the @rel values that
accompany a URL. At present, when an A element with the class of URL
is found (primarily hCard) the value is represented as:

[url] => http://example.com/

This is obviously very easy to consume. However, if there are
accompanying rel values we have nowhere to show those. Taking the next
leap, we could change the interface to represent URL as an array:

[url] => Array
(
[value] => http://example.com/
[rel] => Array
(
[0] => friend
[1] => coworker
[2] => met
)

)

The downside here is that for simple cases where $result['url'] would
have done, $result['url']['value'] must be used.

Am I worrying too much? I think the tradeoff of the extra complexity
for simple cases is worth it for the added utility. As hkit users,
would you agree?

drew.

[Jeff McNeill]

Hello Drew,

Great effort here. I am wondering if both could be supported?

--
Sincerely,
Jeff McNeill
http://jeffmcneill.com/

[Drew McLellan]

On Jan 15, 7:13 pm, "Jeff McNeill" <j...@jeffmcneill.com> wrote:

> Great effort here. I am wondering if both could be supported?

Both as an option, or only an array when rel values are present?

My concern there would in be making the interface predictable. If URL
can sometimes be just a value and sometimes an array with a 'value'
key, the user needs to write code that expects that (or fail to do so
and have their code break).

drew.

[Jeff McNeill]

Hi Drew,

You are right, predictability is better. The array every time would be
more predictable.

Cheers,

--
Sincerely,
Jeff McNeill
http://jeffmcneill.com/

On 1/15/08, Drew McLellan <drew.m...@gmail.com> wrote:
>

[Drew McLellan]

Does anyone have any further thoughts on this? Is it ok to change the
interface and potentially make it harder for current users to upgrade?

I'm all for it at the moment, with a view to locking things down for
version 1.0.

drew.

[Steve Ivy]

Hi Drew,

Not having a lot of dependant code right now, I'm all for it ;-)

--Steve

--
Steve Ivy
http://redmonk.net // http://diso-project.org
This email is: [ ] bloggable [x] ask first [ ] private

[gareth rushgrove]

That sounds sensible. With more eyes on the problem the interface is
likely to want to change a little - but aiming for a stable API for a
version 1.0 release is a good plan.

Gareth

>
> drew.
> >
>

--
Gareth Rushgrove
garethrushgrove.com
morethanseven.net
getjobsin.com
isitbirthday.com

[Ezra e. k. Cooper]

If this topic is still open, I would suggest supporting both, in a
predictable way. In the 'url' field, put an array with all the URLs as
you explained. If there happens to be just one, then also populate a
field 'single_url' with that URL. In many use cases, the caller will
know whether to expect just one, and can use the shortcut 'single_url'
if so. Callers who aren't certain that there will be just one can
consistently use 'url'.

2c,
Ezra