|
ResMagik
1.0 Documentation This document contains detailed information about every aspect of ResMagik. Consider it the help file, it's detailed enough just in case you're a newbie with resource files. This program is oriented to programmers, i assume you're an experienced one so you probably don't need to read this document. What's a resource file? Most applications use text, images, sounds, videos and many other external files or data. These objects are also known as resources. These resources are used for multiple purposes depending on the type they are. As you might already noticed, many programs you have downloaded use images but, where are these images stored if the programs are only single executable files and sometimes they come with a few satellite assemblies not even related to an image file? Well, the only answer is that these programs are using resource files. Resource files then are files just like any other file but they act like "packages" to store other files, programs are able to read these packages and retrieve data. There're many custom engines for data retrieval but the main concept and popularity of resource files born with the old Win16 resource. Probably, you're now asking yourself: Why should i use a resource file if there're many cool packaging file formats out there? Because compression formats such as RAR, ZIP, ACE, TAR, etc are used only to package or compress files while resource files store many other data types (including files) such us: Strings, dialogs, menus, accelerators and many other serializable objects. Resource files can be used in web sites (dynamic pages). Resource files differ from other file types in the way they can be used: Resource files may be used directly by an application or (one of the most important feature) they can be embedded inside executables or libraries (the executable reads itself to retrieve data). "...A resource is any nonexecutable data that is logically deployed with an application..." .NET Framework Developer's Guide. When the .NET Framework 1.0 appeared around the 2001, two new resource file formats came out with it, we're talking about ".resx" and ".resources" file formats. The first one is a XML structure containing multiple tags and the actual binary state of a resource, .resx files can be easily opened and edited in text mode with any text editor but they can't be embedded in assemblies. In the other hand, .resources files are almost impossible to edit with a text editor because they are in a binary form but they are embeddable with assemblies. Both formats are an evolution from years of implementations, dropping ambiguities like storing different resource types in different tables and adding new features like native support for UTF-8 strings. Now a days, these resource file formats and other implementations store all resources in a single area (not in a specific table) and had excluded certain objects from the specification (for example, dialogs and forms are now part of the program code), these formats now may include only strings, files and generic serializable objects. Why to use a resource file?
What's ResMagik? ResMagik is a very simple, easy to use and open source command line tool for compiling Microsoft .NET '.resources' files. Technically, is nothing more than a external interface to the .NET libraries with extended functionality. It's designed for neutral culture resources (yet). More about ResMagik and me here. ResMagik is free software, this means you can use and distribute ResMagik and its source code under the terms available in the GNU General Public License version 2. A copy of the GPL license is included in the distribution. You can also read it with the command ResMagik -l. <DISCLAIMER> Please note that ResMagik is provided AS IS (with all possible faults) and comes with no warranty. I (Heinz Traub) am not responsible for binary files generated by ResMagik and content (text and files) inside them. You (ResMagik user) are complete responsible for negative results due to incorrect usage of your resource files (virus & malware packaging). If you included copyrighted text or files protected by a copyright, patent or license inside a resource file generated by ResMagik, that's absolutely your responsibility. By using ResMagik or creating a resource file with it means you're in agreement with the terms of this disclaimer. </DISCLAIMER> You can also read this disclaimer with the command ResMagik -i. ResMagik can be downloaded only from SourceForge.net's download system. If you wish to be able to download ResMagik from your website please use a direct link to the file from SourceForge.net's download servers.
Version 1.0 (16/07/2007). The source code is also available for download but it's included in a different package. Go to the download page at SourceForge.net here and select for download the file "ResMagik-1.0-src.zip". As a prerequisite for running ResMagik you need Microsoft .NET Framework 2.0 Runtime Libraries which can be downloaded here. ResMagik comes packaged in a single ZIP file. You only need to unzip the file with your preferred program in any folder you want and that's it. No external files or registry entries are required for installation or use (clean install). The package should contain the following files.
A good idea could be to include ResMagik's path into the global variable PATH. By doing this you can call ResMagik from any working directory. This section will explain in full detail how ResMagik works and how to use it. A few examples are listed in the Examples section below just in case you didn't understood or want to learn directly from implementation. If you read only the explanation i recommend to take a look at the examples too because they give useful tips and have downloadable C# source code and precompiled binaries with example programs that make use of resource files. In order to create a resource file you need of course external resources. ResMagik retrieves external resources information from a list, this list contains resource declarations such as strings (id & value), file locations and directories. The list is a physical file in plain text format with ANSI or UTF-8 encoding and whatever extension you want. More about the list later, we'll now start from the beginning. ResMagik is a flexible tool, it takes certain parameters as instructions to perform specific task for specific resources. In order to compile a resource file we must tell ResMagik what to do by passing parameters. Parameters are string values separated by a white space character and are passed by calling ResMagik's executable followed by the strings.
Ok, i know what a parameter is but, what parameters should i pass and how do i use them? ResMagik takes at least 3 parameters (see example above. Links to each parameter explanation: 1 2 3) and they must be in the correct order, a fourth parameter or more will be ignored, passing less than 3 will show the help screen: The first parameter is reserved for a set of special instructions called 'options'. This parameter tells ResMagik what to do. It must be present, it must start with the character '-' (ASCII code 0x2D) and it must contain at least one character *. Each character of this parameter is an option and it represents a specific instruction, characters are case sensitive. Options are divided into 3 categories:
* Remark: The first parameter must contain at least one character and it must be a command option. Check the table below for a full list of all available options:
* Working Directory: Directory from where ResMagik is called. Ok, i read the whole introduction to options, what's next? Well, we now give the first step by passing the first parameter which is a command option and a few environment options:
If you add an invalid option or don't add a command option, the help screen will be shown. You said we needed al least 3 parameters, where's the second? The second parameter is nothing more than the list's path. The path is either absolute or partial (relative to the working directory), it doesn't need to start with a '-' character, that's for identifying options only. So, lets add the second parameter to our previously example:
OBSERVATION: When calling an executable file with multiple parameters, they must be separated by white spaces right? Then, What if you want to pass a parameter, a path for example that has white spaces in it?: C:\Program files\my folder\myfile.txt. Here we are passing one parameter with 2 white spaces in it. So, the program will recognize 3 parameters and that's an unwanted result. What to do to solve this issue? Replace all white spaces with the character '?'. Our example would end like this: C:\Program?files\my?folder\myfile.txt. ResMagik will then replace back '?' characters with white spaces and will continue with the program flow normally. We have successfully declared the list to be used but, it must exist or an error will be throw. I'll now explain how to create a list and add resources to it. Create a text file in plain text format with Notepad or whatever text editor you want. The file must be in ANSI or UTF-8 encoding. Choose the name and extension you prefer and save the file in any location. That's enough and our list is ready, now, lets add resources to it. There're 2 types of resources: Strings and files. Strings are just text strings used by your application for output. Files are external resources used by your application such as icons, images, sounds, videos and binary files of any kind for multiple purposes. Each resource is added (declared) by writing a line in the list with a few information related to the resource, each line in the list represents a resource. Special characters may be used such as ';' which comments a line if it starts with this character (comments are skipped), also you can start a line with '-' for adding options for that resource (we'll cover this topic later). We now refer to a line in the list as a "resource declaration". Every resource (strings and files) inside a resource file has an identifier (id), this identifier is used inside your program code to call (use) a specific resource. Identifiers are unique, trying to add 2 different resources with the same id will throw an error at the second resource. Resources in the Microsoft .NET platform are stored with the type or class they are, this helps the .NET libraries and 3rd party software to easily identify resources and tells how to work with them, ResMagik automatically generates this field by the following criteria:
Because strings and files are declared in a different manner, we'll cover both cases: Usage > Adding Resources > Adding Strings Strings are declared by writing the id and the text separated by the character '='. The id must contain at least one character, it can contain white spaces. The text is the actual value of the string, it can be whatever you want (no character restrictions), it can be null and it can contain character literals (output format will vary on your implementation). As you might already read, you can add list options before declaring a resource. For strings this isn't the case, strings don't support options. Do not add options for a string declaration because they will be ignored and do not start a string declaration with the character '-' because it will be recognized as an option.
In conclusion, all text to the left from the first '=' is the id and the text to the right is the value. ResMagik looks for the character "=" to recognize the declaration as a string, so this character is reserved specially for strings and if you're trying to declare a file that contains "=" it will be recognized as a string, the list option 'p' is used in cases like this but it will be covered next (Adding Files). If you want a string id to start with '-' or ';', a good technique is to start the declaration with the list option 'n' because this option was specially made for these cases, the rest of the options will be ignored except for 'p' so please don't use it if you wish to declare a string:
If you want to add strings with special international characters then make sure you save your list file with UTF-8 encoding. Usage > Adding Resources > Adding Files When you add a file, the name is used as the id (it includes the extension if it's present). File declarations support options, so make sure you use an existing option, adding an invalid option will cause an error to be thrown . Use the option 'n ' if the declaration starts with a reserved character ('-' or ';'). There're three ways for adding files (files can be of any extension you want): The first one is to declare the file's path and that's it. The path can be absolute or partial. Remember that by default, partial paths are relative to the list, if the path couldn't be found then the path is relative to the working directory. Use the list option 'r' to revert the search order and make first the path relative to the working directory.
The second way is able to add multiple files at a time by adding a search pattern to the paths declared. Search patterns are valid only if the character '*' is present in the name or extension of the file. Multiple wildcards may be used.
And the third way is the most suitable one for adding files. It consist in declaring a folder and all files inside the folder will be added. This is the recommended method for adding files because you can add all your desired files with only one declaration while having all your files in one folder all well organized. You can also include the option 's' to add all files in subfolders too (useful if you want to organize your files by categories).
OBSERVATION: If you add a path, for example "C:\my folder\myfile.bin". ResMagik will first try to find a file named "myfile.bin" in the folder "C:\my folder", if the file couldn't be found then it will try to find an existing folder called "C:\my folder\myfile.bin". If neither a file or a directory is found then an error will be thrown. OK, that's all about adding resources. Where were we? Ah, yes. Finally, where's the third and last parameter? The third parameter is the name of the output file (THE resource file), in fact it's the name or path of the desired resource file. Again, the path may be absolute (aka full path) or partial relative to the working directory. Files should contain the extension ".resources". You can also specify only the name without extension and call ResMagik with the option 'x' for automatically adding the extension for you. Valid examples are:
OBSERVATION: As with the list parameter, if the path specified contains whites paces, you should replace them with the character '?' in order to be recognized as one parameter. ResMagik will then replace them back to whitespaces. "That's all folks". I hope at least you get an idea what resource files are, how important they are for a good quality programming and how to create them. Feedback would be much appreciated. Thanks man, it's all clear to me but, how do i use them in my source code? If you're not already tired of reading then keep reading the examples section. Examples explain how to read resource files with .NET libraries and show also one of the most important features of resource files: Embedding a resource file with an executable or library file. ResMagik is a command line tool, this means you must run it from a command prompt. Fortunately, you may run ResMagik from a batch file making repetitive tasks much easier. You can use the same batch file used to compile your application. By doing this, your resources get refreshed every time you recompile your program. Creating a batch file is easy: Just create a text file with Notepad or the text editor of your choice and save it with the extension ".bat". Now edit this file and add all the commands you'd usually use in a command prompt (one command per line), save the file and close it. Now open it by clicking/double clicking the batch file (type its name if you're in a command prompt and press enter) and now all commands inside the batch file will start to execute in the order they were written. The following examples include calling commands to ResMagik, you could insert these commands in a batch file. I uploaded the following examples just for you to learn from code. Please study the code because i don't want to go into much detail about C# code and .NET libs (that's beyond the scope of this documentation). Check also the batch file that compiles the program and calls ResMagik to create the resource file (that's the primary goal). Finally take a look at the list file to understand a working example, select ids from the list and trace them in the source code, with this you'll learn how to bind your code with a specific resource. A lots of things can be done when you mix resources and code, i just put in the basics for resource output. Example 1: Resources in console applications.
Instructions: To compile this example register the C# compiler in the global variable PATH then install ResMagik in the same folder you extracted the example. The precompiled binary is in the bin\ folder, to execute this example open the batch file Run.bat.
Example 2: Resources in Winforms applications.
Instructions: To compile this example register the C# compiler in the global variable PATH then install ResMagik in the same folder you extracted the example. The precompiled binary is in the bin\ folder.
Example 3: Multilanguage application with manual culture setting.
Example 4: Multilanguage application with automatic culture detection.
Example 5: Resources in dynamic web pages.
As mentioned before: Errors are thrown when a resource coudn't be added. If a resource throws an error, the program will continue with next resource in the list. Errors will output a short description of the fault within the line number in the list. Try reading the messages and correct the list. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
ResMagik...we love you! |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
