Merge branch 'master' into master

Author: hsnyder

.github/workflows/CI.yml

@@ -90,7 +90,7 @@ jobs:
     - name: Test manual makefiles
       if: contains(matrix.os, 'ubuntu') && contains(matrix.gcc_v, '10')
       run: |
-        make -f Makefile.manual FYPPFLAGS="-DMAXRANK=4"
+        make -f Makefile.manual FYPPFLAGS="-DMAXRANK=4" -j
         make -f Makefile.manual test
         make -f Makefile.manual clean
 

.github/workflows/ci_windows.yml

@@ -70,6 +70,7 @@ jobs:
           mingw-w64-${{ matrix.arch }}-gcc-fortran
           mingw-w64-${{ matrix.arch }}-python
           mingw-w64-${{ matrix.arch }}-python-pip
+          mingw-w64-${{ matrix.arch }}-python-setuptools
           mingw-w64-${{ matrix.arch }}-cmake
           mingw-w64-${{ matrix.arch }}-ninja
 

CMakeLists.txt

@@ -1,12 +1,19 @@
 cmake_minimum_required(VERSION 3.14.0)
-project(fortran_stdlib Fortran)
+project(fortran_stdlib
+        LANGUAGES Fortran
+        VERSION 0
+        DESCRIPTION "Community driven and agreed upon de facto standard library for Fortran"
+)
 enable_testing()
 
 # Follow GNU conventions for installation directories
 include(GNUInstallDirs)
 
 include(${PROJECT_SOURCE_DIR}/cmake/stdlib.cmake)
 
+# --- CMake specific configuration and package data export
+add_subdirectory(config)
+
 # --- compiler options
 if(CMAKE_Fortran_COMPILER_ID STREQUAL GNU)
   add_compile_options(-fimplicit-none)

README.md

@@ -3,6 +3,18 @@
 [![Actions Status](https://github.com/fortran-lang/stdlib/workflows/CI/badge.svg)](https://github.com/fortran-lang/stdlib/actions)
 [![Actions Status](https://github.com/fortran-lang/stdlib/workflows/CI_windows/badge.svg)](https://github.com/fortran-lang/stdlib/actions)
 
+* [Goals and Motivation](#goals-and-motivation)
+* [Scope](#scope)
+* [Getting started](#getting-started)
+  - [Get the code](#get-the-code)
+  - [Requirements](#requirements)
+  - [Supported compilers](#supported-compilers)
+  - [Build with CMake](#build-with-cmake)
+  - [Build with make](#build-with-make)
+* [Using stdlib in your project](#using-stdlib-in-your-project)
+* [Documentation](#documentation)
+* [Contributing](#contributing)
+* [Links](#links)
 
 ## Goals and Motivation
 
@@ -82,6 +94,12 @@ GCC Fortran (MSYS) | 10 | Windows Server 2019 | x86_64
 GCC Fortran (MinGW) | 10 | Windows Server 2019 | x86_64, i686
 Intel oneAPI classic | 2021.1 | Ubuntu 20.04 | x86_64
 
+The following combinations are known to work, but they are not tested in the CI:
+
+Name | Version | Platform | Architecture
+--- | --- | --- | ---
+GCC Fortran (MinGW) | 8.4.0, 9.3.0, 10.2.0 | Windows 10 | x86_64, i686
+
 We try to test as many available compilers and platforms as possible.
 A list of tested compilers which are currently not working and the respective issue are listed below.
 
@@ -132,7 +150,7 @@ To test your build, run the test suite after the build has finished with
 cmake --build build --target test
 ```
 
-Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details on the compiler used, the operating system and platform architecture.
+Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details of the compiler used, the operating system and platform architecture.
 
 To install the project to the declared prefix run
 
@@ -158,6 +176,36 @@ make -f Makefile.manual FYPPFLAGS=-DMAXRANK=4
 ```
 
 
+
+## Using stdlib in your project
+
+The stdlib project exports CMake package files and pkg-config files to make stdlib usable for other projects.
+The package files are located in the library directory in the installation prefix.
+
+For CMake builds of stdlib you can find a local installation with
+
+```cmake
+find_package(fortran_stdlib REQUIRED)
+...
+target_link_libraries(
+  ${PROJECT_NAME}
+  PRIVATE
+  fortran_stdlib::fortran_stdlib
+)
+```
+
+To make the installed stdlib project discoverable add the stdlib directory to the ``CMAKE_PREFIX_PATH``.
+The usual install localtion of the package files is ``$PREFIX/lib/cmake/fortran_stdlib``.
+
+For non-CMake build systems (like make) you can use the exported pkg-config file by setting ``PKG_CONFIG_PATH`` to include the directory containing the exported pc-file.
+The usual install location of the pc-file is ``$PREFIX/lib/pkgconfig``.
+In make you can obtain the required compile and link arguments with
+
+```make
+STDLIB_CFLAGS := $(shell pkg-config --cflags fortran_stdlib)
+STDLIB_LIBS := $(shell pkg-config --libs fortran_stdlib)
+```
+
 ## Documentation
 
 Documentation is a work in progress (see issue [#4](https://github.com/fortran-lang/stdlib/issues/4)) but already available at [stdlib.fortran-lang.org](https://stdlib.fortran-lang.org).

STYLE_GUIDE.md

@@ -47,7 +47,7 @@ focus on the semantics of the proposed changes rather than style and formatting.
 <!-- ATTENTION! This section includes intentional trailing whitespace to get decent formatting with GFM and Python Markdown. -->
 
 * Always specify `intent` for dummy arguments.
-* Don't use `dimension` attribute to declare arrays because it is less verbose.
+* Don't use `dimension` attribute to declare arrays because it is more verbose.
   Use this:  
   ```
   real, allocatable :: a(:), b(:,:)

config/CMakeLists.txt

@@ -0,0 +1,40 @@
+# SPDX-Identifier: MIT
+
+# Export a pkg-config file
+configure_file(
+  "${CMAKE_CURRENT_SOURCE_DIR}/template.pc"
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc"
+  @ONLY
+)
+install(
+  FILES
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc"
+  DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig"
+)
+
+# Export CMake package file
+include(CMakePackageConfigHelpers)
+configure_package_config_file(
+  "${CMAKE_CURRENT_SOURCE_DIR}/template.cmake"
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
+  INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
+)
+if(BUILD_SHARED_LIBS OR PROJECT_VERSION_MAJOR EQUAL 0)
+  # Due to the uncertain ABI compatibility of Fortran shared libraries
+  # limit compatibility for dynamic linking to same minor version.
+  set(COMPATIBILITY SameMinorVersion)
+else()
+  # Require API compatibility via semantic versioning for static linking.
+  set(COMPATIBILITY SameMajorVersion)
+endif()
+write_basic_package_version_file(
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake"
+  VERSION "${PROJECT_VERSION}"
+  COMPATIBILITY ${COMPATIBILITY}
+)
+install(
+  FILES
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake"
+  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
+)

config/template.cmake

@@ -0,0 +1,5 @@
+@PACKAGE_INIT@
+
+if(NOT TARGET "@PROJECT_NAME@::@PROJECT_NAME@")
+  include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@-targets.cmake")
+endif()

config/template.pc

@@ -0,0 +1,9 @@
+prefix=@CMAKE_INSTALL_PREFIX@
+libdir=${prefix}/@CMAKE_INSTALL_LIBDIR@
+includedir=${prefix}/@CMAKE_INSTALL_INCLUDEDIR@
+
+Name: @PROJECT_NAME@
+Description: @PROJECT_DESCRIPTION@
+Version: @PROJECT_VERSION@
+Libs: -L${libdir} -l@PROJECT_NAME@
+Cflags: -I${includedir}

doc/specs/index.md

@@ -11,6 +11,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
 
 ## Experimental Features & Modules
 
+ - [ascii](./stdlib_ascii.html) - Procedures for handling ASCII characters
  - [bitsets](./stdlib_bitsets.html) - Bitset data types and procedures
  - [error](./stdlib_error.html) - Catching and handling errors
  - [IO](./stdlib_io.html) - Input/output helper & convenience
@@ -19,10 +20,11 @@ This is and index/directory of the specifications (specs) for each new module/fe
  - [optval](./stdlib_optval.html) - Fallback value for optional arguments
  - [quadrature](./stdlib_quadrature.html) - Numerical integration
  - [stats](./stdlib_stats.html) - Descriptive Statistics
+ - [stats_distribution_PRNG](./stdlib_stats_distribution_PRNG.html) - Probability Distributions random number generator
+ - [string\_type](./stdlib_string_type.html) - Basic string support
 
 ## Missing specs
 
- - [ascii](https://github.com/fortran-lang/stdlib/blob/master/src/stdlib_ascii.f90)
  - [kinds](https://github.com/fortran-lang/stdlib/blob/master/src/stdlib_kinds.f90)
 
 ## Released/Stable Features & Modules

doc/specs/stdlib_ascii.md

@@ -0,0 +1,171 @@
+---
+title: ASCII
+---
+
+# The `stdlib_ascii` module
+
+[TOC]
+
+## Introduction
+
+The `stdlib_ascii` module provides procedures for handling and manipulating
+intrinsic character variables and constants.
+
+
+## Constants provided by `stdlib_ascii`
+
+@note Specification of constants is currently incomplete.
+
+
+## Specification of the `stdlib_ascii` procedures
+
+@note Specification of procedures is currently incomplete.
+
+
+### `to_lower`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Converts input character variable to all lowercase.
+
+#### Syntax
+
+`res = [[stdlib_ascii(module):to_lower(function)]] (string)`
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+#### Example
+
+```fortran
+program demo_to_lower
+    use stdlib_ascii, only : to_lower
+    implicit none
+    print'(a)', to_lower("HELLo!") ! returns "hello!"
+ end program demo_to_lower
+``` 
+
+### `to_upper`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Converts input character variable to all uppercase.
+
+#### Syntax
+
+`res = [[stdlib_ascii(module):to_upper(function)]] (string)`
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+#### Example
+
+```fortran
+program demo_to_upper
+    use stdlib_ascii, only : to_upper
+    implicit none
+    print'(a)', to_upper("hello!") ! returns "HELLO!"
+ end program demo_to_upper
+``` 
+
+### `to_title`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Returns a capitalized version of an input character variable.
+The first alphabetical character is transformed to uppercase unless it follows a numeral.
+The rest of the character sequence is transformed to lowercase.
+
+#### Syntax
+
+`res = [[stdlib_ascii(module):to_title(function)]] (string)`
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+#### Example
+
+```fortran
+program demo_to_title
+    use stdlib_ascii, only : to_title
+    implicit none
+    print*, to_title("hello!") ! returns "Hello!"
+    print*, to_title("'enquoted'") ! returns "'Enquoted'"
+    print*, to_title("1st")  ! returns "1st"
+ end program demo_to_title
+``` 
+
+### `reverse`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Reverses the order of all characters in the input character type.
+
+#### Syntax
+
+`res = [[stdlib_ascii(module):reverse(function)]] (string)`
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+#### Example
+
+```fortran
+program demo_reverse
+    use stdlib_ascii, only : reverse
+    implicit none
+    print'(a)', reverse("Hello, World!") ! returns "!dlroW ,olleH"
+end program demo_reverse
+```