Jonquil

Bringing TOML blooms to JSON land

Jonquil is a JSON library for Fortran, built on top of TOML Fortran. It provides a simple API for parsing and serializing JSON data, with seamless interoperability with TOML data structures.

Features

• Parse JSON from files or strings
• Serialize Fortran data structures to JSON
• Seamless compatibility with TOML Fortran data structures
• Modern Fortran (2008 standard)
• Multiple build systems: fpm, Meson, and CMake

Quick Start

Add Jonquil to your fpm.toml:

[dependencies]
jonquil.git = "https://github.com/toml-f/jonquil"

Parse and work with JSON:

program example
  use jonquil
  implicit none

  class(json_value), allocatable :: data
  type(json_object), pointer :: object
  type(json_error), allocatable :: error
  character(:), allocatable :: name
  integer :: count

  ! Parse JSON from a string
  call json_loads(data, '{"name": "Fortran", "count": 42}', error=error)
  if (allocated(error)) error stop error%message

  ! Access values
  object => cast_to_object(data)
  call get_value(object, "name", name)
  call get_value(object, "count", count)

  print '(a,a)', "Name: ", name
  print '(a,i0)', "Count: ", count

  ! Serialize back to JSON
  print '(a)', json_serialize(data)
end program example

Documentation

• TOML Fortran Documentation - Comprehensive guide (Jonquil follows the same API patterns)
• Jonquil Guide - Jonquil-specific documentation
• JSON Specification - Official JSON format reference

Installation

Using fpm (recommended)

Add to your fpm.toml:

[dependencies]
jonquil.git = "https://github.com/toml-f/jonquil"

Build and run:

fpm build
fpm test

Using Meson

git clone https://github.com/toml-f/jonquil
cd jonquil
meson setup _build
meson compile -C _build
meson test -C _build

Using CMake

git clone https://github.com/toml-f/jonquil
cd jonquil
cmake -B _build -G Ninja
cmake --build _build
ctest --test-dir _build

For detailed installation instructions, see the installation guide.

API Overview

Key Types

Jonquil Type	TOML Fortran Type	Description
json_object	toml_table	Key-value mapping
json_array	toml_array	Ordered list of values
json_value	toml_value	Base type for all values
json_error	toml_error	Error information

Key Procedures

Procedure	Description
json_load(val, filename)	Load JSON from a file
json_loads(val, string)	Load JSON from a string
json_dump(val, filename)	Write JSON to a file
json_dumps(val, string)	Write JSON to a string
json_serialize(val)	Serialize and return as string
get_value(object, key, val)	Get a value from an object
set_value(object, key, val)	Set a value in an object

TOML Fortran Compatibility

Jonquil data structures are fully compatible with TOML Fortran. You can use procedures from either library interchangeably:

program compatibility
  use jonquil, only : json_loads, json_value, json_object, cast_to_object
  use tomlf, only : toml_array, add_array, set_value, toml_serialize
  implicit none

  class(json_value), allocatable :: data
  type(json_object), pointer :: object
  type(toml_array), pointer :: array

  ! Parse with Jonquil
  call json_loads(data, '{"values": [1, 2, 3]}')
  object => cast_to_object(data)

  ! Modify with TOML Fortran
  call add_array(object, "more", array)
  call set_value(array, [4, 5, 6])

  ! Serialize with TOML Fortran
  print '(a)', toml_serialize(object)
end program compatibility

Requirements

• Fortran compiler supporting Fortran 2008:
  • GFortran 5+
  • Intel Fortran 18+
  • NAG 7+
• Build system (one of):
  • fpm 0.2.0+
  • Meson 0.55+
  • CMake 3.9+

Contributing

Contributions are welcome! Please read the contributing guidelines to get started.

License

Jonquil is free software: you can redistribute it and/or modify it under the terms of the Apache License, Version 2.0 or MIT license at your opinion.

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.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Jonquil by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.