Skip to content

noaa-oar-arl/Fyaml

BranchesTags

Repository files navigation

FYAML - Fortran YAML Parser

Build Status Coverage

A comprehensive and modern Fortran library for parsing YAML configuration files. FYAML provides an easy-to-use interface for reading YAML files in Fortran applications, supporting all major YAML features including nested structures, arrays, anchors, and aliases.

Quality Assurance

FYAML maintains high code quality standards:

  • ⚠️ Zero Warnings: Compiles cleanly with strict compiler flags (-Wall -Wextra -pedantic)
  • 🧪 Comprehensive Testing: 89.4% code coverage with 18 specialized test programs
  • 🔄 Continuous Integration: Automated testing across multiple platforms and compilers
  • 📊 Performance Tested: Handles large files and complex structures efficiently
  • 🎯 API Complete: All public functions thoroughly tested with edge cases
  • 🔧 Multi-Compiler: Tested with GCC, Intel ifx/ifort, NVIDIA HPC, and LFortran

Features

  • 🚀 Modern Fortran: Written in standard-compliant Fortran 2003+
  • 📝 YAML Compliance: Supports YAML 1.2 specification
  • 🔧 Easy Integration: Simple CMake and pkg-config support
  • 📦 Package Manager Ready: Spack package available for HPC environments
  • 🧪 Well Tested: Comprehensive test suite with 89.4% overall coverage
  • ⚠️ Warning-Free: Zero compiler warnings with strict compilation flags
  • 🏭 Multi-Compiler: Supports GCC, Intel (ifx/ifort), NVIDIA HPC SDK, LFortran
  • 📚 Documented: Complete API documentation and user guides
  • 🔗 Anchors & Aliases: Full support for YAML references
  • 📊 Arrays & Objects: Handle complex nested data structures
  • ⚡ Performance: Optimized for large configuration files
  • 🔍 Robust Testing: 18 test programs covering all API functions and edge cases

Quick Start

Installation

From Source

git clone https://github.com/fyaml/fyaml.git
cd fyaml
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
make install

Using Spack

Spack is the preferred method for HPC and scientific computing environments:

# Basic installation
spack install fyaml

# With variants
spack install fyaml +tests +shared

# Load into environment
spack load fyaml

See SPACK_SETUP.md for detailed Spack installation instructions.

Package Managers

  • Spack: spack install fyaml (recommended for HPC)
  • Source: CMake-based build system
  • Future: Additional package managers coming soon

Basic Usage

program example
    use fyaml
    implicit none

    type(fyaml_t) :: yml
    integer :: max_iterations, rc
    real(fyaml_yp) :: tolerance
    character(len=fyaml_StrLen) :: output_file
    integer, dimension(3) :: grid_size

    ! Add configuration values
    call fyaml_add(yml, "solver%max_iterations", 1000, "Maximum iterations", rc)
    call fyaml_add(yml, "solver%tolerance", 1.0e-6_fyaml_yp, "Convergence tolerance", rc)
    call fyaml_add(yml, "output%file", "results.dat", "Output filename", rc)
    call fyaml_add(yml, "grid%size", [100, 100, 50], "Grid dimensions", rc)

    ! Read configuration values back
    call fyaml_get(yml, "solver%max_iterations", max_iterations, rc)
    call fyaml_get(yml, "solver%tolerance", tolerance, rc)
    call fyaml_get(yml, "output%file", output_file, rc)
    call fyaml_get(yml, "grid%size", grid_size, rc)

    ! Clean up
    call fyaml_cleanup(yml)
end program

Compiler Support

FYAML is tested and verified to work with multiple Fortran compilers:

Compiler Vendor Versions Tested CI Status
GFortran GNU 11, 12, 13, 14 ✅ Fully Tested
ifx Intel 2025.0+ ✅ Fully Tested
ifort Intel (Classic) 2021.10+ ✅ Fully Tested
nvfortran NVIDIA HPC SDK 25.1+ ✅ Fully Tested
LFortran LFortran 0.45.0+ ⚠️ Manual Testing

Cross-Platform Testing:

  • 🐧 Linux: Ubuntu 24.04 (primary CI platform)
  • 🍎 macOS: macOS 14+ (GCC) - CI tested
  • 🪟 Windows: Windows Server 2022 (GCC) - Manual testing

Primary compilers (GCC, Intel, NVIDIA HPC) are automatically tested in CI with both Debug and Release configurations.

Building and Testing

Standard Build (Library Only)

By default, FYAML builds only the library without tests, making it suitable for production use and package installation:

mkdir build && cd build
cmake ..
make

With Tests

To build and run the comprehensive test suite:

cmake .. -DBUILD_TESTING=ON
make
ctest --output-on-failure

Legacy Test Option

For compatibility with older scripts, you can also use:

cmake .. -DFYAML_BUILD_TESTS=ON  # Legacy alias for BUILD_TESTING
make
ctest --output-on-failure

Test Suite Overview:

  • 🧪 18 comprehensive test programs covering all functionality
  • ✅ 100% test pass rate - all tests consistently pass
  • 🔍 API Coverage: Complete testing of fyaml_add, fyaml_get, fyaml_update, fyaml_add_get
  • 📊 Data Types: Full coverage for integers, reals, booleans, strings (scalars and arrays)
  • 🎯 Edge Cases: Comprehensive testing of boundary conditions and error paths
  • 📈 Array Testing: Various sizes, patterns, and multidimensional-like structures

Code Coverage

To generate code coverage reports:

# Install coverage tools (Ubuntu/Debian)
sudo apt-get install lcov

# Configure with coverage
cmake .. -DFYAML_ENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug

# Build and run tests
make
ctest

# Generate coverage report
make coverage

This will create an HTML coverage report in coverage-html/ that you can open in your browser.

GitHub Actions

The project includes automated testing and deployment:

  • CI Workflow: Automatically builds with tests enabled (-DBUILD_TESTING=ON) and tests on multiple platforms and compilers
  • Coverage Workflow: Generates coverage reports and uploads them as artifacts
  • Documentation: Automatically builds and deploys to GitHub Pages on every push to main

Note: While tests are disabled by default for end-user builds, they are automatically enabled in all CI/CD workflows to ensure code quality and compatibility across different platforms and compilers.

Coverage reports are automatically generated for pull requests and can be downloaded as artifacts from the GitHub Actions page. Documentation is automatically published at https://noaa-oar-arl.github.io/fyaml/

CMake Integration

Using find_package

find_package(FYAML REQUIRED)
target_link_libraries(your_target PRIVATE FYAML::fyaml)

Using pkg-config

find_package(PkgConfig REQUIRED)
pkg_check_modules(FYAML REQUIRED fyaml)
target_link_libraries(your_target PRIVATE ${FYAML_LIBRARIES})
target_include_directories(your_target PRIVATE ${FYAML_INCLUDE_DIRS})

Documentation

Examples

See the examples/ directory for complete working examples:

  • example.f90: Simple configuration parsing and basic usage
  • Advanced features: Anchors, arrays, and complex structures (see test files)
  • CMake integration: Example project setup

Key Test Programs:

  • test_api_functions.f90: Comprehensive API testing (461 lines, 99.8% coverage)
  • test_comprehensive_arrays.f90: Complete array testing (174 lines, 100% coverage)
  • test_edge_cases.f90: Boundary conditions and error handling (65 lines, 100% coverage)
  • Plus 15 additional specialized test programs covering all functionality

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Code style and standards
  • Testing requirements
  • Pull request process
  • Development setup

Recent Improvements

Code Quality Enhancements:

  • ✅ Eliminated all compiler warnings (intent overlap, unused variables, string truncation)
  • 📈 Increased test coverage from ~44% to 89.4% overall
  • 🎯 Enhanced main API coverage to 74.4% (fyaml.f90)
  • 🧪 Added 3 major comprehensive test suites

New Test Coverage:

  • test_api_functions.f90: Complete API function testing with all data types
  • test_comprehensive_arrays.f90: Extensive array testing (single to large arrays)
  • test_edge_cases.f90: Boundary conditions and error path validation
  • Full round-trip testing: add → get → update → verify workflows

Development Setup

# Clone and setup development environment
git clone https://github.com/fyaml/fyaml.git
cd fyaml

# Install dependencies (Ubuntu/Debian)
sudo apt-get install gfortran cmake

# macOS with Homebrew
brew install gcc cmake

# Build with all options enabled
mkdir build && cd build
cmake .. -DBUILD_TESTING=ON -DFYAML_ENABLE_COVERAGE=ON
make

# Run full test suite
ctest --output-on-failure

# Generate coverage report (requires GCC)
make coverage

Coverage Testing

FYAML includes comprehensive coverage testing using gcov. To run coverage analysis:

# Using the provided script (macOS with Homebrew)
./scripts/run_coverage.sh

# Or manually
mkdir build-coverage && cd build-coverage
cmake .. -DFYAML_ENABLE_COVERAGE=ON -DBUILD_TESTING=ON
make coverage

Current Coverage Statistics:

  • 📊 Overall Project: 89.4% coverage (2,474 of 2,767 lines executed)
  • 🎯 Main API Module: 74.4% coverage (fyaml.f90 - 484 of 651 lines executed)
  • ✅ Test Files: Near 100% coverage across all test programs
  • 🔍 Key Modules: High coverage across all critical components

Coverage reports are generated as .gcov files showing line-by-line execution data. Lines marked with ##### indicate code that wasn't executed and may need additional test coverage.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Acknowledgments

  • Thanks to all contributors who have helped improve FYAML
  • Inspired by modern YAML parsers in other languages
  • Built with modern Fortran best practices

About

Very lightweight native fortran yaml parser

Topics

yaml fortran yaml-parser

Resources

Readme

License

GPL-3.0 license

Contributing

Contributing
Activity
Custom properties

Stars

4 stars

Watchers

3 watching

Forks

4 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages