04: FINDing your Way Around

This is a temporary forum setup for the purpose of discussing the EMC standards
Locked
Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

04: FINDing your Way Around

Post by Nuttzy99 » Tue Sep 02, 2003 2:26 am

FINDing your Way Around

The FIND command is the most import of any command. By properly formatting FINDs your MOD will have a better chance of installing even if many MODs have already been installed.

The least you need to know:
  • Keep FINDs limited to their minimum uniqueness
  • Choose text that is likely to not be modified by other MODs
  • In lang files, search only for the $lang array keys and exclude the values
  • FIND once and operate many
  • FINDs are whitespace indifferent
[/b]
Uniqueness
Golden Rule #1: Keep FINDs limited to their minimum uniqueness. Rather than quoting entire blocks of core phpBB code letter for letter, isolate just those parts that make the line(s) unique. The more MODs that have been previously installed, the less likely you are to FIND an exact match for what you are seeking. Limiting to just the minimum uniqueness greatly increases the odds that you will have a successful FIND.

Instead of having a monstrousity like this....

Code: Select all

# 
#-----[ FIND ]------------------------------------------ 
# 
			$sql = "UPDATE " . USERS_TABLE . "
				SET " . $username_sql . $passwd_sql . "user_email = '" . str_replace("\'", "''", $email) ."', user_icq = '" . str_replace("\'", "''", $icq) . "', user_website = '" . str_replace("\'", "''", $website) . "', user_occ = '" . str_replace("\'", "''", $occupation) . "', user_from = '" . str_replace("\'", "''", $location) . "', user_interests = '" . str_replace("\'", "''", $interests) . "', user_sig = '" . str_replace("\'", "''", $signature) . "', user_sig_bbcode_uid = '$signature_bbcode_uid', user_viewemail = $viewemail, user_aim = '" . str_replace("\'", "''", str_replace(' ', '+', $aim)) . "', user_yim = '" . str_replace("\'", "''", $yim) . "', user_msnm = '" . str_replace("\'", "''", $msn) . "', user_attachsig = $attachsig, user_allowsmile = $allowsmilies, user_allowhtml = $allowhtml, user_allowbbcode = $allowbbcode, user_allow_viewonline = $allowviewonline, user_notify = $notifyreply, user_notify_pm = $notifypm, user_popup_pm = $popuppm, user_timezone = $user_timezone, user_dateformat = '" . str_replace("\'", "''", $user_dateformat) . "', user_lang = '" . str_replace("\'", "''", $user_lang) . "', user_style = $user_style, user_active = $user_active, user_actkey = '" . str_replace("\'", "''", $user_actkey) . "'" . $avatar_sql . "
				WHERE user_id = $user_id";
You could trim it down to this....

Code: Select all

# 
#-----[ FIND ]------------------------------------------ 
#
# NOTE: the origial text is like:
#	$sql = "UPDATE " . USERS_TABLE . "
#		SET " . $username_sql ... [ follow by much more ]
#		WHERE user_id = $user_id";
#
$sql = "UPDATE " . USERS_TABLE
user_sig_bbcode_uid = '$signature_bbcode_uid',
WHERE

Other Hints
There are a few things to optimize your FINDs. Choose text that is likely to not be modified by other MODs. As many lines as needed may appear in the FIND block. Any length of any portion of a line may be used, and it is not necessary to use the beginning of the line. When dealing with TPL files it is a good idea to key on the template variables (ie. {L_TITLE}) as these are less likely to be modified and are also likely to appear in non-subSilver TPL files.

A FIND must proceed an IN-LINE FIND (not immedaiately though), however it is not necessary that the IN-LINE FIND fragment be present in the FIND. The point is that the FIND need only focus on the unique elements that distinguish this block of lines from others and that IN-LINE FIND can be less specific, needing only to focus on what distingushes the fragment on this line.

Dealing with Languages
When performing FINDs in lang_ files, keep in mind that ALL languages are going to be updated. Although values will change from language to language the variable names stay the same in ALL language packs. Therefore search only for the $lang array keys like "$lang['Forum']" and not "$lang['Forum'] = 'Forum';". It is very unwise to rely on comment (such as // That's all folks! ) in language files as often the comments are also translated into other languages.

There is an exception to this though. The two FAQ files (lang_faq.php and lang_bbcode.php) have no $lang keys unlike the other lang files. Therefore while FINDs work fine in English (or the primary language setting), they have no chance of working in other lang files. Therefore EM will try to commensate by performing all ADD commands just before the closing ?> of the file. It will be impossible to act on any REPLACE or IN-LINE commands.


Order and FINDs
Much of how order plays a role in FINDs is covered at length in the Order! Order! section. I'll recap the highlights here though. It is intended that you will process a file sequentially and not try to FIND some lines previous to ones already found. FIND something once and only once, and perform as many commands on the FIND black as needed. Unfortunately this means a popular method for ordering command is no longer valid.

Lastly it is important to note that you may have consequtive FIND statements if this will help zero in on some lines that aren't particularly distinctive. For instance, if you need to find a specifc but undestinctive feature like a particular <BR> or a } (closing brace), you can have a FIND command that directs us close to the desired location, and then have a second FIND command containing just the <BR> or }. However, this method should be used as infrequently as possible and in fact all other options should be exhausted before trying it.

Whitespace in FINDs
Much of how whitespace plays a role in FINDs is covered at length in the I need (white)space! section. The FIND command is whitespace indifferent, meaning that the FIND command totally ignores leading and trailing whitepace and also whitespace lines. Since whitespace is ignored, be sure that your FIND is not depending on whitespace to be in a particular spot.

-Nuttzy :cool:
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 04: FINDing your Way Around

Post by Ptirhiik » Tue Sep 02, 2003 6:15 am

Does now the FIND process beeing a real FIND (except the trealing space) and not an in-line find ? Meaning the FIND statement as to start from the begining of the sentence ? (issues with tpl files and commented php lines).


Is it planed in the next phpBB version to included comment anchors in order to point spots being probably client for modifications ?

Has the tpl also being reviewed in order to have a normed presentation, letting a chance to have a greater compliancy on all style ?

(assuming the last two questions sadly won't find response for phpBB 2.0.x version).

Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

Re: 04: FINDing your Way Around

Post by Nuttzy99 » Tue Sep 02, 2003 2:25 pm

From Other Hints: "Any length of any portion of a line may be used, and it is not necessary to use the beginning of the line." Also the example show that the 2nd line is NOT using text from the beginning of the line.

As for working with the 2.2 Dev's that has not taken place. I'm not even sure if I would encourage comment anchors though. I can see the benefit to this easy enough, but there could be some concerns to artificially increasing the number of modifications to a particular part rather than letting them occur in a more natural dispersement. I will consider this though as the benefits are clear.

For TPL's I'm really not sure how this would work. Style Dev's can do whatever they like so long as they keep the template variable the same so there really is no way to deal with all the different changes that could take place. I assume there are still template variable? I've not looked at 2.2 yet. The best way to cope with this is to allow for EM to accept specifc modification code for certain styles (just like languages) so that Authors can write for the most popular styles if they choose to.

-Nuttzy :cool:
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

Re: 04: FINDing your Way Around

Post by Nuttzy99 » Tue Sep 02, 2003 5:56 pm

Note to self: forgot to comment on comments ;)

-Nuttzy :cool:
Last edited by Nuttzy99 on Tue Sep 02, 2003 6:02 pm, edited 1 time in total.
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 04: FINDing your Way Around

Post by Ptirhiik » Tue Sep 02, 2003 6:02 pm

So it is not an improvement of the FIND, but a lost : you are there considering a FIND statement is an in-line FIND statement, which occurs in a lost of signification of the FIND statement, and makes the presence of the both pretty useless, and there quite dangerous (inserting code where it isn't supposed to be, although the find is unique, without any warning from easymod).

This is a very important point : there you deny the right to mod author to add comments, which is at least a very bad idea. Only a single comment like :

Code: Select all

// here we added foo1 before original_foo in the where statement
which would be a quality comment regarding evolution of a board will be beaten with another installation of mod.

Please keep the FIND statement its original mean and purpose, the IN-LINE FIND is there in order to carry fragemented search. Think also a mod has to be installable at hand too...

Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

Re: 04: FINDing your Way Around

Post by Nuttzy99 » Tue Sep 02, 2003 6:11 pm

Ptirhiik wrote:So it is not an improvement of the FIND, but a lost : you are there considering a FIND statement is an in-line FIND statement, which occurs in a lost of signification of the FIND statement, and makes the presence of the both pretty useless, and there quite dangerous (inserting code where it isn't supposed to be, although the find is unique, without any warning from easymod).
I really think you are not grasping what is going on. Go read the other topic! This is not even close to how FIND works.

-Nuttzy :cool:

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 04: FINDing your Way Around

Post by Ptirhiik » Tue Sep 02, 2003 6:41 pm

Oh, I have readen all the topics with a particular attention 8) , and alos performed some samples at hand : here is one (taking place in functions.php) :
not unique stuff
// $is_auth = auth(AUTH_VIEW, AUTH_LIST_ALL, $userdata);
not unique stuff
$is_auth = auth(AUTH_VIEW, AUTH_LIST_ALL, $userdata);
not unique stuff
As you can see, a mod has been applied in order to activate the auth process in the jumpbox. Now another mod has to find :

Code: Select all

#---[ FIND ]-----------
	$is_auth = auth(AUTH_VIEW, AUTH_LIST_ALL, $userdata);
which is an unique statement (// is not present on the second line).

Using what you are describing from the FIND statement, there is no way to act on the good line, as FIND will perform an IN-LINE FIND, and will always go to the commented line, and not to the line mentioned in the FIND statement. This is due to the not considered start of the find statement. Other issues of the same kind occurs in tpls too, and not only with comments : if you are supposed to FIND :

Code: Select all

#---[ FIND ]----------
<tr><td class="row1">
and that somewhere else before in the tpl stands also :

Code: Select all

<table cellpadding="4" cellspacing="1" border="0" with="100%"><tr><td class="row1"><span class="gen">{SOME_VAR}</span></td></tr></table>
you are not supposed to apply the actions the find were sat to this second line, but only to the first mentioned. There, with the way you describe FIND statement, you will touch this line, although it is clearly not the one searched.

Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

Re: 04: FINDing your Way Around

Post by Nuttzy99 » Tue Sep 02, 2003 6:57 pm

Comments like you are suggesting will not be allowed. Yes, this means the size of Ptirhiik's MODs will be shrinking quite a bit ;) However EM will be providing its own comments that EM will know how to skip.

As for the way you leave comments in your subforum MOD, if a person is manually installing it then they could simply comment out all those lines instead of you have to put them in the MOD script. There is no reason why you need to be doing this for them. If someone manually installing wants to document changes they can do it just as easily themselves than if you were including the comments in your MOD script.

My reasoning for not allowing such comments: sometimes people want to search for text that is a comment (like your comment anchoring idea). Therefore you cannot automatically skip a line b/c it is commented out. Plus I will also need to be keeping track of every /* and */ which is very messy.

The bottom line, is that if we want automation then we have to the best we can as a community to standardize things. There will have to be some give and take but the benefit will be near flawless automatic MOD installations. I also am not deciding all these things by myself. I always submit things to the community to examine and am willing to reverse my decisions. I also NEVER require something unless it is necessary and I have known for quite sometime that comments like you are suggesting cause problems.

IMO the best way to deal with them is to eliminate them and have some or have some standard way of telling EM to skip them. So perhaps a compromise. I could probably make it so that by adding a little extra text that EM will know how to skip your kind of comments too. But this is going to lead to double commenting since EM will already be doing this. I really don't think it is up to the MOD author to be generating the kind of comments that you do.

The difficult thing is that I'm not done writing EMC and I think people will have a better understanding when everything is done. It's not like I'm choosing one or two styles b/c I like them. The task is actually getting ALL standards to work together. Every standard I have is for a reason and it is meant to not clash with any other standard.

-Nuttzy :cool:
Last edited by Nuttzy99 on Tue Sep 02, 2003 7:00 pm, edited 2 times in total.
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

Nuttzy99
Registered User
Posts: 927
Joined: Fri Aug 03, 2001 7:09 am
Contact:

Re: 04: FINDing your Way Around

Post by Nuttzy99 » Tue Sep 02, 2003 6:58 pm

As for your TPL example, that FIND block is clearly not unique enough.

-Nuttzy :cool:
SpellingCow.com - Free spell check service for your forums or any web form!
My Other Site

Ptirhiik
Registered User
Posts: 144
Joined: Sun Apr 06, 2003 12:29 pm

Re: 04: FINDing your Way Around

Post by Ptirhiik » Tue Sep 02, 2003 7:21 pm

> sub-forums : as I stand on another board ( ;) ), categories hierarchy won't be a EMC mod, as it goes too far in the functionality and the coding of phpBB to be considered as a non-advance user mod. Will an upgrade mod from phpBB 2.0.x to phpBB 2.2 be considered as an EMC mod ? I don't think so :).

> Comments : god I have ask the mod team to introduce the [ MUTE ] action, it has been discussed and rejected. As I want to keep the original code in my mods before modification, I have no choice than to add it to the script : there is a matter of quality, in order to allow a user to easely upgrade as the phpBB version and/or the mod version. It is the only way - to my point of view - to track all installation conflicts with other mod, and actually it works just great :).

> unique statement :
Sorry, but the line to find is an unique line in the tpl mentioned : the other line are far longest, an preceded with stuff. It is not if you treat the [FIND] as an [IN-LINE FIND], ignoring the start of the line, what is my point. BTW, I really can't figure why you don't consider the start of the line : this is at least the only difference between the way FIND and IN-LINE FIND works in the finding process (I'm talking there about human process).

Also, the commented line given as example is a sample of original code in functions.php, not a comment added by a mod : only the uncommented line was added. You've got the same issue, more critical, in some line further with the if statement checking the auth (commented) or the public status of the forum (active).

Locked