phpweather-devel

Design for PHP Weather 2

[Martin G. <gim...@gi...>]

Hi again

I've thought some more about how we could structure PHP Weather 2. The
design that's currently in CVS isn't final - it's actually my first
attempt at using objects in a program. I've learned Java since, and
with that a lot of OO.

My plan is to separate the METAR-parsing logic from the output. So we
should have a class phpweather that handles the parsing of the METAR
and uses the database-layer to cache it.

Then we should have several modules (two so far) which talk to the
phpweather object and retrieves the parsed METAR from it. They can
also obtain things like the ICAO and location from the class
phpweather (which can find this information in the database).

The module should work together with a locale to produce the output.
If it doesn't need any localization information, then the locale can
be left out.

So you would probably do something like this:

$weather =3D new phpweather('EKYT');
$locale =3D new pw_locale_en();
$text =3D new pw_module_text($weather, $locale,
                           array('mark_begin' =3D> '<i>',
                                 'mark_end' =3D> '</i>');
$icon =3D new pw_module_icon($weather);

echo $text->get_output();
echo '<img src=3D"' . $icon->get_output() . '">';

Does this kind of separation make sense?

We would of course have to think about how we are going to let the
locales customize the output of the modules...

=2D-=20
Martin Geisler                       My GnuPG Key: 0xF7F6B57B

See my homepage at http://www.gimpster.com/ for:
PHP Weather =3D> Shows the current weather on your webpage.
PHP Shell   =3D> A telnet-connection (almost :-) in a PHP page.

Re: Design for PHP Weather 2

[Martin G. <gim...@gi...>]

"Martin Geisler" <gim...@gi...> writes:

> Hi again

I'll just expand on what I said a little earlier...

> My plan is to separate the METAR-parsing logic from the output. So
> we should have a class phpweather that handles the parsing of the
> METAR and uses the database-layer to cache it.
>
> Then we should have several modules (two so far) which talk to the
> phpweather object and retrieves the parsed METAR from it. They can
> also obtain things like the ICAO and location from the class
> phpweather (which can find this information in the database).
>
> The module should work together with a locale to produce the output.
> If it doesn't need any localization information, then the locale can
> be left out.

I think it's going to be hard (impossible?) to separate the
output-modules from the locales. As it is now, locale_common should
probably be considered an output-module: it knows how to produce
textual output. The locales then extend this class. This cannot work
if there are more than one of these classes, so I suggest that we
simply drop the idea about having a seperate locale and output-module.

So, instead of having this:

                            ---> output_(text/icons/...)
                           /
  DB <----> phpweather <--<
                           \
                            ---> locale_(en/da/...)

where the locale has to work together with the output-modules in a
rather tricky way, I think we should have this:

                                               +-- output_text_en
                                               |
                           ---> output_text <--+-- output_text_da
                          /                    |
  DB <---- phpweather <---+---> output_icons   +-- output_text_xx
                          \
                           ---> output_wap <---+-- output_wap_en
                                               |
                                               +-- output_wap_da
                                               |
                                               +-- output_wap_xx

In this setup, phpweather is the superclass of metar-parser and the
db-layer. Seperated from hierarchy, we have the output-modules. We
have the three base-classes: output_text, output_icons, and
output_wap. The output_text and output_wap classes are sub-classed by
the different language-classes, whereas output_icons doesn't need any
internationalization.

> So you would probably do something like this:
>
> $weather =3D new phpweather('EKYT');
> $locale =3D new pw_locale_en();
> $text =3D new pw_module_text($weather, $locale,
>                            array('mark_begin' =3D> '<i>',
>                                  'mark_end' =3D> '</i>');
> $icon =3D new pw_module_icon($weather);
>
> echo $text->get_output();
> echo '<img src=3D"' . $icon->get_output() . '">';

With the new proposal, this would be something like this:

$weather =3D new phpweather('EKYT');
$text =3D new pw_output_text_en($weather,
                              array('mark_begin' =3D> '<i>',
                                    'mark_end'   =3D> '</i>'));

$icon =3D new pw_output_icon($weather);

echo $text->get_output();
echo '<img src=3D"' . $icon->get_output() . '">';

Or perhaps it should just be

$icon =3D new pw_output_icon($weather->get_data());

where get_data() would return an array with the parsed metar plus
things like the location etc.

> We would of course have to think about how we are going to let the
> locales customize the output of the modules...

That should work automatically now.

=2D-
Martin Geisler                       My GnuPG Key: 0xF7F6B57B

See my homepage at http://www.gimpster.com/ for:
PHP Weather =3D> Shows the current weather on your webpage.
PHP Shell   =3D> A telnet-connection (almost :-) in a PHP page.

Re: Design for PHP Weather 2

[Max H. <ma...@fl...>]

> > My plan is to separate the METAR-parsing logic from the output. So
> > we should have a class phpweather that handles the parsing of the
> > METAR and uses the database-layer to cache it.
> >
> > Then we should have several modules (two so far) which talk to the
> > phpweather object and retrieves the parsed METAR from it. They can
> > also obtain things like the ICAO and location from the class
> > phpweather (which can find this information in the database).
> >
> > The module should work together with a locale to produce the output.
> > If it doesn't need any localization information, then the locale can
> > be left out.
>
> I think it's going to be hard (impossible?) to separate the
> output-modules from the locales. As it is now, locale_common should
> probably be considered an output-module: it knows how to produce
> textual output. The locales then extend this class. This cannot work
> if there are more than one of these classes, so I suggest that we
> simply drop the idea about having a seperate locale and output-module.

I think that the locale is intrinsic in any function that returns text...


> In this setup, phpweather is the superclass of metar-parser and the
> db-layer. Seperated from hierarchy, we have the output-modules. We
> have the three base-classes: output_text, output_icons, and
> output_wap. The output_text and output_wap classes are sub-classed by
> the different language-classes, whereas output_icons doesn't need any
> internationalization.
>
> With the new proposal, this would be something like this:
>
> $weather = new phpweather('EKYT');
> $text = new pw_output_text_en($weather,
>                               array('mark_begin' => '<i>',
>                                     'mark_end'   => '</i>'));
>
> $icon = new pw_output_icon($weather);
>
> echo $text->get_output();
> echo '<img src="' . $icon->get_output() . '">';

I'd be happier to see
$weather = new pw_weather('EGBE');
$text = new pw_text($weather,"en");
$icons = new pw_icons($weather);

echo $text->print_pretty() . '<br />
<img src="'.$icons->src_main().'" />';

etc.

- let's not mess about with different functions for each locale, it'll be
much easier to add new locales if we select it in the function itself,
rather than defining the function to be locale-specific.

An alternative to this schema is if the output functions actually extend
the phpweather class, but I can see problems if we want to produce both
text and icons...

> Or perhaps it should just be
>
> $icon = new pw_output_icon($weather->get_data());

no. Let's do it properly OO. Pass it the object, then it'll be easier to
get out anything we need at a later date. We should be consistent, so that
any output function should take the $phpweather object.

Max

-- 
Never put the words "Diabolical Master Plan" on a CV

Re: Design for PHP Weather 2

[Martin G. <gim...@gi...>]

Max Hammond <ma...@fl...> writes:

>> I think it's going to be hard (impossible?) to separate the
>> output-modules from the locales. As it is now, locale_common should
>> probably be considered an output-module: it knows how to produce
>> textual output. The locales then extend this class. This cannot
>> work if there are more than one of these classes, so I suggest that
>> we simply drop the idea about having a seperate locale and
>> output-module.
>=20
> I think that the locale is intrinsic in any function that returns
> text...

Yes - so we shouldn't try and split the function that generates text
away from it's locale.=20

What I'm proposing is actually just a change of names: locale_common
is very tightly coupled with the textual output, so it should become
the base-class for that output module. The icons should also have
their own output module.

>> [...]
>> echo $text->get_output();
>> echo '<img src=3D"' . $icon->get_output() . '">';
>=20
> I'd be happier to see
> $weather =3D new pw_weather('EGBE');
> $text =3D new pw_text($weather,"en");
> $icons =3D new pw_icons($weather);

Should the pw_text object then include a file with the English
strings? If so, then how does the English translation override
something in pw_text?

I know that I keep talking about this idea, but I have a feeling that
it'll come in handy at some time. We actually discussed using it for
the Hungarian translation where Mih=E1ly Gyulai had some problems with
some of the strings.
=20
> echo $text->print_pretty() . '<br />
> <img src=3D"'.$icons->src_main().'" />';
>=20
> etc.
>=20
> - let's not mess about with different functions for each locale,
> it'll be much easier to add new locales if we select it in the
> function itself, rather than defining the function to be
> locale-specific.

But I was thinking that each locale was it's own class. That should
also make it easy to add new locales - you just subclass a suitable
language and change what needs to be changed.

This would enable an British-English class could inherit from the
current British-American class and change only a couple of words,
things like 'color' to 'colour' and so on. And if the British-American
class has overridden some methods in the base-class (very unlikely)
then that will benifit the British-English class as well.
=20
> An alternative to this schema is if the output functions actually
> extend the phpweather class, but I can see problems if we want to
> produce both text and icons...

Yes, I think they have to be separate. It wouldn't make sense to make
two phpweather objects and parse the METAR twice to get both text and
icons.
=20
>> Or perhaps it should just be
>>
>> $icon =3D new pw_output_icon($weather->get_data());
>=20
> no. Let's do it properly OO. Pass it the object, then it'll be
> easier to get out anything we need at a later date. We should be
> consistent, so that any output function should take the $phpweather
> object.

Right. That's exactly why I'm glad we're discussing this: our system
should be flexible and extensible. The first version of PHP Weather
was written without any planning. I just found some code that could
decode a METAR, I added some extra utility functions, and the result
is what you see today.

Now that we're doing a rewrite, then we have the chance to come up
with a structure that can last for some time.

=2D-=20
Martin Geisler                       My GnuPG Key: 0xF7F6B57B

See my homepage at http://www.gimpster.com/ for:
PHP Weather =3D> Shows the current weather on your webpage.
PHP Shell   =3D> A telnet-connection (almost :-) in a PHP page.

RE: Design for PHP Weather 2

[Max H. <ma...@fl...>]

Hi all,

> What I'm proposing is actually just a change of names: locale_common
> is very tightly coupled with the textual output, so it should become
> the base-class for that output module. The icons should also have
> their own output module.
>
> >> [...]
> >> echo $text->get_output();
> >> echo '<img src=3D"' . $icon->get_output() . '">';
> >
> > I'd be happier to see
> > $weather =3D new pw_weather('EGBE');
> > $text =3D new pw_text($weather,"en");
> > $icons =3D new pw_icons($weather);
>
> Should the pw_text object then include a file with the English
> strings? If so, then how does the English translation override
> something in pw_text?

yes, include() it from the pw_text class. It wouldn't necessarily be an
override, it could work in a similar way to the way it does at the moment.

> I know that I keep talking about this idea, but I have a feeling that
> it'll come in handy at some time. We actually discussed using it for
> the Hungarian translation where Mih=E1ly Gyulai had some problems with
> some of the strings.

There's nothing to stop us doing both... Most languages will work with th=
e
same "template", I think. We could make different classes for anything
that's so different that our assumptions about syntax and grammar don't h=
old
at all. I'm not keen to do things like this, but it's an option.

> > echo $text->print_pretty() . '<br />
> > <img src=3D"'.$icons->src_main().'" />';
> >
> > etc.
> >
> > - let's not mess about with different functions for each locale,
> > it'll be much easier to add new locales if we select it in the
> > function itself, rather than defining the function to be
> > locale-specific.
>
> But I was thinking that each locale was it's own class. That should
> also make it easy to add new locales - you just subclass a suitable
> language and change what needs to be changed.

sorry, I meant to say class rather than function.

I'm still not convinced that subclassing the languages is going to help. =
I
see it as "the purpose of the output object is to return text" - and that=
 is
true for whatever language, so it makes sense that that output object is
configurable, rather than replacable.

> This would enable an British-English class could inherit from the
> current British-American class and change only a couple of words,
> things like 'color' to 'colour' and so on. And if the British-American
> class has overridden some methods in the base-class (very unlikely)
> then that will benifit the British-English class as well.

You could override those same methods in the localisation include file, i=
f
you do:

basic_text <------ pw_text
                     ||
               pw_loc_en-gb.inc

Most of the functions we need are actually in the basic_text object, and
pw_text only really exists to apply localisation to it.

> >> Or perhaps it should just be
> >>
> >> $icon =3D new pw_output_icon($weather->get_data());
> >
> > no. Let's do it properly OO. Pass it the object, then it'll be
> > easier to get out anything we need at a later date. We should be
> > consistent, so that any output function should take the $phpweather
> > object.
>
> Right. That's exactly why I'm glad we're discussing this: our system
> should be flexible and extensible. The first version of PHP Weather
> was written without any planning. I just found some code that could
> decode a METAR, I added some extra utility functions, and the result
> is what you see today.

And it's still a great piece of work - It does what it does very well.

Max

Re: Design for PHP Weather 2

[Martin G. <gim...@gi...>]

"Max Hammond" <ma...@fl...> writes:

> Hi all,
>=20
>> Should the pw_text object then include a file with the English
>> strings? If so, then how does the English translation override
>> something in pw_text?
>=20
> yes, include() it from the pw_text class. It wouldn't necessarily be
> an override, it could work in a similar way to the way it does at
> the moment.

But at the moment, we have subclasses for each language - this isn't
what you mean, is it?
=20
>> I know that I keep talking about this idea, but I have a feeling
>> that it'll come in handy at some time. We actually discussed using
>> it for the Hungarian translation where Mih=E1ly Gyulai had some
>> problems with some of the strings.
>=20
> There's nothing to stop us doing both... Most languages will work
> with the same "template", I think. We could make different classes
> for anything that's so different that our assumptions about syntax
> and grammar don't hold at all. I'm not keen to do things like this,
> but it's an option.

I agree that most languages should work with the same template. So
their classes would simply have a constructor that initializes
$strings with the right strings to fill in the template.

You would rather have this initialization of the $strings in a file
that's included by the template, right?
=20
> I'm still not convinced that subclassing the languages is going to
> help. I see it as "the purpose of the output object is to return
> text" - and that is true for whatever language, so it makes sense
> that that output object is configurable, rather than replacable.

I'm not talking about replacing the output module, I'm talking about
extending and overriding it for languages which dont fit into the
template provided by the basic output module.

>> This would enable an British-English class could inherit from the
>> current British-American class and change only a couple of words,
>> things like 'color' to 'colour' and so on. And if the
>> British-American class has overridden some methods in the
>> base-class (very unlikely) then that will benifit the
>> British-English class as well.
>=20
> You could override those same methods in the localisation include
> file, if you do:

But you can't override function definitions in an included file. That
is, unless we do something like this in our output module:

include("pw_locale_$language.inc");

if (!function_exists('output_temp')) {

  function output_temp($c, $f) { ... }

}

I'm not even sure that it would work as I've coded it above..

That's why I'm thinking about having the localisation subclass the
basic output instead of just including a file.
=20
> basic_text <------ pw_text
>                     ||
>                pw_loc_en-gb.inc
>=20
> Most of the functions we need are actually in the basic_text object,
> and pw_text only really exists to apply localisation to it.

Ahh - I think we almost agree :-) We have an basic_text object with
the methods needed to do textual output. (This is what locale_common
does today). Do you then want the pw_text object to subclass
basic_text or do you want basic_text to use an pw_text object like the
db_layer currently uses a db_mysql object?

Also, what is the difference between the basic_text and pw_text
classes? If pw_text only exists to apply localization, then why dont
we just call it pw_text_en, pw_text_da and so forth?

>> The first version of PHP Weather was written without any planning.
>=20
> And it's still a great piece of work - It does what it does very
> well.

Thanks - but the code that handles the databases are pretty ugly.
=20
=2D-=20
Martin Geisler                       My GnuPG Key: 0xF7F6B57B

See my homepage at http://www.gimpster.com/ for:
PHP Weather =3D> Shows the current weather on your webpage.
PHP Shell   =3D> A telnet-connection (almost :-) in a PHP page.