[Swimor]

RL_FILES - makes your life easy
currect version: 1.3.1, official topic: here

Hey,
Here I will explain how to use my plugin, first of all this is my first plugin.
This is very simple plugin but he has some cool tricks.

Requirements
(*) Plugin files that you can download from here
(*) At the time (v1.3.1) you must have Windows platform to run the plugin
(*) Make sure you have .DLL and .INC files.
(*) Minimum version of plugin for this tutorial is 1.3.1

Installation
The installation of the plugin are very simple, all you have to do is 2 steps.
First, Move .DLL file (plugins folder) to yourserver/plugins and edit your server.cfg (ADD plugins row):

Код:

plugins x.dll rl_files.dll x.dll

Second, In the GM/FS where you want to use the plugin just include rl_files.inc, like this:

Код:

#include <rl_files>

Now you done, you have successfully installed the plugin on your server.

Get started
After we installed the plugin let's try to understand what we doing,
The plugin allows you easy control your files and directories, and no, it's not file system like dFile, DOF2, etc..

So what is plugin for? Yeah it's good question, the plugin created to allow you create array that contents all files in specific directory.
After some time I added some new functions to the plugin and now it's like "directories system".

Now, lets try understand this code:

pawn Код:

// 1:
new
    Dir:test = dopen("test"), 
    str[64],
    type;

// 2:
while(dread(test, str, type)) if(type == TYPE_FILE) {
    printf("file: %s", str);
}

// 3:
dclose(test);

The code are has 3 parts,
First, Creating variables to store the data.
Second, Reading from the directory - the returned data will stored in str (name) and type (type DIR/FILE/UNKNOWN).
Third, We not need opened directory anymore so we can close it.

As you see the code structure are very simple, just like with files.

Working with files
The plugin adds some new file functions that allows you to fully control your files.
The big idea behind the plugin are to get file name from hes index in directory.

For example we have directory that looks like this,

Quote:

- [Level 1] scriptfiles -- [Level 2] test.txt -- [Level 2] moko.ini -- [Level 2] mdsa.ini -- [Level 2] molo.ini -- [Level 2] dir -- [Level 3] another

And we want to create loop over all files in Level 1, so we can simply use fname function.

fname(const dir[], idx, souce[], len = sizeof(souce))
This function allows get file name from hes index in the directory, here again our example folder structure,

Quote:

- [Level 1] scriptfiles -- [Level 2] test.txt (0) -- [Level 2] moko.ini (1) -- [Level 2] mdsa.ini (2) -- [Level 2] molo.ini (3) -- [Level 2] dir (non-index) -- [Level 3] another (non-index)

So we need the second file name, we simply passing index (2) to the function and the file name will pass by reference.

Here some example,

pawn Код:

// 1:
new
    file[64];

// 2:
    if(fname(".", 0, file)) // "." is ./scriptfile/.
// 3:
        printf("file with idx 0 is: %s", file);

And again the code hes 3 parts,
First, Creating variable to store the file name.
Second, Getting the file name and pass it to our variable (returns 0 if error)
Third, Printing the file name that we got on step 2.

fnum(const dir[] = NULL_DIR)
After we know the files names, how we can count files in the directory?
Simply, fnum will count the files in specific directory, lets go back to our example.

Quote:

- [Level 1] scriptfiles -- [Level 2] test.txt (0) -- [Level 2] moko.ini (1) -- [Level 2] mdsa.ini (2) -- [Level 2] molo.ini (3) -- [Level 2] dir (non-index) -- [Level 3] another (non-index)

We can see that there are (4) files in our directory, so lets create code that will detect it automaticly.

pawn Код:

printf("number of files in scriptfiles: %d", fnum(".")); // "." is ./scriptfile/.

If there are no files in directory the function will return (0)(zero) so we can check if there are files in specific directory like this,

pawn Код:

if(fnum(".")) // "." is ./scriptfile/.
    print("There are more than 0 files in ./scriptfiles");

More abilities
There are more abilities in the plugin, like check if file exist bu index or deleting file ext.

fcheck(const dir[], idx)
Now, how we can know if file with specific index are exist?
This function return boolean, true if file with the index are exist and false if not.

Here some example, this is out directory.

Quote:

- [Level 1] scriptfiles -- [Level 2] test.txt (0) -- [Level 2] moko.ini (1) -- [Level 2] mdsa.ini (2) -- [Level 2] molo.ini (3) -- [Level 2] dir (non-index) -- [Level 3] another (non-index)

So, lets try this code:

pawn Код:

if(fcheck("", 0))
    print("file with idx 0 exists!");
if(fcheck("", 4))
    print("file with idx 4 exists!");

And as you can see we dont have file with index (4) so the seconf if returned false.

fend(const file[])
The fend function are very simple, she removes the file ext, sorry but I don't have what to explain any more about this function.

pawn Код:

printf("file name \"test.ini\" without ext is: \"%s\"", fend("test.ini"));

The output will file name "test.ini" without ext is: "test".

fprint(const dir[] = NULL_DIR)
To check bugs and plugin I created some function that will print all the files in specific directory,

pawn Код:

fprint(".");

This will print all the file in ./scriptfile/. , you can simply change how the print will shown.
Edit those line in the include:

pawn Код:

#define PRINT_FORMAT          "%s/%s",dir,file

Working with directories
First, I want to show you a piece of tiny code and I will later explain what he mean.

pawn Код:

new
    Dir:test = dopen("test"),
    str[64],
    type;

while(dread(test, str, type)) if(type == TYPE_FILE) {
    printf("file: %s", str);
}

dclose(test);

After you will read whole the tutorial you must understand what this code doing.

Creating & Deleting
In order, the plugin have ability to create and delete directories.

To create empty directory, only thing we must to is use dcreate function,

pawn Код:

dcreate("test");

Here we created empty folder under "test" name.

And what if we want to delete directory, yes there are option to remove directories.
This function a bit more complicated, As you know you can add files in to directory. So our plugin allows you to delete whole directory (Including files).
Here some example code:

pawn Код:

// 1:
dremove("test", false); 

// 2:
dremove("test2", ture);

This code are have 2 parts,
First, Delete directory if he empty (if not skip).
Second, Delete directory including files, that means that all files in directory will be removed.

Reading
Now the most important part of "Working with directories", this part will describe how to read files (and sub-directories) from an directory.
Lets start with type recognization. There are 2 type of readen data,
First, TYPE_FILE(0x1) - the type of the data are file.
Second, TYPE_DIR(0x10) - the type of the data re directory.
Third, TYPE_UNKNOWN(0x100) - The type of the data are Unknown.

After we known the files type we can start coding, Lets understand how it works. And here example code:

pawn Код:

// 1:
new
    Dir:test = dopen("test"),
    str[64],
    type;

// 2:
while(dread(test, str, type)) {
    printf(type == TYPE_FILE? ("file(%d): %s"):("dir(%d): %s"), type, str);
}

// 3:
dclose(test);

We focusing only on part 2 of the code, We created loop that will work until we have files in the directory.
The first argument is type of Dir and containing the directory ID (You can get the ID by opening directory).
The second argument is the string to store the name of the file / directory.
The third argument is variable that containing type of the data.

More abilities
There are more abilities in the plugin, like renaming directory or check if directory exists.

drename(const oldname[], const newname[])
As the function name says, you can rename directory name.

pawn Код:

drename("test", "test2");

This code will rename test folder to test2.

dexist(const dir[])
And how about checking if some directory exist? Yes there is function to do it.
Here some little example of using:

pawn Код:

if(dexist("test")) 
        print("folder \"test\" exists!");

Summary
At the end we can say that the plugin has allot of options, and its not all I will update the plugin as soon I can.
We have here allot of functions Like reading files by index and fully control on our directories.
If you have and suggestion please PM me or send mail to this mail: Rafi.Zilberman@gmail.com Thanks!

Examples
If you have some interesting example of usage you can send me PM with the code and I will add your code here

Good Luck!

[S00m0]

Nice tutorial, you have some grammar mistakes
+REP

[SaTla]

Nice totorial Rafael

[Blackazur]

Nice, well explained for Beginners, good Tutorial, keep it up!