cleanup of read/write API names (now have print, load, serialize, and deserialize for both json_core and json_file). Fixes #397. The old ones are still there for backward compatibility.

added a json_core print to console routine. Fixes #408

Author: jacobwilliams

src/json_file_module.F90

@@ -48,17 +48,18 @@ module json_file_module
     !    character(len=:),allocatable :: cval
     !    logical :: found
     !    call json%initialize(compact_reals=.true.)
-    !    call json%load_file(filename='myfile.json')
-    !    call json%print_file() !print to the console
+    !    call json%load(filename='myfile.json')
+    !    call json%print() !print to the console
     !    call json%get('var.i',ival,found)
     !    call json%get('var.r(3)',rval,found)
     !    call json%get('var.c',cval,found)
     !    call json%destroy()
     !    end program test
     !```
     !
-    !@warning The `destroy()` method must be called before the variable
-    !         goes out of scope or a memory leak will occur.
+    !@note The `destroy()` method may be called to free the memory, but
+    !      [[json_file(type)]] includes a finalizer that also calls
+    !      `destroy()` when the variable goes out of scope.
 
     type,public :: json_file
 
@@ -75,8 +76,16 @@ module json_file_module
 
         procedure,public :: get_core => get_json_core_in_file
 
+        procedure,public :: load => json_file_load
+
+        !>
+        !  The same as `load`, but only here for backward compatibility
         procedure,public :: load_file => json_file_load
 
+        generic,public :: serialize => MAYBEWRAP(json_file_load_from_string)
+
+        !>
+        !  The same as `serialize`, but only here for backward compatibility
         generic,public :: load_from_string => MAYBEWRAP(json_file_load_from_string)
 
         procedure,public :: destroy => json_file_destroy
@@ -91,11 +100,23 @@ module json_file_module
         procedure,public :: check_for_errors => json_file_check_for_errors
         procedure,public :: clear_exceptions => json_file_clear_exceptions
 
+        !>
+        !  Print the [[json_value]] structure to an allocatable string
+        procedure,public :: deserialize => json_file_print_to_string
+
+        !>
+        !  The same as `deserialize`, but only here for backward compatibility
         procedure,public :: print_to_string => json_file_print_to_string
 
+        generic,public :: print => json_file_print_to_console, &
+                                   json_file_print_to_unit, &
+                                   json_file_print_to_filename
+
+        !>
+        !  The same as `print`, but only here for backward compatibility
         generic,public :: print_file => json_file_print_to_console, &
-                                        json_file_print_1, &
-                                        json_file_print_2
+                                        json_file_print_to_unit, &
+                                        json_file_print_to_filename
 
         !>
         !  Rename a variable, specifying it by path
@@ -150,7 +171,7 @@ module json_file_module
         !  call f%add('inputs.t', 0.0_rk)
         !  call f%add('inputs.x', [1.0_rk,2.0_rk,3.0_rk])
         !  call f%add('inputs.flag', .true.)
-        !  call f%print_file()
+        !  call f%print()  ! print to the console
         !  end program test
         !```
         generic,public :: add => json_file_add, &
@@ -321,10 +342,10 @@ module json_file_module
         !remove:
         procedure :: MAYBEWRAP(json_file_remove)
 
-        !print_file:
+        !print:
         procedure :: json_file_print_to_console
-        procedure :: json_file_print_1
-        procedure :: json_file_print_2
+        procedure :: json_file_print_to_unit
+        procedure :: json_file_print_to_filename
 
         final :: finalize_json_file
 
@@ -620,7 +641,7 @@ function initialize_json_file_from_string(str,&
     call file_object%initialize(&
 #include "json_initialize_dummy_arguments.inc"
                                )
-    call file_object%load_from_string(str)
+    call file_object%serialize(str)
 
     end function initialize_json_file_from_string
 !*****************************************************************************************
@@ -664,7 +685,7 @@ function initialize_json_file_from_string_v2(str, json_core_object) &
     type(json_core),intent(in)          :: json_core_object
 
     file_object%core = json_core_object
-    call file_object%load_from_string(str)
+    call file_object%serialize(str)
 
     end function initialize_json_file_from_string_v2
 !*****************************************************************************************
@@ -719,7 +740,7 @@ end subroutine json_file_nullify
 !> author: Jacob Williams
 !
 !  Destroy the [[json_value]] data in a [[json_file(type)]].
-!  This must be done when the variable is no longer needed,
+!  This may be done when the variable is no longer needed,
 !  or will be reused to open a different file.
 !  Otherwise a memory leak will occur.
 !
@@ -804,7 +825,7 @@ end subroutine json_file_move_pointer
 !      use json_module
 !      implicit none
 !      type(json_file) :: f
-!      call f%load_file('my_file.json')
+!      call f%load('my_file.json')
 !      !...
 !      call f%destroy()
 !     end program main
@@ -820,7 +841,7 @@ subroutine json_file_load(me, filename, unit)
                                                       !! (if not present, a newunit
                                                       !! is used)
 
-    call me%core%parse(file=filename, p=me%p, unit=unit)
+    call me%core%load(file=filename, p=me%p, unit=unit)
 
     end subroutine json_file_load
 !*****************************************************************************************
@@ -836,7 +857,7 @@ end subroutine json_file_load
 !  Load JSON from a string:
 !```fortran
 !     type(json_file) :: f
-!     call f%load_from_string('{ "name": "Leonidas" }')
+!     call f%serialize('{ "name": "Leonidas" }')
 !```
 
     subroutine json_file_load_from_string(me, str)
@@ -846,7 +867,7 @@ subroutine json_file_load_from_string(me, str)
     class(json_file),intent(inout)      :: me
     character(kind=CK,len=*),intent(in) :: str  !! string to load JSON data from
 
-    call me%core%parse(str=str, p=me%p)
+    call me%core%load(str=str, p=me%p)
 
     end subroutine json_file_load_from_string
 !*****************************************************************************************
@@ -862,7 +883,7 @@ subroutine wrap_json_file_load_from_string(me, str)
     class(json_file),intent(inout)       :: me
     character(kind=CDK,len=*),intent(in) :: str
 
-    call me%load_from_string(to_unicode(str))
+    call me%serialize(to_unicode(str))
 
     end subroutine wrap_json_file_load_from_string
 !*****************************************************************************************
@@ -890,7 +911,7 @@ end subroutine json_file_print_to_console
 !
 !  Prints the JSON file to the specified file unit number.
 
-    subroutine json_file_print_1(me, iunit)
+    subroutine json_file_print_to_unit(me, iunit)
 
     implicit none
 
@@ -900,10 +921,10 @@ subroutine json_file_print_1(me, iunit)
     if (iunit/=unit2str) then
         call me%core%print(me%p,iunit=iunit)
     else
-        call me%core%throw_exception('Error in json_file_print_1: iunit must not be -1.')
+        call me%core%throw_exception('Error in json_file_print_to_unit: iunit must not be -1.')
     end if
 
-    end subroutine json_file_print_1
+    end subroutine json_file_print_to_unit
 !*****************************************************************************************
 
 !*****************************************************************************************
@@ -919,12 +940,12 @@ end subroutine json_file_print_1
 !```fortran
 !     type(json_file) :: f
 !     logical :: found
-!     call f%load_file('my_file.json')    !open the original file
-!     call f%update('version',4,found)    !change the value of a variable
-!     call f%print_file('my_file_2.json') !save file as new name
+!     call f%load('my_file.json')       !open the original file
+!     call f%update('version',4,found)  !change the value of a variable
+!     call f%print('my_file_2.json')    !save file as new name
 !```
 
-    subroutine json_file_print_2(me,filename)
+    subroutine json_file_print_to_filename(me,filename)
 
     implicit none
 
@@ -933,7 +954,7 @@ subroutine json_file_print_2(me,filename)
 
     call me%core%print(me%p,filename)
 
-    end subroutine json_file_print_2
+    end subroutine json_file_print_to_filename
 !*****************************************************************************************
 
 !*****************************************************************************************
@@ -948,8 +969,8 @@ end subroutine json_file_print_2
 !```fortran
 !     type(json_file) :: f
 !     character(kind=CK,len=:),allocatable :: str
-!     call f%load_file('my_file.json')
-!     call f%print_file(str)
+!     call f%load('my_file.json')
+!     call f%deserialize(str)
 !```
 
     subroutine json_file_print_to_string(me,str)
@@ -959,7 +980,7 @@ subroutine json_file_print_to_string(me,str)
     class(json_file),intent(inout)                   :: me
     character(kind=CK,len=:),allocatable,intent(out) :: str  !! string to print JSON data to
 
-    call me%core%print_to_string(me%p,str)
+    call me%core%deserialize(me%p,str)
 
     end subroutine json_file_print_to_string
 !*****************************************************************************************