Kajabity Tools
Kajabity Tools (for C’#) is a free, Open Source collection of software utilities for .NET applications – version 0.1 includes only JavaProperties and related classes.
Java Properties in C#
The main component in the Kajabity Tools .NET class library is the JavaProperties class and it’s helpers – these are shown in the diagram below:
The classes are: -
- JavaProperties – a C# class that extends the Hashtable class to provide functionality similar to the Java “Properties” class – it maintains a number of (string) keys with values and can load them from or store them to a Java style “.properties” file.
- JavaPropertyReader – this class is used by JavaProperties to read Java style properties from an input stream. It can be used directly to load properties into any Hashtable or derived class.
- JavaProperetyWriter – this class is used by JavaProperties to store Java style properties to an output stream. It can be used directly to store properties from any Hashtable or derived class.
- ParseException – this exception is thrown if the contents of the stream being read by JavaPropertyReader are invalid (for example a malformed Unicode escape.
The Java Properties Format
A Java style properties file contains key value pairs (properties) in a file with ISO-8859-1 encoding (code page 28592). The file usually has a “.properties” file extension and consists of a series of lines (terminated by \r, \n or \r\n) each a key value pair, a comment or a blank line.
Leading whitespace (spaces, tabs \t, form feeds \f) are ignored at the start of any line – and a line that is empty or contains only whitespace is treated as blank and ignored.
A line where the first non-whitespace character is a ‘#’ or ‘!’ is a comment line and the rest of the line is ignored.
If the first non-whitespace character is not ‘#’ or ‘!’ then it is the start of a key. A key is all the characters up to the first whitespace or a key/value separator – ‘=’ or ‘:’.
The separator is optional. Any whitespace after the key or after the separator (if present) is ignored.
The first non-whitespace character after the separator (or after the key if no separator) begins the value. The value may include whitespace, separators, or comment characters.
Any Unicode character may be included in either key or value by using escapes preceded by the escape character ‘\’.
The following special cases are defined:
'\t' - horizontal tab. '\f' - form feed. '\r' - return '\n' - new line '\\' - add escape character. '\ ' - add space in a key or at the start of a value. '\!', '\#' - add comment markers at the start of a key. '\=', '\:' - add a separator in a key.
Any unicode character using the following escape:
'\uXXXX' - where XXXX represents the unicode character code as 4 hexadecimal digits.
Finally, longer lines can be broken by putting an escape at the very end of the line. Any leading space (unless escaped) is skipped at the beginning of the following line.
Examples
a-key = a-value a-key : a-value a-key=a-value a-key a-value
All the above will result in the same key/value pair – key "a-key" and value "a-value".
! comment... # another comment...
The above are two examples of comments.
Honk\ Kong = Near China
The above shows how to embed a space in a key – key is "Hong Kong", value is "Near China".
a-longer-key-example = a really long value that is \
split over two lines.
An example of a long line split into two.
Download
Version 0.1 – Released 1st December 2009
Click on the link below to download a ZIP file containing the DLL, source files and licence details for Kajabity Tools v0.1
The download zip file contains:
- Kajabity Tools DLL – this can be included in a project’s references.
- Sources for Kajabity Tools – including JavaProperties and associated classes.
- Documentation.chm – genereated help file from the code comments.
- Licence, Notice – a copy of the Apache License, Version 2.0.
Licence
Kajabity Tools is licensed under the Apache License, Version 2.0 (the “License”); you may not use Kajabity Tools except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.