JText Platform Effort
Amy Stephen
First - will we replace all JText messages? (Meaning beyond exceptions, so including JLog statements?)
Second - should we keep track of the language strings removed for a later patch so that those values can then be removed from the CMS language files?
Third - if it is still important to translate the JLog statements, can we add JText in the JLog class -- so that the JText dependency can be removed throughout the framework? (Personally, I think uncoupling the translation class would be helpful.)
Finally - I'd like to do a subsystem at a time to keep the work units small and easy to adapt. (That should also make it easy for others who might be looking for small, easy jobs to do to get started with the platform). I can see you are selecting an SPL Exception that is a better fit for the exception. I am not familiar with these categorizations yet and I don't have a feel for how you might be looking at this, so I am certain you'll have feedback on my choices -- keeping the scope narrow will help. I assume this is the list from which to choose? http://www.php.net/manual/en/spl.exceptions.php
Thanks.
Andrew Eddie
> Before I get started on continuing Andrew's work with JText
> https://github.com/eddieajau/joomla-platform/commit/48d20ffae01d18a3df05b4399769ffac67d58c87,
> I wanted to ask a couple of questions.
>
> First - will we replace all JText messages? (Meaning beyond exceptions, so
> including JLog statements?)
Let's start with thrown exceptions and see how it goes. This is going
to be an iterative process and it's probably best to start small and
progress slowly.
> Second - should we keep track of the language strings removed for a later
> patch so that those values can then be removed from the CMS language files?
I think it should be a simple matter for someone to devise a grep for
the CMS on JLIB_* strings, and then just do a diff on a sorted list of
existing and found strings. I haven't been keeping track myself.
Long term we probably won't have any platform classes using JText for
messages.
> Third - if it is still important to translate the JLog statements, can we
> add JText in the JLog class -- so that the JText dependency can be removed
> throughout the framework? (Personally, I think uncoupling the translation
> class would be helpful.)
I think translation of the messages, if required, happens outside of
JLog. JLog should just process the message it's given and shouldn't
have any coupling to the translation system, even by composition.
> Finally - I'd like to do a subsystem at a time to keep the work units small
> and easy to adapt. (That should also make it easy for others who might be
> looking for small, easy jobs to do to get started with the platform).
Agree.
> I can
> see you are selecting an SPL Exception that is a better fit for the
> exception. I am not familiar with these categorizations yet and I don't have
> a feel for how you might be looking at this, so I am certain you'll have
> feedback on my choices -- keeping the scope narrow will help. I assume this
> is the list from which to choose?
> http://www.php.net/manual/en/spl.exceptions.php
If in doubt, it's probably going to be a RuntimeException.
If you are checking an argument sent to a function or method, and it
fails a condition, I usually throw an InvalidArgumentException with
the name of the method called. 99.% of the time these are problems
the developer has to fix so getting a terse programmer-centric message
is not a problem. Eg:
throw new InvalidArgumentException(sprintf('%s::foo(*%s*)',
get_class($type), gettype($foo));
There's no need to embellish the message with "has an invalid
argument" because it's implied by the exception type.
While in a method, if you get an unexpected result from calling some
other API, like an array is empty when it shouldn't be, I usually
throw an UnexpectedValueException, e.g.:
$things = $this->getThings();
if (empty($things)
{
throw new InvalidArgumentException(sprintf('getThings in %s::foo()
returned an empty array', get_class($type));
}
It's a bit harder to know how to craft this message succinctly. We
need enough information for the developer to have a clue where to go
looking if they get a report of that exception being thrown.
Let's try and nail the easy ones first.
The other thing that can be done is a sweep of the checks on if
($db->getErrorMsg()). Those can all be removed now because the DB
drivers will throw exceptions and never get to that code.
Also, I still haven't had time to follow up on the "return
JError::raise*" case yet.
Regards,
Andrew Eddie
Andrew Eddie
> On 23 March 2012 12:53, Amy Stephen <amyst...@gmail.com> wrote:
> $things = $this->getThings();
> if (empty($things)
> {
> throw new InvalidArgumentException(sprintf('getThings in %s::foo()
> returned an empty array', get_class($type));
> }
That should be "UnexpectedValueException".
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers
JM Simonet
to translate Errors in the CMS?
As I spent countless hours implementing this in 1.6 for the sake of
our International users, I would apprciate this to be discussed.
JM
--
>Please keep the Subject wording in your answers
This e-mail and any attachments may be confidential. You must not
disclose or use the information contained in this e-mail if you are
not the
intended recipient. If you have received this e-mail in error, please
notify us immediately and delete the e-mail and all copies.
-----------------------------------------------------------
Jean-Marie Simonet / infograf768
Joomla Production Working group
Joomla! Translation Coordination Team
Andrew Eddie
What we are changing back to plain text are programmers errors
(exceptions actually). These are things like "Cannot find Controller
file XYZ". These are messages that the developer should see if
they've made a mistake during development and they are an unnecessary
overhead on your translators.
Messages like "1 article published" (system messages) have not been changed.
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers
On 23 March 2012 16:18, JM Simonet <infog...@gmail.com> wrote:
> Would you be kind enough to explain why we would not be able anymore to
> translate Errors in the CMS?
> As I spent countless hours implementing this in 1.6 for the sake of our
> International users, I would apprciate this to be discussed.
>
> JM
>
>
>
JM Simonet
thanks for your reply.
I did understand that this kind of errors were indeed at stake and I
can't but welcome taking off any overhead from translators.
I had remarked though that in the past months, no effort was made in
the platform to use JText for new errors (in fact all new ones are in
plain English) and I have been worrying about it.
Let me be the non anglo-centric devil's advocate:
I have not seen any discussion on this decision, i.e. questionning
non native English-speaking developpers.
Should all developpers in the world be fluent in English to understand errors?
Or is this battle already lost?
JM
Andrew Eddie
> Let me be the non anglo-centric devil's advocate:
> I have not seen any discussion on this decision, i.e. questionning non
> native English-speaking developpers.
> Should all developpers in the world be fluent in English to understand
> errors?
> Or is this battle already lost?
It's a fair question and I'm open to discussion about it. However,
the API is in English so if a developer can read English PHP then it's
fair to say they will be able to read English error messages that
relate directly to the code. That's my point of view anyway.
However, at the application level, there's nothing stopping the
developer from wrapping such errors in a translatable string. For
example, a database error is generally not translated, but a developer
might wrap that error message in "The database threw this error: %s"
and then display that through JText. The point is to translate "late"
(at the application level, like the CMS error page), not "early" (at
the platform level unless it is absolutely necessary).
JM Simonet
the framework, any absent string would be replaced by a hardcoded
English phrase?
As of now, it is only when a full ini file does not exist in a said
language, that it loads the en-GB default ini.
Something like
throw new
Exception(JTextErr::sprintf('JLIB_FORM_ERROR_FIELDS_GROUPEDLIST_ELEMENT_NAME',
'Unsupported element %s in JFormFieldGroupedList',
$element->getName()), 500);
JM
Andrew Eddie
> Would it be feasible to implement another solution where, globally in the
> framework, any absent string would be replaced by a hardcoded English
> phrase?
> As of now, it is only when a full ini file does not exist in a said
> language, that it loads the en-GB default ini.
> Something like
> throw new
> Exception(JTextErr::sprintf('JLIB_FORM_ERROR_FIELDS_GROUPEDLIST_ELEMENT_NAME',
> 'Unsupported element %s in JFormFieldGroupedList', $element->getName()),
> 500);
That's a good example of the types of errors we should not be translating :)
The thing we need to allow for is the developer to opt-in to
translation, not assume the developer needs it on by default (the
platform is used for much more than the CMS). So in that case if
would be more like this in the application:
// In the application now.
try
{
$cms->doSomthing();
}
catch (Exception $e)
{
// Uh oh. Platform has thrown an English exception.
// Wrap it in my application's language so the user can understand
something has gone wrong.
$cms->showErrorPage(JText::sprintf('JCOMMON_EXCEPTION', $e->getMessage()));
}
You can also trap different types of exceptions as well, but an
exception is throw if something really "bad" has happened, usually
meaning the developer or possible site administrator (database server
went down) has to fix it.
brian teeman
On Friday, 23 March 2012 07:26:58 UTC, Andrew Eddie wrote:
On 23 March 2012 17:21, JM Simonet <infog...@gmail.com> wrote:
> Let me be the non anglo-centric devil's advocate:
> I have not seen any discussion on this decision, i.e. questionning non
> native English-speaking developpers.
> Should all developpers in the world be fluent in English to understand
> errors?
> Or is this battle already lost?It's a fair question and I'm open to discussion about it. However,
the API is in English so if a developer can read English PHP then it's
fair to say they will be able to read English error messages that
relate directly to the code. That's my point of view anyway.
Andrew Eddie
"exceptions" here - that is, when an exception is thrown, it's
generally something the application cannot recover from (except that
the application might catch the exception and format it nicely in an
error page).
Where the application can recover from the error (raise a notice or a
warning), that's where we should consider running things through
JText.
Alternatively, the developer shouldn't be forced into making a
language file just to use the most basic aspects of the platform. It
all requires balance and I think we'll have to take each edge case as
it comes.
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers
piotr_cz
I suggest there is a new wiki page created on Github repository, or on
Joomla docs, listing:
- set of PHP exception types used in the framework (with short
description of use case as Andrew Eddie gave for
InvalidArgumentException, and example)
- Exception extensions, like JDatabaseException
This would help clarifying when to throw specific exception and
possibly help in generating fallbacks using JText if developer
decides.
Developers could make a fork of wiki for own language (have it open
during development if Exceptions are not translated).
What do you think?
On Mar 23, 8:52 am, Andrew Eddie <mambob...@gmail.com> wrote:
>
> > Would it be feasible to implement another solution where, globally in the
> > framework, any absent string would be replaced by a hardcoded English
> > phrase?
> > As of now, it is only when a full ini file does not exist in a said
> > language, that it loads the en-GB default ini.
> > Something like
> > throw new
> > 500);
>
> That's a good example of the types of errors we should not be translating :)
>
> The thing we need to allow for is the developer to opt-in to
> translation, not assume the developer needs it on by default (the
> platform is used for much more than the CMS). So in that case if
> would be more like this in the application:
>
> // In the application now.
> try
> {
> $cms->doSomthing();}
>
> catch (Exception $e)
> {
> // Uh oh. Platform has thrown an English exception.
> // Wrap it in my application's language so the user can understand
> something has gone wrong.
> $cms->showErrorPage(JText::sprintf('JCOMMON_EXCEPTION', $e->getMessage()));
>
> }
>
> You can also trap different types of exceptions as well, but an
> exception is throw if something really "bad" has happened, usually
> meaning the developer or possible site administrator (database server
> went down) has to fix it.
>
> Regards,
Amy Stephen
I agree with your comments. It will be important to uncouple JText from platform subsystems.
One idea is to use the numeric code portion of the Exception in addition to the English message. I think that might be a useful key for downstream users to use in their translation systems. So, instead of displaying the message, the code could be retrieved, used to get the translation, and then that message could be displayed.
The downside is that this approach will take work organizing numeric ranges by package and then developing processes to ensure each error/code combination is documented to ensure uniqueness. A nice side benefit is a definitive list of codes and errors that could be published.
If that works for exceptions, we should be able to extend that type of approach with the other messages.
The piece that has me completely stumped is sprintf. If we can move away from using it and simplify the error messages, then good. Otherwise, I'm just not sure what we would do with translations.
Amy Stephen
piotr_cz
docs.joomla.org / GitHub wiki?
As far as I can tell there isn't any Joomla Platform related section
on docs. I'll create a Github wiki page then and we may move it later.
Chris Davenport
A great deal of the material there is actually relevant to the Platform, but as yet hasn't been re-organised to reflect to separation of the Platform from the CMS. Feel free to add whatever pages you need.
Chris.
Chris Davenport
Joomla Leadership Team - Production Working Group
Joomla Documentation Coordinator
Andrew Eddie
> The only question is:
> docs.joomla.org / GitHub wiki?
>
> As far as I can tell there isn't any Joomla Platform related section
> on docs. I'll create a Github wiki page then and we may move it later.
Had this created for a while and forgot about it.
https://github.com/joomla/joomla-platform/pull/1029/files
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers
Andrew Eddie
> The main entry point for developer documentation is here:
> http://docs.joomla.org/Developers
Well, that's where I probably (respectfully) disagree with you ;) I'd
like to see the main entry point for developer documentation for the
Platform to be here:
http://developer.joomla.org/platform-manual.html
and here:
http://developer.joomla.org/coding-standards.html
Personally I'd love to see the CMS follow in the same direction, but
that's not my call.
> A great deal of the material there is actually relevant to the Platform, but
> as yet hasn't been re-organised to reflect to separation of the Platform
> from the CMS. Feel free to add whatever pages you need.
My personal feelings are that people can collaborate on documentation
wherever they want (wiki, google docs, github), but my preference for
organising that information into the definitive source is adding it to
the docs tree in the platform itself:
https://github.com/joomla/joomla-platform/tree/staging/docs
I'm more than happy to help people add material to those documents if
that's what they ant to do because I feel strongly that we should have
a top quality, *community built* and *free* Platform developer manual.
I also respect that people might want to add stuff to the wiki, and
that's completely ok, it's just not something I'm passionate about :)
My vision for the Platform Manual is that it's a solid teaching
resource that walks you through how to set the platform up and then
how to use it.
The introduction for setup is enough for now but improvements are welcome.
The next major section I see, and it is already there, is the
developer's reference to the core packages, and this is basically the
companion to the API docs. If the API docs tell you "what" the
platform does, then this section of the developer manual explains the
"how to" of wiring it all up and giving you some examples of how to do
that (it's one thing to know what classes exists, it's another matter
to know how to use them effectively).
The next major section after that, which hasn't been started (because
it's just in my head) is a suite of tutorials and/or strategies for
implementing platform applications. It might include advice on how to
set up a CLI app, a pure Web App, how to create a Web Services API,
etc and so on. It might also be tightly linked to example
repositories on github that form the definitive guide to boilerplate
application starters that you just clone as a start to your own
platform application project.
Testing is started but needs bulking out with strategies for writing
different types of tests, etc.
The Appendix can be the dumping ground for anything that doesn't fit.
Anyway, we are off topic but that's where my heart is on the matter.
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers
Andrew Eddie
> One idea is to use the numeric code portion of the Exception in addition to
> the English message. I think that might be a useful key for downstream users
> to use in their translation systems. So, instead of displaying the message,
> the code could be retrieved, used to get the translation, and then that
> message could be displayed.
>
> The downside is that this approach will take work organizing numeric ranges
> by package and then developing processes to ensure each error/code
> combination is documented to ensure uniqueness. A nice side benefit is a
> definitive list of codes and errors that could be published.
If someone wants to propose a code system and maintain it, I won't
stop them. However, let's see what we can do with exception types
first. My biggest fear is that codes are a *big* overhead and unless
it's drop dead easy for a contributor to know what code to use, and
then for we poor maintainers to double check, it won't get off the
ground.
> The piece that has me completely stumped is sprintf. If we can move away
> from using it and simplify the error messages, then good. Otherwise, I'm
> just not sure what we would do with translations.
There's no secret behind it. I use sprintf instead of using string
concatenation. It makes the code more readable. Nothing more,
nothing less.
Amy Stephen
On 24 March 2012 00:30, Amy Stephen <amyst...@gmail.com> wrote:
> One idea is to use the numeric code portion of the Exception in addition to
> the English message. I think that might be a useful key for downstream users
> to use in their translation systems. So, instead of displaying the message,
> the code could be retrieved, used to get the translation, and then that
> message could be displayed.
>
> The downside is that this approach will take work organizing numeric ranges
> by package and then developing processes to ensure each error/code
> combination is documented to ensure uniqueness. A nice side benefit is a
> definitive list of codes and errors that could be published.
If someone wants to propose a code system and maintain it, I won't
stop them.
I think that's the trick - finding something maintainable. (automated or being able to add a codesniff would be important.)
However, let's see what we can do with exception types
first.
Very good. I'll get started then with the response you gave me above.
My biggest fear is that codes are a *big* overhead and unless
it's drop dead easy for a contributor to know what code to use, and
then for we poor maintainers to double check, it won't get off the
ground.
I do not disagree. I'll give it some thought.
> The piece that has me completely stumped is sprintf. If we can move away
> from using it and simplify the error messages, then good. Otherwise, I'm
> just not sure what we would do with translations.
There's no secret behind it. I use sprintf instead of using string
concatenation. It makes the code more readable. Nothing more,
nothing less.
Absolutely. What I meant was - while it is possible to associate a numeric code with a specific message, what is not possible is to do the same with a message that results from a sprintf statement. (That message could be a number of different values when sprintf is done with it.)
Regardless, that idea is back burner-ed and I will get started given your response above.
Thanks.
CirTap
>
> I think that's the trick - finding something maintainable. (automated or
> being able to add a codesniff would be important.)
>
Just a thought...
When PEAR introduced PEAR_Exception() to PHP4 <sigh>, at some point I
used crc32(__METHOD__) as a "error code" base to allow message translations.
Long, ugly numbers :)
throw new Exception('English message', crc32(__METHOD__));
Obviously this only gives one code per method, which might be sufficient
for most occasions -- at that time "Frameworks" were rather small ;)
IF the code should pass a translation process and more variations "per
method" are needed, a unique keyword per method throwing the Exception
can be invented and added into the mix:
throw new Exception('English message 1', crc32(__METHOD__.'BAD1'));
throw new Exception('English message 2', crc32(__METHOD__.'BAD2'));
Creating a list of "major codes" per class method is easy.
Supplemental keywords might follow a fixed taxonomy, i.e. 'arg',
'param', 'type', you name it.
Mixing this with the various Exception classes however could do the job.
Have fun,
CirTap
Chris Davenport
If contributors to the developer documentation prefer to use git + DocBook that's fine, although in my experience most will find it easier to add material using the wiki. But there is no reason material can't be re-used in different places and in different formats. Indeed, the existence of various tools to take MediaWiki output and push it through lots of different toolchains for generating DocBook XML, Latex, PDF and so on, was one of the reasons we moved to MediaWiki. Think of the wiki as a repository of documentation fragments that can be re-used in lots of different ways, including assembly into fully edited, downloadable, discrete manuals. That was always the vision.
There is much in the wiki that could usefully be incorporated into the Platform Manual, so if anyone wants to select the relevant parts and copy them over, I would encourage that. There are lots of other ways to re-use wiki content too.
So I think the only point we disagree on is where we are right now. I look forward to being able to say to people that the definite reference is the Platform Manual, but I don't think we're there yet. Which reminds me that there really should be a link from the wiki to the Platform Manual. Someone care to add that?
Chris.
Amy Stephen
I agree with Andrew exceptions really don't need to be translated and that the first order of business is to focus there. So, no immediate worries.
+++
In a sense, there really isn't an issue since the downstream user can use the message as the translation key. So, even if that's not the preference, it's still an option. (Setting aside the sprintf issue for now.)
+++
Also, we might want to think a bit about how phpMailer does it. They have an array of keys and messages at the class level. That'd be overwhelming to do for each and every class - but maybe a standard class for each package? (Just started thinking on that.)
Short codes and longer messages:
https://github.com/joomla/joomla-platform/blob/staging/libraries/phpmailer/phpmailer.php#L937
+++
So, we've got a few ideas. Little time and sharing ideas will help. And again, already downstream users could take those messages and use those as their translation keys, so in the end there is already a solution for those who must have it in their systems.
Andrew Eddie
I might continue this discussion in a separate thread.
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers
Rob Schley
Sam Moffatt
http://docs.joomla.org/Errors
There are a few places, hardly dominant but as you point out, really
just requires people to actually bother to do it and most people
aren't bothering to do it.
Cheers,
Sam Moffatt
http://pasamio.id.au
Chris Davenport
An alternative to having a pre-defined set of error codes is to have the codes automatically generated based on say, class name, method name, exception type, version number, etc. If the error message that is shown to the user includes a link which includes this error code then we could very easily write a platform application running on, say, errors.joomla.org which would count the number of people clicking on that link. A bit like "liking" something; this would be like having a "hate" button for the error message. The application could also allow people to add comments about the error (suitably moderated of course), so that explanations of what might have caused the error, how to fix it, workarounds, etc., could be added over time. Kind of a "social error handling" application, we could have a page of "most hated" errors. This might even guide developers towards areas of the code that need more attention. Could be a good GSoC project.
Just a thought.
Chris.
brian teeman
On Saturday, 24 March 2012 11:37:37 UTC, Chris Davenport wrote:
Yes, and building on that I've always thought that it would be good to be able to include a link to the documentation page as part of the standard error message that gets displayed to the user. Something along the lines of "Click here for more information about this error". Probably of more relevance to the CMS than the Platform though.
An alternative to having a pre-defined set of error codes is to have the codes automatically generated based on say, class name, method name, exception type, version number, etc. If the error message that is shown to the user includes a link which includes this error code then we could very easily write a platform application running on, say, errors.joomla.org which would count the number of people clicking on that link. A bit like "liking" something; this would be like having a "hate" button for the error message. The application could also allow people to add comments about the error (suitably moderated of course), so that explanations of what might have caused the error, how to fix it, workarounds, etc., could be added over time. Kind of a "social error handling" application, we could have a page of "most hated" errors. This might even guide developers towards areas of the code that need more attention. Could be a good GSoC project.
CirTap
> just requires people to actually bother to do it and most people
> aren't bothering to do it.
... or maybe all of this just gets lost in the shuffle like this very
nice list of yours?
Heavens, it's from *2009* !?? I have never seen it before...
Well hidden in alphabetical order. ;)
It should have an page "Error Codes" redirecting to it -- or vice versa
-- and it doesn't even show up if you search for that term in the Wiki.
Mind if I fix this?
So maybe "people don't bother" because they just don't know/find what
they're looking for?
If I may add my 2ct: with the gazillion places and sites and mailing
lists all kind of people throw all kind of information into, it's darn
hard for "Dev Average" to keep up, let alone read it.
Have fun,
CirTap
Chris Davenport
On Saturday, 24 March 2012 11:37:37 UTC, Chris Davenport wrote:Yes, and building on that I've always thought that it would be good to be able to include a link to the documentation page as part of the standard error message that gets displayed to the user. Something along the lines of "Click here for more information about this error". Probably of more relevance to the CMS than the Platform though.
Would be great but I'm not sure how it would work well in the non-english speaking world
Same mechanism that the help screens use. Part of the generated URL can be a language code with the whole structure of the URL defined in an XML file that can also be language-specific.
Chris.
Amy Stephen
brian teeman
On Saturday, 24 March 2012 13:20:22 UTC, Chris Davenport wrote:
Hi Brian,On 24 March 2012 12:07, brian teeman <joom...@googlemail.com> wrote:
On Saturday, 24 March 2012 11:37:37 UTC, Chris Davenport wrote:Yes, and building on that I've always thought that it would be good to be able to include a link to the documentation page as part of the standard error message that gets displayed to the user. Something along the lines of "Click here for more information about this error". Probably of more relevance to the CMS than the Platform though.
Would be great but I'm not sure how it would work well in the non-english speaking world
Same mechanism that the help screens use. Part of the generated URL can be a language code with the whole structure of the URL defined in an XML file that can also be language-specific.
Chris.
Andrew Eddie
> An alternative to having a pre-defined set of error codes is to have the
> codes automatically generated based on say, class name, method name,
> exception type, version number, etc.
That sounds more like an error "signature" than an error code. That
could easily be generated from a backtrace in the exception catcher
(something done at the application level).
Let me ask a basic question which doesn't seem to be addressed. Why
do I want to use codes in the first place?
Amy Stephen
The benefit to the codes is primarily to get a key for translations.
Hope to have it ready to share soon.
Chris Davenport
Thinking about it, I don't think a signature is such a good idea. A better idea would be to construct a URI which contains slugs for the key data points: class name, method name, exception type, version number. The error processing application could then decode the URI, making it easier to search for error information along these different dimensions.
Chris.
Emerson da Rocha Luiz
+55 51 9881-9146 | MSN: emerson at webdesign.eng.br | GTalk: fititnt at Gmail | Skype: fititnt | http://www.fititnt.org | Twitter: @fititnt
Amy Stephen
I used the Crypt class to see how idea might work. I like this approach, I think it might work.
- It will increase quality due to the inclusion of unit tests for exceptions and messages.
- The unit tests should satisfy Andrew's requirement that verification be easy for maintainers to oversee.
- Translation files could be easily generated by downstream users given both code/English messages.
- The approach organizes and consolidates system messages and codes whereas today this information is embedded within the source code and (nearly) impossible to pull together without significant time.
- Data is accessible, not only to downstream clients but also, but as Chris points out -- system codes/messages can be extracted via the API and then used in other ways, such as the wiki or Docbook.
I'll try to overview some of the elements and findings.
1. Message Class
https://github.com/AmyStephen/joomla-platform/blob/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4/libraries/joomla/crypt/message.php
- proposing one class per package (stored in the root of package)
- serves as a collection for all message and code combinations for the package
- proposed numbering scheme (bottom of email) per package similar to Sam's approach earlier
https://github.com/AmyStephen/joomla-platform/blob/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4/libraries/joomla/crypt/message.php#L42
- get method retrieves:
a) all messages;
b) specific message by code;
c) or returns a default 'message not found' for unidentified codes
- getCode allows retrieval of the message, given the code.
https://github.com/AmyStephen/joomla-platform/blob/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4/libraries/joomla/crypt/message.php#L41
Usage:
throw new InvalidArgumentException(JCryptMessage::get(300400), 300400);https://github.com/AmyStephen/joomla-platform/commit/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4#L1L70Returns both the English message and the code.
2. Unit Testing
One of Andrew's criterion was that the solution is easy for maintainers to verify. Requiring a unit test for any Exceptions and log message should satisfy that need (and ensure the logic is accurate and useful).
After prototyping out some tests, (not Unit Tests yet -- just a script you can run from the root of your repository):
https://github.com/AmyStephen/joomla-platform/blob/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4/test.php
What the test found were a few bugs in the exception processing. (Which is exactly what we want from unit testing. Point being -- this is not wasted time - it's necessary and helpful work.)
Examples of bugs:
1. Code that will never be executed.
Could be wrong on these -- so if you disagree, please help me understand how to test these.
Magic method will not be accessed without $this->type == 'type'
https://github.com/AmyStephen/joomla-platform/commit/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4#L3L59
Fatal error because of protected type.
In order for this exception to be thrown, one would have to instantiate the class, create the key for another encryption class, then pass that key into this class.
If you do that, a fatal error results because the $this->type defined in JCrypt is protected (and not accessible here.)
https://github.com/AmyStephen/joomla-platform/commit/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4#L1L70
So, this change is needed to get a good exception
https://github.com/AmyStephen/joomla-platform/commit/bfcbf25c1d7d3bd5f6212276a6fc71f5e687ace4#L3L36
3. Code ranges
broad numeric ranges, new packages can be inserted, thus retaining numeric and alphabetic ordering (although that should not be a concern)
10000 - Access
50000 - Application
100000 - Archive
150000 - Base
200000 - Cache
250000 - Client
300000 - Crypt
350000 - Database
400000 - Document
450000 - Environment
500000 - Event
550000 - Filesystem
600000 - Filter
650000 - Form
700000 - Github
750000 - HTML
800000 - HTTP
850000 - Image
900000 - Input
950000 - Installer
1000000 - Language
1050000 - Log
1100000 - Mail
1150000 - Object
1200000 - Plugin
1250000 - Profiler
1300000 - Registry
1350000 - Session
1400000 - String
1450000 - Table
1500000 - Updater
1550000 - User
1600000 - Utilities
Hannes Papenberg
I don't see any benefit in hiding the error meesages in our program code behind a numeric code. Standardizing on error messages is great, but making me memorize dozens of error code ranges simply to know which area of the code is effected instead of simply writing JAccess::set() is stupid. And then I don't even know what the issue is.
The error code does not only have to be understandable in the output, but also in the actual code. I don't want to have to jump between source files simply to look up the error message.
Hannes
Amy Stephen
The error message itself is for the requesting process.
On Thursday, March 22, 2012 9:53:42 PM UTC-5, Amy Stephen wrote:
Before I get started on continuing Andrew's work with JText https://github.com/eddieajau/joomla-platform/commit/48d20ffae01d18a3df05b4399769ffac67d58c87, I wanted to ask a couple of questions.
First - will we replace all JText messages? (Meaning beyond exceptions, so including JLog statements?)
Second - should we keep track of the language strings removed for a later patch so that those values can then be removed from the CMS language files?
Third - if it is still important to translate the JLog statements, can we add JText in the JLog class -- so that the JText dependency can be removed throughout the framework? (Personally, I think uncoupling the translation class would be helpful.)
Finally - I'd like to do a subsystem at a time to keep the work units small and easy to adapt. (That should also make it easy for others who might be looking for small, easy jobs to do to get started with the platform). I can see you are selecting an SPL Exception that is a better fit for the exception. I am not familiar with these categorizations yet and I don't have a feel for how you might be looking at this, so I am certain you'll have feedback on my choices -- keeping the scope narrow will help. I assume this is the list from which to choose? http://www.php.net/manual/en/spl.exceptions.php
Thanks.
Hannes Papenberg
get a quick grasp of what the issue is than to read the code.
Example:
if (!$done)
{
$this->setError(JText::_('JLIB_APPLICATION_ERROR_INSUFFICIENT_BATCH_INFORMATION'));
return false;
}
This is from JModelAdmin::batch(). $done is set in 4 places in that
method. What went wrong?
Yes, maybe we wouldn't replace this error message, but stating that we
don't need properly readable code is like saying we don't need comments
and docblocks in the code, because the code is oh-so-simple to read.
Small reminder: As far as I know, we currently have at least 3 different
ways of throwing errors. We are now in the process of introducing a
fourth standard. maybe we should clean up the other three before we
start adding more.
Hannes
Am 25.03.2012 11:18, schrieb Amy Stephen:
> To be honest, Hannes, if you have to read the error message to
> determine what the code is testing and then finding to be a problem,
> the code needs to be simplified.
>
> The error message itself is for the requesting process.
>
> On Thursday, March 22, 2012 9:53:42 PM UTC-5, Amy Stephen wrote:
>
> Before I get started on continuing Andrew's work with JText
> https://github.com/eddieajau/ joomla-platform/commit/
> 48d20ffae01d18a3df05b4399769ff ac67d58c87
> <https://github.com/eddieajau/joomla-platform/commit/48d20ffae01d18a3df05b4399769ffac67d58c87>,
> I wanted to ask a couple of questions.
>
> First - will we replace all JText messages? (Meaning beyond
> exceptions, so including JLog statements?)
>
> Second - should we keep track of the language strings removed for
> a later patch so that those values can then be removed from the
> CMS language files?
>
> Third - if it is still important to translate the JLog statements,
> can we add JText in the JLog class -- so that the JText dependency
> can be removed throughout the framework? (Personally, I think
> uncoupling the translation class would be helpful.)
>
> Finally - I'd like to do a subsystem at a time to keep the work
> units small and easy to adapt. (That should also make it easy for
> others who might be looking for small, easy jobs to do to get
> started with the platform). I can see you are selecting an SPL
> Exception that is a better fit for the exception. I am not
> familiar with these categorizations yet and I don't have a feel
> for how you might be looking at this, so I am certain you'll have
> feedback on my choices -- keeping the scope narrow will help. I
> assume this is the list from which to choose?
> http://www.php.net/manual/en/ spl.exceptions.php
> <http://www.php.net/manual/en/spl.exceptions.php>
>
> Thanks.
>
Amy Stephen
Totally agree!!! I'm not a big fan of using "flags" to track the application activity -- to me that says the code is too complex. And, if a flag must be used, "$done" says nothing to me.
Having said that, I disagree with the notion that adding more words to confusing code clears things up. It's been my experience that good code documents itself. Long ago I realized that relying on comments or display messages to work out the logic is ill advised.
And, to be fair, your examples are not in the prototype. Here are the two types of exceptions in the prototype examples. Are either of these confusing? In either of these cases, do the messages add or detract from understanding what the code is doing?
Check 1: Is the PHP module "mcrypt" available?
if (!is_callable('mcrypt_encrypt')){throw new RuntimeException('The mcrypt extension is not available.');}
New:
if (!is_callable('mcrypt_encrypt'))
{
throw new RuntimeException(JCryptMessage::get(300200), 300200);
}
Check 2: Is the keytype valid?
if ($key->type != $this->keyType)
{
throw new InvalidArgumentException('Invalid key of type: ' . $key->type . '. Expected ' . $this->keyType . '.');
}
After:
if ($key->type != $this->keyType)
{
throw new InvalidArgumentException(JCryptMessage::get(300300), 300300);
}
One of my favorite A List Apart quotes: "Good design is iterative, the result of removing the unnecessary until on the real value remains." http://www.alistapart.com/articles/standanddeliver/
As I look through Joomla's massive code base, it's obvious to me that the newer code written today is lean, simple, elegant, easy to understand. This approach continues those good directions by removing the extraneous data and centralizing messages/codes where it has more value, better access.
Now, if the overall concern is that the message should be displayed in the code, we can implant the English message and invoke the getCode method to return the code. (don't recommend it but it's an option.)
Hannes - other than the code issue, what is your thinking on using an approach like this to enable the creation of keys for translations, extractable messages/codes, tested exception logic, and a verifiable approach for maintainers? Do you have other ideas on how we might solve this problem?
Appreciate your feedback, thanks much.
Amy Stephen
Just to make certain you understand, I'm just fine with going with your original idea, keep it simple, get JText out of the Exception handling. That's the only big need I have -- getting the packages better separated.
So, if you want time to consider a better solution (or if you simply think one isn't needed), I'm more than happy to do less work. No reason not to get started and let people share prototypes, etc., at leisure.
Don't feel I'm pushing this, I'm not. Just proposed something I thought might help some of the other concerns. I like this idea for Molajo - but my main goal is to help with separation. That is what helps me the most (and the motivation for my involvement since my time is limited, too.)
Thanks.
On Thursday, March 22, 2012 10:24:19 PM UTC-5, Andrew Eddie wrote:
On 23 March 2012 12:53, Amy Stephen <amyst...@gmail.com> wrote:
> Before I get started on continuing Andrew's work with JText
> https://github.com/eddieajau/joomla-platform/commit/48d20ffae01d18a3df05b4399769ffac67d58c87,
> I wanted to ask a couple of questions.
>
> First - will we replace all JText messages? (Meaning beyond exceptions, so
> including JLog statements?)
Let's start with thrown exceptions and see how it goes. This is going
to be an iterative process and it's probably best to start small and
progress slowly.
> Second - should we keep track of the language strings removed for a later
> patch so that those values can then be removed from the CMS language files?
I think it should be a simple matter for someone to devise a grep for
the CMS on JLIB_* strings, and then just do a diff on a sorted list of
existing and found strings. I haven't been keeping track myself.
Long term we probably won't have any platform classes using JText for
messages.
> Third - if it is still important to translate the JLog statements, can we
> add JText in the JLog class -- so that the JText dependency can be removed
> throughout the framework? (Personally, I think uncoupling the translation
> class would be helpful.)
I think translation of the messages, if required, happens outside of
JLog. JLog should just process the message it's given and shouldn't
have any coupling to the translation system, even by composition.
> Finally - I'd like to do a subsystem at a time to keep the work units small
> and easy to adapt. (That should also make it easy for others who might be
> looking for small, easy jobs to do to get started with the platform).
Agree.
> I can
> see you are selecting an SPL Exception that is a better fit for the
> exception. I am not familiar with these categorizations yet and I don't have
> a feel for how you might be looking at this, so I am certain you'll have
> feedback on my choices -- keeping the scope narrow will help. I assume this
> is the list from which to choose?
> http://www.php.net/manual/en/spl.exceptions.php
If in doubt, it's probably going to be a RuntimeException.
If you are checking an argument sent to a function or method, and it
fails a condition, I usually throw an InvalidArgumentException with
the name of the method called. 99.% of the time these are problems
the developer has to fix so getting a terse programmer-centric message
is not a problem. Eg:throw new InvalidArgumentException(sprintf('%s::foo(*%s*)',
get_class($type), gettype($foo));There's no need to embellish the message with "has an invalid
argument" because it's implied by the exception type.While in a method, if you get an unexpected result from calling some
other API, like an array is empty when it shouldn't be, I usually
throw an UnexpectedValueException, e.g.:$things = $this->getThings();
if (empty($things)
{
throw new InvalidArgumentException(sprintf('getThings in %s::foo()
returned an empty array', get_class($type));
}It's a bit harder to know how to craft this message succinctly. We
need enough information for the developer to have a clue where to go
looking if they get a report of that exception being thrown.Let's try and nail the easy ones first.
The other thing that can be done is a sweep of the checks on if
($db->getErrorMsg()). Those can all be removed now because the DB
drivers will throw exceptions and never get to that code.Also, I still haven't had time to follow up on the "return
JError::raise*" case yet.Regards,
Andrew Eddie
Andrew Eddie
> Andrew -
>
> Just to make certain you understand, I'm just fine with going with your
> original idea, keep it simple, get JText out of the Exception handling.
> That's the only big need I have -- getting the packages better separated.
Not withstanding the fact that I appreciate you and others going
deeper into the subject, I think let's keep it simple for now and at
least get everything standardised and consistent. So for now the two
easy wins are:
1. Removing JText from thrown exceptions.
2. Removing the checks on $db->getErrorNum() in code.
We've only got a couple of weeks till 12.1 ships and it would be good
to have these cleaned up.
Amy Stephen
CirTap
First of all, I'm really stunned about why there seems to be a need to
"sell" the benefits of having a (unique) error code associated with a
thrown Exception?
This isn't an entirely new or revolutionary concept to the software
world either, and incidently, the 2nd argument for the Exception class
accepts just that: an error code.
I may as well missed some essential sidenote in this thread and it's all
about how those codes ought to look like and where they come from.
I hereby also "withdraw" that crc32() idea :) It's indeed too
signature'ish. I looked into my yelde "Nemesis" package and it too used
plain numeric ranges as can be found in Sam's proposal(?) on the wiki.
The checksum was added occasionally on top but that "trick" kinda stuck
with me.
However, in reply to Hannes:
Am 25.03.2012 12:57, schrieb Hannes Papenberg:
> And for me to be honest, its still easier to read the error message to
> get a quick grasp of what the issue is than to read the code.
AFAIK nobody here has asked for removing the error messages, but to
_add_ a supplemental (unique) numerical code when throwing an Exception.
> Small reminder: As far as I know, we currently have at least 3
> different
> ways of throwing errors. We are now in the process of introducing a
> fourth standard. maybe we should clean up the other three before we
> start adding more.
I don't consider this a "fourth standard" at all, but a valuable
extension to the "latest" standard of throwing Expections that's also
easy to apply.
Even JError has a notion of error codes, but that feature was never (or
barely) used or the code was a generic placeholder.
> if (!$done)
> {
>
$this->setError(JText::_('JLIB_APPLICATION_ERROR_INSUFFICIENT_BATCH_INFORMATION'));
> return false;
> }
>
> This is from JModelAdmin::batch(). $done is set in 4 places in that
> method. What went wrong?
>
Good question!
You might ask the person who wrote this so s/he can answer you.
In this case I'd be less concerned with the use of the flag $done, but
what setError() will forward to the user. The first one is a debatable
coding style, the latter a useability failure, imho.
In this case however, I'd blame the limitations imposed by PHP4 that
probably lead to the design of this "error handling solution" for J!1.5
(or even 1.1?) that still sticks.
As a consequence of the old technical limitation, it's also a perfect
example of an utterly useless error message users have to face on a
regular basis: "Why was it insufficient, and what in the world do you
want me to do to make it work?"
There's nothing "unexpected" happening here (hence no Exception) and
despite the fact that the code that triggers that error perfectly KNOWS
exactly what additional data is needed, it can only pass a string to the
outside world.
What bothers me more is also the fact that currently, no matter if error
occurs or not, the whole whooping pack of INI strings is loaded
unconditionally only to support this kind of solution.
So I'm curious about Amy's prototype :-)
Have fun,
CirTap
Andrew Eddie
>
> First of all, I'm really stunned about why there seems to be a need to
> "sell" the benefits of having a (unique) error code associated with a
> thrown Exception?
Actually that depends on your assumptions (and why I asked the
question why do you want an error code - that was not a brush off
statement, I wanted to know what people thought they wanted them for).
Do you want a unique code for every unique message, or every line on
which a throw is made even if the message is the same, or do you want
a code that characterises the type of exception, or do you want to
pass back some third-party error code like from a database?
Whatever the case, working out what error codes should be is separate
from decoupling exceptions from JText, and that's one job I would like
complete before 12.1 ships. It's probably best to start a different
thread altogether on error codes.
And yes, a lot of the garbage we had to deal with was from PHP 4.
Phil Brown
I find that using a number is meaningless, requires lookups on some documented site somewhere and adds to complexity.
Working on pre-existing projects that had errors raised with numbers simply caused myself a lot of wasted time. Searching the project then looking at the code when a simple FileNotFoundException with a message of the file path would of given a much cleaner indication from the get go.
eg.
FileNotFoundException("Path to file");
catch (FileNotFoundException
instead of:
Exception("File Not Found: it is located here", 3450);
By using extended exceptions I can
- Determine what the error is about even when there is no text present.
- Allow me to do a direct catch of that type of exception and handle it in its own block instead of having to do numeric equalisation checks in a single block.
- Use a more OOBish method of error handling.
- Still decide to display a different message to a user and log a more detailed one if I wish.
- And probably others if I wasnt so tired.
Just my 2c.
Phill Brown
M 04 2481 9754
Bathurst Software Solutions
-------------------------------------------------------------------------------------------------------------------
garyamort
On Sunday, March 25, 2012 11:32:40 AM UTC-4, Amy Stephen wrote:
Hannes --
Totally agree!!! I'm not a big fan of using "flags" to track the application activity -- to me that says the code is too complex. And, if a flag must be used, "$done" says nothing to me.
Having said that, I disagree with the notion that adding more words to confusing code clears things up. It's been my experience that good code documents itself. Long ago I realized that relying on comments or display messages to work out the logic is ill advised.
And, to be fair, your examples are not in the prototype. Here are the two types of exceptions in the prototype examples. Are either of these confusing? In either of these cases, do the messages add or detract from understanding what the code is doing?
Check 1: Is the PHP module "mcrypt" available?if (!is_callable('mcrypt_encrypt')){throw new RuntimeException('The mcrypt extension is not available.');}
New:
if (!is_callable('mcrypt_encrypt'))
{
throw new RuntimeException(JCryptMessage::get(300200), 300200);
}
Amy Stephen
On Monday, March 26, 2012 2:03:59 AM UTC-5, Andrew Eddie wrote:
Whatever the case, working out what error codes should be is separate
from decoupling exceptions from JText, and that's one job I would like
complete before 12.1 ships. It's probably best to start a different
thread altogether on error codes.
If I understand the mission, correctly, in less than two weeks, our goal is three parts:
1. Remove JText from Exception handling
Instead, replace it with English text and (possibly) fine tune the SPL exception selected.
Example from Andrew's work on a recent PR: https://github.com/eddieajau/joomla-platform/commit/ 48d20ffae01d18a3df05b4399769ffac67d58c87
2. Remove $db->getErrorMsg since the DB drives now throw exceptions and that code is no longer reachable.
This will require a little thinking about how best to handle these. In cases where there is further processing, it will be important to add a catch for the exception and then pass it on to the calling process and still exit the method. In other cases, you might be able to simply remove the check.
if ($db->getErrorNum())
{
JLog::add(JText::sprintf('JLIB_APPLICATION_ERROR_MODULE_LOAD', $db->getErrorMsg()), JLog::WARNING, 'jerror');
return $clean;
}
3. Figure out how to handle the "return JError::raise" cases
For now, we need more direction from Andrew on this (or for someone to think about these and propose solutions.)
If you can help, THANKS, I created a spreadsheet that we can use to claim a package, one at a time, so that others know not to work in that area. Just add your name beneath the Assignment column. When you create your PR, please update the PR Link column.
https://docs.google.com/spreadsheet/ccc?key=0Ai_cbqlzUiyddGlXRDg5XzVacFZNbi1kUV9XOUl4b1E#gid=0
The following are comments from Andrew related to how we can make our first "best guess" on what SPL Exception http://www.php.net/manual/en/spl.exceptions.php to use:
<Andrew's quote from above>
if in doubt, it's probably going to be a RuntimeException.
If you are checking an argument sent to a function or method, and it
fails a condition, I usually throw an InvalidArgumentException with
the name of the method called. 99.% of the time these are problems
the developer has to fix so getting a terse programmer-centric message
is not a problem. Eg:
throw new InvalidArgumentException(sprintf('%s::foo(*%s*)',
get_class($type), gettype($foo));
There's no need to embellish the message with "has an invalid
argument" because it's implied by the exception type.
While in a method, if you get an unexpected result from calling some
other API, like an array is empty when it shouldn't be, I usually
throw an UnexpectedValueException, e.g.:
$things = $this->getThings();
if (empty($things)
{
throw new InvalidArgumentException(sprintf('getThings in %s::foo()
returned an empty array', get_class($type));
}
It's a bit harder to know how to craft this message succinctly. We
need enough information for the developer to have a clue where to go
looking if they get a report of that exception being thrown.
</end quote>
BTW - I appreciate the great responses and thoughts on the messages and code discussion. I apologize I won't be responding to any comments directed to me on that topic at this time so that I can focus on this. I have severely limited time ATM and I want to help get this task in before 12.1. Would most definitely welcome help, too. =)
Andrew Eddie
Amy Stephen
What do you want done with lines like this (many in JForm):
return new JException(JText::_('JLIB_FORM_ERROR_VALIDATE_FIELD'), -1, E_ERROR);
Is it okay to change these like this:
throw new RuntimeException('Invalid xml field', -1);
Thanks.
Amy Stephen
Amy Stephen
Rouven Weßling
Also, forgot to ask, are we going to skip the legacy folder? Or, do we need to make changes there, too?
Assuming we make no change to JObject until JError/JException are removed. ?
Amy Stephen
On 31.03.2012, at 04:03, Amy Stephen wrote:Also, forgot to ask, are we going to skip the legacy folder? Or, do we need to make changes there, too?
IMO yes, that stuff is either going to move to the CMS (where it won't be a platform responsibility anymore) or be removed completely. Either way I don't think we should do anything in there that causes B/C problems.
On 31.03.2012, at 22:33, Amy Stephen wrote:Assuming we make no change to JObject until JError/JException are removed. ?
What changes do you mean?
JObject methods getError, setError, and getErrors are (I believe) used with JException and JError exclusively.
Best regardsRouven
Amy Stephen
All platform subsystems have been processed, with changes committed or in the midst of the feedback process.
Three types of changes were made:
1. JText was removed from Exception (and JException) lines.
2. Wherever found, "plain" Exceptions were changed to SPL Exceptions.
3. All $db->getError Msg/Num logic was removed.
4. "return JError::raise" lines were changed to Exceptions.
As an FYI, I took on a big contract and beginning tomorrow, my time availability is going to decrease. I'll try to keep the PR's moving but I want to raise some concerns that I have and also that Rouven is making that might warrant discussion.
The changes in this pull request really aren't significant in that it's just changing messages or removing dead code. But, when the Exceptions were initially added, the API changed. While that is documented in the docblocks of the process that throws the exception, it's not always going to be obvious that an exception could be thrown given the chain of class/methods traveled. Since we simply removed the $db->errorETC blocks, there is, in many cases, no "hint" that the database might have thrown an exception.
Is there anyway to clarify this? Or, is this just one of those things that from now on, developers need to understand that the platform throws exceptions, it doesn't return false or the JError object anymore?
It's a good time to make this type of change since the CMS will likely take 12.1 for v 3.0. It's important that everyone understands "try/catch" blocks are going to be needed throughout the CMS (and by any downstream users) in place of $db->error and "false" returns. That also needs to be understood by extension developers.
I realize this is not new information to the platform team. I just raise the point that awareness is needed and that some thought might be given to documenting exceptions that are made "layers deep" within the framework so that the API for each method that might serve as the original call - has that hint available.
Overall, these are very good improvements and not even optional if you want to keep the codebase in sync with PHP. But, these are the type of changes that can be maddening since untrapped errors can be very difficult to debug.
piotr_cz
where can we find the source of the manual? I can't see it on GitHub
(joomla-platform/docs).
On Mar 27, 8:52 am, Andrew Eddie <mambob...@gmail.com> wrote:
> Notes on exception handling are now livehttp://developer.joomla.org/coding-standards.html
>
> Regards,