Extraction of the demo programs from the specs

CMakeLists.txt

@@ -71,6 +71,7 @@ add_subdirectory(src)
 if(BUILD_TESTING)
   enable_testing()
   add_subdirectory(test)
+  add_subdirectory(example)
 endif()
 
 install(EXPORT ${PROJECT_NAME}-targets

README.md

@@ -149,12 +149,17 @@ To build the standard library run
 cmake --build build
 ```
 
-To test your build, run the test suite after the build has finished with
+To test your build, run the test suite and all example programs after the build has finished with
 
 ```sh
 cmake --build build --target test
 ```
 
+To test only the test suite, run
+```sh
+ctest --test-dir build/test
+```
+
 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
@@ -179,6 +184,15 @@ git checkout stdlib-fpm
 fpm build --profile release
 ```
 
+You can run the examples with `fpm` as:
+
+```sh
+fpm run --example prog
+```
+
+with `prog` being the name of the example program (e.g., `example_sort`).
+
+
 To use `stdlib` within your `fpm` project, add the following lines to your `fpm.toml` file:
 ```toml
 [dependencies]

ci/fpm-deployment.sh

@@ -39,7 +39,7 @@ minor=$(cut -d. -f2 VERSION)
 patch=$(cut -d. -f3 VERSION)
 fyflags="${fyflags} -DPROJECT_VERSION_MAJOR=${major} -DPROJECT_VERSION_MINOR=${minor} -DPROJECT_VERSION_PATCH=${patch}"
 
-mkdir -p "$destdir/src" "$destdir/test"
+mkdir -p "$destdir/src" "$destdir/test" "$destdir/example"
 
 # Preprocess stdlib sources
 find src -maxdepth 1 -iname "*.fypp" \
@@ -49,6 +49,7 @@ find src -maxdepth 1 -iname "*.fypp" \
 find src -maxdepth 1 -iname "*.f90" -exec cp {} "$destdir/src/" \;
 find test -name "test_*.f90" -exec cp {} "$destdir/test/" \;
 find test -name "*.dat" -exec cp {} "$destdir/" \;
+find example -name "example_*.f90" -exec cp {} "$destdir/example/" \;
 
 # Include additional files
 cp "${include[@]}" "$destdir/"

doc/specs/stdlib_array.md

@@ -46,14 +46,7 @@ Returns an array of default integer size, with a maximum length of `size(array)`
 #### Examples
 
 ```fortran
-program demo_trueloc
-  use stdlib_array, only : trueloc
-  implicit none
-  real, allocatable :: array(:)
-  allocate(array(500))
-  call random_number(array)
-  array(trueloc(array > 0.5)) = 0.0
-end program demo_trueloc
+{!example/array/example_trueloc.f90!}
 ```
 
 
@@ -90,12 +83,5 @@ Returns an array of default integer size, with a maximum length of `size(array)`
 #### Examples
 
 ```fortran
-program demo_falseloc
-  use stdlib_array, only : falseloc
-  implicit none
-  real, allocatable :: array(:)
-  allocate(array(-200:200))
-  call random_number(array)
-  array(falseloc(array < 0.5), lbound(array)) = 0.0
-end program demo_falseloc
+{!example/array/example_falseloc.f90!}
 ```

doc/specs/stdlib_ascii.md

@@ -51,11 +51,7 @@ 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
+{!example/ascii/example_ascii_to_lower.f90!}
 ``` 
 
 ### `to_upper`
@@ -87,11 +83,7 @@ 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
+{!example/ascii/example_ascii_to_upper.f90!}
 ```
 
 ### `to_title`
@@ -128,13 +120,7 @@ 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 there!") ! returns "Hello There!"
-    print*, to_title("'enquoted'") ! returns "'Enquoted'"
-    print*, to_title("1st")  ! returns "1st"
- end program demo_to_title
+{!example/ascii/example_ascii_to_title.f90!}
 ```
 
 ### `to_sentence`
@@ -169,13 +155,7 @@ The result is an intrinsic character type of the same length as `string`.
 #### Example
 
 ```fortran
-program demo_to_sentence
-    use stdlib_ascii, only : to_sentence
-    implicit none
-    print*, to_sentence("hello!") ! returns "Hello!"
-    print*, to_sentence("'enquoted'") ! returns "'Enquoted'"
-    print*, to_sentence("1st")  ! returns "1st"
- end program demo_to_sentence
+{!example/ascii/example_ascii_to_sentence.f90!}
 ```
 
 ### `reverse`
@@ -207,9 +187,5 @@ 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
+{!example/ascii/example_ascii_reverse.f90!}
 ```