ReNamer: Making of new manual

prologician · 2009-03-02 08:52

The Manual (Page 15) wrote:

www.remobjects.com
RemObjects is a software development company that offers this great
PascalScript component, which allows run-time scripting.

So, that's the answer to one of your questions.

However, I've yet to actually find a reasonably descriptive manual there which describes what PascalScript does and does not support. Mind you, I've also not looked that carefully... (All I find are two examples, one describing objects, the other doesn't...)

Hopefully such a resource exists like you're hoping for. Because it seems kinda unfair that the ReNamer manual needs to make up for the deficiencies/laziness of the PascalScript component developers.

Andrew · 2009-03-02 08:55

As mentioned on the RemObjects site, "Pascal Script is a free scripting engine that allows you to use most of the Object Pascal language within your Delphi or Free Pascal projects at runtime." So PascalScript is a subset of Object Pascal.

One thing confuses me though - is the functionality of PS determined by RemObjects, or by Denis? If it's just a precompiled file (unit?) that a program author has to include in his Delphi project, then Denis should not be able to modify it, right? But since he obviously can modify it or at least extend it, it means he has access to either the source or something. So guess Denis has to clarify for us what modifications exactly he's made to the PS component, and what functions, data types etc. it supports now.

Re. the PS section of the manual, I haven't really found anything dealing with basics like code blocks, loops etc. The syntax of these varies across languages, so knowing what the looping commands are, how they are to be specified (eg. should it be else if or elseif?), how to set the step size, how to write a reverse (countdown) loop, how to write the loop body (eg. the end command in the if block shouldn't have a semicolon if it is followed by an else) is important for someone just starting off with PS.

Data types like arrays, pchar (used for external DLLs?) etc. are also not covered in the existing manual. Accessing external DLLs, using stuff like stdcall etc. is a topic I'd like to see in the manual or elsewhere.

Many of the functions too should have proper descriptions...

What do you guys think? Is all this too basic?

prologician wrote:

Hopefully such a resource exists like you're hoping for. Because it seems kinda unfair that the ReNamer manual needs to make up for the deficiencies/laziness of the PascalScript component developers.

Well, can't exactly blame them, for they are a professional software development company, and this component is probably developed in their free time by a few people and given away for free. So naturally there will be very little resources allocated to it and it won't be updated/maintained that regularly as well. Who knows? Maybe they will end up linking to this site and ReNamer's manual for people who want help with PascalScript! (Talk about outsourcing!)

Re. the scripts already in the forum, a separate subsection of the forum would be nice, as currently the scripts are spread around in a haphazard manner, depending on whether they were a response to a bug, a suggestion, a request for help/support etc. Of course, we'd also need to pitch in to move the scripts to that forum section. (Maybe we can have one master thread, where we can mention which thread should be moved where, to make it easy for Denis.)

Finally, if we enforce the rule of one topic per thread in that section (eg. a thread titled 'Scripts for Alphanumeric Serialization'), then having multiple scripts in a topic would not be a problem, as they'd either be different solutions for that same problem, or else a good way for someone to learn just how the script evolved to become better/more efficient or to solve bugs/issues that cropped up.

In effect, what I'm saying is that to reduce work, we pretty much move all threads containing scripts pertaining to a single issue to that forum section (with proper titles), else we split the threads according to issue and move them. No need to go around deleting old versions of scripts etc., which might do something differently and thus also be valuable.

Last edited by Andrew (2009-03-02 09:00)

prologician · 2009-03-02 09:35

Re: PS Section of the Manual

Actually, that's a good mix of stuff there, Andrew. It's been so long, I don't remember basic programming from introductory CS classes, but showing the semantics of PascalScript and how to do that nitpicky stuff is really important. That was probably the biggest speed-bump for me.

But even the comment, too, about more advanced stuff, like DLL interfaces, is a good one. I mean, when I was fiddling with my stuff, I didn't have a CLUE why iconv.dll was exploding horribly when using stdcall. It was only after Denis's suggestion to use cdecl that it all fell into place. (For the record, this is all pertaining to x86 calling conventions, something I never even looked at previously).

It seems like both should be written SOMEwhere. I don't know if they should be in the manual together. Maybe separate chapters, "Advanced Topics in PascalScript"?

narayan · 2009-03-02 15:53

Andrew, you have described all aspects of this issue very accurately!

If someone has made the script engine, and he expects others to write scripts to run on it, then he has to declare what works (and what doesn't). Script-writers cannot be expected to purely guess this. Therefore, a PascalScript script definition must be out there somewhere...

Even if the script is based on a language, I expected to see an article highlighting-
(a) a pointer to that language and
(b) specific differences between PascalScript and that "base" language.

@Listing scripts for specific purposes in the manual:
Even if we list the scripts in the manual, we will need to collect them in one place first. (I can't do it on my own, and not on-the-fly while writing the manual). The forum is the best place for that. In fact, I can harvest the forum periodically, and keep updating the manual even if the basic ReNamer has not changed.

All of us seem to agree on this one point- Start a new section with one script per thread.
***********
@where to include the pascalscript material:
Assuming that we will create a reverse-engineered tutorial on PascalScript, we will need all the topics found typically in a scripting book.

That is huge work, and will take a long time. So we can finish the first volume of the ReNamer manual, and push the PaslScripting to volume-II of the manual.

(We can place all PascalScript commands in that second volume; because without detailed explanation and other parts of the script, these functions alone are not of much use.)

In other words,
Vol-1 will contain explanation of the commands and ready-made scripts.
Vol-2 will contain "PscalScript in a nutshell" and also "PascalScript commands reference"

What do you think?

Last edited by narayan (2009-03-02 15:55)

Andrew · 2009-03-02 17:44

narayan wrote:

Assuming that we will create a reverse-engineered tutorial on PascalScript, we will need all the topics found typically in a scripting book. That is huge work, and will take a long time.

Actually, speaking from the point of view of someone who was totally new to PascalScript (ReNamer was the first and till date only app I've seen that uses it), not all the functions required detailed explanations. Most might do with a 1-2 line description IMO, while others might need a few paragraphs or a short example or two to describe accurately. General stuff like RegEx etc. (for which plenty of help exists) we can skip (though we can include a few examples on using the PS RegEx functions).

As far as including scripts in the manual goes, I'm not for it. It will become unwieldy, out of date, and with people writing multiple scripts to tackle the same problems, might very well raise issues about which script deserves to be included in the official documentation. Plus many scripts might not have a wide/general application. Scripts should be confined to a subsection of the forum, and if any of them are really worth it and of a general enough nature, Denis can choose to include those in the distribution package as part of the Scripts folder.

I say we tackle one section at a time. Let's first get all the non-PS stuff done, 'cos that's definitely easier, and then let's get to PS (where we might need to pester Denis often for help/clarifications).

narayan · 2009-03-02 17:58

I think you are right!

So while I go ahead with the rest of the manual, those who are familiar with PS please put together a chapter for PS; and I will just put that chapter in.

narayan · 2009-03-11 03:27

I have almost finished the manual (only a day's work remains- finishing touches).

Only the pascal script remains. There too, I have found a jackpot:
www.taoyue.com/tutorials/pascal/contents.html

At the end of that tutorial, the author provides multiple references also.
http://www.freepascal.org/docs-html/

However, for some reasons, the tutorial does not cover some basic tokens like break, exit, continue and uses. I have contacted the author yesterday.

That means we have to provide only ReNamer-specific scripting tips and typical building blocks that are frequently used in ReNamer.

Can anyone do this?

I know I can do this by combing the scripts posted at the forum, but some of you would remember such tips offhand.

prologician · 2009-03-11 05:41

A few quick thoughts (I don't know exactly what you've written, but I'm gonna put these out there now).

1. PascalScript does not support pointers (Forum references here and here). Yeah, I said this before, though since that Free Pascal website brings it up, I should also mention what really applies.

2. I only briefly looked at the Free Pascal website, so I don't know if I'm being redundant with saying this, but Pascal (and PascalScript too) does not support lazy evaluation. When you have a conditional statement, all parts are evaluated, even if a partial evaluation guarantees that it is true or false.

For example:

var
  Num: Integer;

begin
  Num := 0;
  
  if ((Num > 0) and (5 / Num = 1)) then
    Filename := Filename + IntToStr(Num);
end.

This is perfectly legitimate code in C, because the first test fails, the condition is guaranteed to be false, and thus the division never happens. However, in Pascal and PascalScript, the division happens, and you get a Division by Zero error.

As far as the keywords you're referring to.... break and continue are keywords controlling iterations through loops (Delphi Basics for break and continue). Exit is how you can get out of a function/procedure without letting execution reach the end of the function. Uses.... dunno, you got me on that one.

Last edited by prologician (2009-03-11 05:43)

krtek · 2009-03-11 17:14

Initialization of variables and breaking the execution of the script

I guess one of the important things to understand is that rules are applied file-by-file, which means you get all the rules applied to the first file and then all the rules (in order as they appear in rules window) applied to the next file and so on.
For PascalScript rules it means that script is run for x times (where x is number of files marked for renaming in the filetable). The trick that makes script useful is that it preserves values of variables between executions of the script during one Preview operation (although variables are reset to their default values every time you press Preview or AutoPreview takes place). It means you can rely on any incrementation you let the script to do. The drawback of that situation is that you can't simply set starting values of variables in the script, because they will be reset to these starting values on every execution of the script (so for every file), eg. this script

var
i : Integer;

begin
  i:=0
  i:=i+1;
  Filename:=IntToStr(i) + '.txt';
end.

will make every filename to be "1.txt".
So if we need any initialization of variables we need to write such code that will be executed only during the first execution of the script. To do that we have to learn one very useful thing: all boolean variables in ReNamer's PascalScript have their default value set to FALSE. With that knowledge we can write initialization part of the script:

var
  Initialized: Boolean;

procedure Initialize;
begin
  Initialized := True;
  // Initialization code here
end;

begin
  if not Initialized then Initialize;
  // The main renaming code here
end.

Procedure Initialize is executed only if Initialized variable is FALSE. And as the procedure sets the variable Initialized to TRUE, it prevents the initialization code to be executed more than once.

You need similar approach to the problem if you want to allow user to exit your script (and stop whole Preview operation) on some condition.
Exit statement has no use in this situation as it exits only from the script that is currently executed. It means that you might exit from the script executed, eg. for the first file in the filetable, but then script will be executed again for the second file, and third, and so on... And every change to the filename (or file) that occures in the script before the exit statement will be applied.

The simple workarround is to make the execution of the script dependent on some boolean variable, eg. TimeToExit:

var
TimeToExit : Boolean;

begin

if not TimeToExit then
    begin
    //main remaining code
    //with part
        if INeedToExit then
           begin
             TimeToExit:=True;
             exit;
           end
    end
else exit;

end.

PS. I'm not an English native speaker, so feel free to make any language (or logic ;-) adjustments.

Last edited by krtek (2009-03-15 19:18)

narayan · 2009-03-11 18:36

prologician, I know those keywords (from other languages) but I want the tutorial to be self-sufficient, so that our manual stays clear of script basics.

So far as script is concerned, I have not written anything so far. But I wanted exactly what you and krtek have provided. Plus I want to list all the ReNamer-specific functions with examples, best uses, etc.)

I have sent the preliminary documentation to Denis, as I haven't subscribed to a shared server space. I hope he shares the docs with all to invite more comments.

den4b Forum

#21 2009-03-02 08:52

Re: ReNamer: Making of new manual

#22 2009-03-02 08:55

Re: ReNamer: Making of new manual

#23 2009-03-02 09:35

Re: ReNamer: Making of new manual

#24 2009-03-02 15:53

Re: ReNamer: Making of new manual

#25 2009-03-02 17:44

Re: ReNamer: Making of new manual

#26 2009-03-02 17:58

Re: ReNamer: Making of new manual

#27 2009-03-11 03:27

Re: ReNamer: Making of new manual

#28 2009-03-11 05:41

Re: ReNamer: Making of new manual

#29 2009-03-11 17:14

Re: ReNamer: Making of new manual

#30 2009-03-11 18:36

Re: ReNamer: Making of new manual

Board footer