DescriptionFortranFormat is an open source Java library for parsing input and formatting output using Fortran Format specification. FortranFormat is written by Kevin Theisen.
UtilityInput and output processes are some of the most common and important functions performed in a program. However, writing a parsing program each time new data needs to be analyzed can be a tedious experience. Having a wide assortment of libraries available significantly reduces the amount of work necessary.
Why did you write FortranFormat? We needed Fortran Formatting to read and write various chemical filetypes, namely Standard Molecular Data (SMD). Most other programming languages have libraries for parsing Fortran Format, but in all of our searching, we could not find a credible library in Java, so we wrote it ourselves. The FortranFormat library is now used to parse/write all fixed length filetypes in ChemDoodle. Why use Fortran Format in Java? Fortran Format may be quite old, but it is still commonly used in many places, especially in academic settings where Fortran is still widely used. If you want to upgrade your system to use Java for any reason, you can use this library to ease the transition. Also, many file formats are easily parsed and written using Fortran Format, so it is a welcome addition to any Java parser's library. Why not use a protocol such as XML rather than Fortran Format? The FortranFormat library does not compete with parsers of other protocols like XML; it is just another library to be used when the need arises. Many file formats were created years before XML and other markup languages were developed and therefore require different parsing libraries to manipulate. FortranFormat aids in that aspect, especially in cases where output and input are text based and restricted to specific column widths (older formats are usually restricted to 80 columns to fit correctly in a console window).
Ease of UseFortranFormat is Java 1.5+ compatible and adheres to the standards of Java 1.5. The entire library was written by Kevin Theisen, so it is very easy to read and follow. It is commented with standard JavaDoc and is packaged with a JUnit testing set.
UsageFortranFormat is typically used in two ways, statically and as an object. You may call FortranFormat using the static read and write methods that should be familiar to those using Fortran.
::CODECOLORER_BLOCK_1::The static read method allows you to quickly obtain a ArrayList of Objects (of correct class as described below), given an input string and a format specification string.
::CODECOLORER_BLOCK_2::The static write method allows you to quickly obtain a formatted string, given an input ArrayList of Objects (of correct class as described below) and a format specification string.
You may use a FortranFormat Object to read and parse a large number of lines from a given file.
::CODECOLORER_BLOCK_3::You may also use a FortranFormat Object to format a large number of data structures to an output file. The additional beauty of this procedure is that the same FortranFormat Object used for the parsing, may also be used for formatting!
For much more complex examples, read this story about using FortranFormat to read and write chemical filetypes.
OptionsThere is an Options object associated with every instance of the FortranFormat class. The following options are available.
|Will add '\n' character to the end of all formatted output.|
|setLeftAlignCharacters(boolean b)||Strings will be left aligned when formatting content for the A edit descriptor.|
|setPositioningChar(char c)||Change the character used for spacing by the X edit descriptor.|
|setReturnFloats(boolean b)||Float objects will be returned instead of double after parsing input.|
|setReturnZerosForBlanks(boolean b)||If a blank is detected for numbers during parsing, a zero will be returned of the appropriate class, instead of a null.|
Runtime ExceptionsAll exceptions are thrown by FortranFormat, as should be. You must account for thrown exceptions in your code. Usually exceptions will occur when parenthesis are not used correctly, or when data cannot be parsed or casted according to the Java Class relationships described below. Parse exceptions are used when further information about the position of the exception during parsing is available.
Extent and LimitationsThe format specification string is parsed forgivingly. FortranFormat supports grouping and multiplication and does not require commas, although you may want to include commas to resolve any ambiguities. FortranFormat supports the following Fortran Format edit descriptors as listed. For clarity, the ArrayList<Object> that is returned after parsing a string will contain Objects with classes corresponding to the class listed in the Java Object Created column. You should then cast the Objects appropriately when using them. When formatting a ArrayList<Object> using FortranFormat, you should place in Objects with classes corresponding to class listed in the Java Object Formatted column. The Objects that appear in the ArrayList<Object> are (and should be) in the same order as the repeatable edit descriptors they correspond to. Non-repeatable edit descriptors are not represented (and nothing should be included for them) in the ArrayList<Object>.
Fortran Format Edit Descriptors
|Edit Descriptor||Descriptor Code||Read Supported||Write Supported||Java Object Created||Java Object Formatted|
|Real Decimal||F||Yes||Yes||Double||Double or Float|
|Real Exponent||E||Yes||Yes||Double||Double or Float|
|Real Scientific||ES||Yes||Yes||Double||Double or Float|
|Real Engineering||EN||Yes||Yes||Double||Double or Float|
|Edit Descriptor||Descriptor Code||Read Supported||Write Supported|
|Horizontal Tab||T, TL, TR||No||Yes|
|Format Scanning Control||:||Yes||Yes|
|Sign Control||S, SP, SS||No||No|
|Blank Control||BN, BZ||No||No|