|IllogicTC - Sun Apr 03, 2011 11:22 am
|A Beginner's Tutorial on INI Files
The purpose of this tutorial is to help people understand the purpose, usage, and proper decision-making in using ini files. This tutorial will cover the basics:
*Description of INI files
*When to Use an INI file, and when to use a different method (e.g. Hash).
*Using mIRC's commands associated with INI files.
INI Files: What are they, and what are they good for?
An INI file is just like a regular text document, except that it is written with a structure to support handling of individual items under what are called sections. INI files are commonly used to store settings or multiple parameters for items, where each item would have its own section.
To get an understanding of how this structure is set up, in your mIRC type:
This will make a file pop up, showing you the contents of the INI file that mIRC uses to store most basic settings. As you can see, there is a structure here, arranged in a pattern of:
Thus, when mIRC needs to find a particular value, it will just check the appropriate Section. Say it wants to check on what files it needs to load up on starting, it will check the section [rfiles], and then go through each item number and load the value for that file.
NOTE: DO NOT EDIT MIRC.INI, WE HAVE OPENED IT FOR OBSERVATION PURPOSES ONLY.
mIRC has a method built-in for allowing you to handle your own INI files, also. These can be quite useful if you need multiple things to be "remembered" for, say, one nickname. Thus, using the built-in /writeini command, we can begin setting up a file structure for a new ini.
Let us pretend, for instance, that you have the following code loaded in your mIRC:
And we have an ini file that looks like this:
Every time NICKNAME_001 typed a line in a channel, it would first read Lines, under the section [NICKNAME_001], and set the Value (4543) as %x. It would then increase the number (4544), and write that number back to the ini file. You do not have to specify that you want it to be overwritten, mIRC will automatically overwrite the old "Lines=" if it exists under the Section [NICKNAME_001]
You could use a setup like this just to keep tabs on user statistics, or do any number of other things that need multiple values remembered under one thing.
Another example would be if you were building a MUD script, and needed to add a monster called Giant Ant. You could simply make your mIRC (or type it in yourself) put all the values you need under one neat little section.
Notice, though, that Giant Ant is two words. Section Headers can only contain one word, as if you tried specifying a second word it would believe that to be the item.
This would write your INI file as:
Since we want the item to be Health, and the Section Name to be Giant Ant, we will have to replace the space in there. Therefore, you will want to use Giant_Ant, and then just use $replace(<Section Header>,$chr(32),$chr(95)) to turn the spaces into underscores. You can also reverse the process using $replace(<Section Header>,$chr(95),$chr(32)). It is also important to note that Items act the same way (they cannot have any spaces), so if you need a "multiple word" Item name, you will have to use the same method to bypass the limitations of INI.
So, you're ready to build your first ini file. Writing and reading from INI is nearly as simple as doing the same from a regular text document.
For the purposes of this tutorial, please add the following to your Remotes in Script Editor:
This will add three commands. /add_to_ini, remove_from_ini, and /read_from_ini. Note that these are not necessary to create in your own scripts using ini, it is just for the purposes of this tutorial.
First, after adding the snippet above to remotes, type this:
As you can see, you should have an INI file that looks like this:
Congratulations! You have taken your first step toward doing your own ini files. Now, study the single line of code in add_to_ini. The breakdown goes like this:
/writeini <switches> <file> <section> <item> <value>
/writeini -n imlearning.ini $1 $2 $3-
In this case, $1 $2 $3- replace Section, Item and Value. So when you typed
/add_to_ini Hello Im Learning
Hello was $1, Im was $2, and $3- was Learning, and it was written to the file imlearning.ini.
It is not necessary to have the -n switch there unless you are building a large ini file, I just do it out of habit.
Now let's add a little more to our ini file. Type this:
Now, your INI file should look like this:
Notice that in the second runthrough, we've added the item "Ive" to the section "Hello", however we have also overwritten the item "Im" in there. The value WAS "Learning", and now the value is "About to learn Reading!" Whenever you name an item that already exists, mIRC will automatically overwrite it with your new value.
When we started out with Hooray instead of Hello, it also started a new section, "Hooray," and we added two items to it.
Also of note is the system explained above about one-word section headers and one-word item names.
"Hooray Or at least I'm pretty sure I do"
The italicized Hooray became your section header, and the underlined "Or" became your item. Everything else became your value.
Reading from INI
Now that we have writing to INI files down, let's try retrieving some of that precious data we put there. For this exercise, we will be using the alias /read_from_ini.
Now in mIRC, type this:
This will make mIRC echo in your active window: "Learning"
Now let's review the structure of the /read_from_ini alias:
echo -a $readini(imlearning.ini,$1,$2)
Notice that when reading from an ini, you have to use the identifier $readini().
The structure of $readini() goes:
So when you typed /read_from_ini Hello Still, it filled out $readini like so:
And the echo made the result "Learning" show up on your active mIRC window.
The two switches involved with $readini() are only there for special purposes, the n switch making it read as plain text (as in if you had mIRC identifiers stored in the ini but DIDN'T want them going off on reading), and p, which would make | pipes read as command separators (which is useful for storing bits of mIRC script in an ini file if you need it.)
To integrate the switches, just use $readini(example.ini,np,123,456). Notice there are FOUR areas separated by commas here, but only THREE areas separated by commas in our example above. You only need the fourth area between <file> and <section> if you're using switches.
So, try a couple more. /run imlearning.ini, and pick from the two headers, and try each item, just to see how it works.
Removing from INI
So, we have our small INI, and there are things we just don't want anymore. What do we do? Luckily, mIRC makes the DELETE IT decision easy to go through with.
We have one more command to play with in the arsenal we put into your remotes earlier: remove_from_ini.
To start, type this:
Now /run imlearning.ini. You will see that all we have left is
To understand how this works, let's break down our alias remove_from_ini. The single line of code is:
As you can see, the file is already plugged in in the alias. We just provided the section and item.
However you may be wondering why we didn't have an item on typing /remove_from_ini Hello earlier. If you specify an item, it will just remove that item (we removed Or from Hooray). If you ONLY specify a section though, the entire section gets deleted. This is handy for removing whole sections of items that you do not need anymore (We didn't need the Hello anymore, as we now know about INI!)
Congratulations, you now know the three ini commands! Remember though, you don't need to build shell aliases to use them, this was just for demonstration. In a real script, just put in the $readini() right in where you need it, or use remini in that IF () statement to delete what you need.
When is it okay to use INI?
In a lot of cases where you are storing data in this format, people will suggest Hash Tables since there is more manipulation available to the scripter, and is a LOT quicker for many simultaneous actions involving data manipulation and retrieval. For more information on using Hash tables, there are other tutorials available in this forum.
For some cases though, INI is the more convenient solution. Since INI files only "Write it, Read it, Ditch it," it can be more simplified for newer scripters and only takes a few steps to integrate into most scripts.
However, if you need a script where you can parse through with wildcards and find things, etc, Hashes are your friend. INI files are only really meant to use to store data in a generic, text-based format, and you should only use these if you know the data you will be writing to it can be comfortably retrieved using $readini() commands instead of using a $find() command, and only if you are fine with a little less speed than using an equally sized hash table.
For the purposes of storing things such as statistics as I mentioned in the introduction, this is a great choice to start with until you learn about Hash routines, and also provides you the ability to open the INI file in most text editors for manual editing, and will be your friend for time-insensitive, structured data until you get until you get a grasp on more advanced subjects.
Note however the difference between an INI file and a regular text file is data STRUCTURE. Say if you just needed to keep a list of names, text files may be a little better for you. But if you need to keep a separate list of names for each network you are on, for example, INI will provide that for you. Whereas regular text files are like tossing papers into a filing cabinet at random, INI will offer one level of structure, kind of like placing the files in organized folders in the same cabinet.
However, in order to get even more structured, like putting folders in OTHER folders (going on our metaphor above), INI cannot provide the solution for without having redundant systems such as having INI files that just point to other INI files, and would end up becoming too confusing and convoluted to serve a useful purpose quite quickly. In cases where such multiple-tier structure is necessary it may be better to try another solution.
So, are you ready to take your first step into structured data with mIRC? Give it a shot!
Last edited by IllogicTC on Thu Apr 07, 2011 5:51 am; edited 1 time in total