program example1 ! Typical usage should only require an explicit use of the fson module. ! The other modules will be used privately by fson as required. use fson ! declare a pointer variable. Always use a pointer with fson_value. type(fson_value), pointer :: value ! parse the json file value => fson_parse("test1.json") ! print the parsed data to the console call fson_print(value) ! extract data from the parsed value ! clean up call fson_destroy(value) end program example1

This JSON will serve as a reference for the following examples.
If you are not already familiar with JSON you can read more at: http://www.json.org/ and http://en.wikipedia.org/wiki/JSON.

{ "name" : {"first": "John", "last" : "Smith"}, "age" : 25, "address" : { "streetAddress": "21 2nd Street", "city" : "New York", "state" : "NY", "postalCode" : "10021"}, "PhoneNumber": [ {"type" : "home", "number": "212 555-1234"}, {"type" : "fax", "number": "646 555-4567"} ] } 

Getting the data from the parsed fson_value to your variable is easy. All extraction is performed through a call to fson_get().
This subroutine is overloaded for different target value types.

program example1 ! The fson mudule has the basic parser and lookup use fson ! Functions for accessing data as an array use fson_value_m, only: fson_value_count, fson_value_get character(len=1024) :: strval, strval2 integer i ! Declare a pointer variables. Always use a pointer with fson_value. type(fson_value), pointer :: json_data, array, item ! Parse the json file json_data => fson_parse("test1.json") ! Get the first and last name and print them call fson_get(json_data, "name.first", strval) call fson_get(json_data, "name.last", strval2) print *, "name.first = ", trim(strval) print *, "name.last = ", trim(strval2) ! Use a lookup string to get the first phone number call fson_get(json_data, "PhoneNumber[1].number", strval) print *, "PhoneNumber[1].number = ", trim(strval) print *, "" ! Get the phone numbers as an array call fson_get(json_data, "PhoneNumber", array) ! Loop through each array item do i = 1, fson_value_count(array) ! Get the array item (this is an associative array) item => fson_value_get(array, i) ! Lookup the values from the array call fson_get(item, "type", strval) call fson_get(item, "number", strval2) ! Print out the values print *, "Phone Number:" print *, "type = ", trim(strval), ", number = ", trim(strval2) end do ! clean up call fson_destroy(json_data) end program example1

The program output is the following:

name.first = John name.last = Smith PhoneNumber[1].number = 212555-1234 Phone Number: type = home, number = 212555-1234 Phone Number: type = fax, number = 646555-4567 

You can also extract entire arrays, as Fortran allocatable arrays, using fson_get(). This assumes the array's elements are all of the same type (integer, real, double precision, logical or character). Rank-1 (vector) or rank-2 (matrix) arrays are supported.

The following example parses a JSON file containing an vector of integers called "v" and a matrix of real numbers called "m", and prints them:

program extract_array use fson implicit none type(fson_value), pointer :: data integer, allocatable :: vec(:) real, allocatable :: mat(:,:) data => fson_parse("data.json") call fson_get(data, "v", vec) call fson_get(data, "m", mat) print *, vec print *, mat call fson_destroy(data) deallocate(vec, mat) end program extract_array

When extracting character arrays, it is necessary to specify a string length when the array is declared, e.g.:

integer, parameter :: str_len = 8 character(len = str_len), allocatable :: m(:) data => fson_parse("data.json") call fson_get(data, "char_array", m)

| Operator | Description | |----------|--------------------------| | $ | Root object/value | | . | Child operator | | [] | Array element | 

Three methods for installing FSON are provided: a regular Makefile, a Meson build, and a CMake build. Below we give a brief overview of how to use each one.

Installing via Makefile is simply a matter of opening the provided makefile, updating the appropriate variables near the top, and running

make make install

For the Makefile build, unit tests can be run using the FRUIT library, together with FRUITPy which is a Python interface to FRUIT. When these are installed, the fson_test.py script in the FSON base directory can be run to execute the unit tests.

For a more automated installation, see one of the following installation methods.

Once Meson and Ninja are installed on your system, FSON may be built, tested and installed as follows:

meson build cd build ninja ninja test # optional unit tests ninja install

For the Meson build, the unit tests use the Zofu library. If this is not already installed on your system, it will be built as a Meson subproject of FSON.

See the Meson documentation for more information on customizing the build (e.g. specifying the install directory, build optimization etc.).

The provided CMakeLists.txt runs with CMake 3 to configure, build and install FSON. The simplest means to build and install using CMake is to run

mkdir bld cd bld cmake3 .. make make test # optional unit tests make install

However, all of the command options available to CMake are supported. For example, to enable building shared libraries use the -DBUILD_SHARED_LIBS:BOOL=ON flag and to override the installation prefix use -DCMAKE_INSTALL_PREFIX=.... Thus the command

cmake3 -DBUILD_SHARED_LIBS:BOOL=ON -DCMAKE_INSTALL_PREFIX=$HOME

would configure FSON to build a shared library and install under your home directory.

Once FSON has been built and installed, you can import it into your CMake supported project using

find_package(FSON) ... add_executable(mytarget ... target_link_libraries(mytarget FSON::FSON)

The CMake build require CMake version 3.6.1 or higher and git version 1.6.5 or newer. It may work with older versions of CMake, but this is what has been tested.

Some platforms are unable to build the Zofu dependency, but the library builds correctly. On these platforms, use

cmake3 -DFSON_ENABLE_TESTS:BOOL=OFF ...

to disable the unit tests.