Merge pull request #112 from zbeekman/documentation-fixes

Documentation fixes & coverage improvements

Author: jacobwilliams

CONTRIBUTING.md

@@ -32,6 +32,19 @@ Looking to contribute something to [json-fortran](README.md)? **Here's how you c
 ## Outstanding Work
 
 - Take a look at the [issues](https://github.com/jacobwilliams/json-fortran/issues) to see if there is an issue you'd like to help address. [Issues](https://github.com/jacobwilliams/json-fortran/issues) with the [ready label](https://github.com/jacobwilliams/json-fortran/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready%22) or in the [ready column on waffle.io](https://waffle.io/jacobwilliams/json-fortran) are issues that are ready to be dealt with. (i.e., They are not blocked by other dependencies and are higher priority.)
+- Increasing the test coverage is another helpful way to
+  contribute. Please take a look at
+  [this wiki page](https://github.com/jacobwilliams/json-fortran/wiki/Coverage-Analysis)
+  for a list of uncovered procedures, and at the
+  [Codecov.io suggestions page](https://codecov.io/github/jacobwilliams/json-fortran/features/suggestions)
+  to find procedures and lines of code that are still uncovered by the
+  [unit tests](https://github.com/jacobwilliams/json-fortran/tree/master/src/tests). It
+  is worth pointing out that the majority of uncovered procedures are
+  internal, overloaded procedures and can only be exercised by calling
+  the corresponding generic procedure with input arguments that will
+  resolve to the specific procedure in question. Let's keep the
+  following graph trending upwards!
+  ![Codecov.io](http://codecov.io/github/jacobwilliams/json-fortran/branch.svg?branch=master)
 
 [top](#contributing-to-json-fortran)
 ## Pull Requests
@@ -40,7 +53,7 @@ Looking to contribute something to [json-fortran](README.md)? **Here's how you c
 - Pull requests should address one issue at a time, and each commit should be a set of self contained, related changes. If you forget something in a commit, please use `git rebase -i <ref>^` to amend and/or squash erroneous commits. Here `<ref>` is the reference to to oldest commit needing to be modified (SHA, or `HEAD~4`, etc.)
 - Each commit should compile, and ideally pass the tests. Very complicated new features or fixes, may have commits that don't pass tests, if otherwise the commit history would include far to many changes in any given commit. Use an interactive rebase to fix any of these issues, as described above.
 - Pull requests should always be based on the upstream master,
-jacobwilliams/json-fortran:master. Please `rebase` your branch on top
+`jacobwilliams/json-fortran:master`. Please `rebase` your branch on top
 of the latest upstream master. Assuming you are on your branch and you've added the upstream remote by running something like:
 ```
 git remote add upstream git://github.com/jacobwilliams/json-fortran.git
@@ -60,6 +73,19 @@ git rebase upstream/master
 - Each commit should address a single logical change and code base transformation.
 - Each commit **must** compile.
 - Each commit should pass the tests unless the feature being implemented or bug being fixed requires extensive changes that would result in a commit with too many different changes.
+- Each pull request should ensure that the proper unit tests have
+  been added to cover at least 90% of new or changed code and that the
+  overall coverage continues to increase.
+- New tests are added to the `src/tests` directory and are named
+  `jf_test_<#>.[Ff]90`. Each test is a stand alone Fortran program
+  which will automatically be compiled and linked against the
+  json-fortran library so long as it follows this naming
+  convention. If any of the tests fail, the test program should exit
+  with a non-zero return status, using the `stop 2` intrinsic
+  statement. (The Fortran standard does not require the 'processor' to
+  have or set a return value, but in practice all compilers respect
+  this convention. An integer other than `2` may be used, so long as
+  it is non-zero and supported by the processor.)
 - No extraneous white spaces are allowed to be introduced at line endings and all non binary files should end with a single new line. Run `git config core.whitespace trailing-space,space-before-tab,blank-at-eol,blank-at-eof` to setup the whitespace rules from within your fork, and then check for white space errors with `git diff --check` to see if you have accidentally introduced white space errors before committing. (You can also enable the sample `pre-commit` hook that ships with git, to prevent you from committing changes that introduce white space errors. See [this stackoverflow question](http://stackoverflow.com/questions/591923/make-git-automatically-remove-trailing-whitespace-before-committing/28446440)) for some tips on preventing the introduction of whitespace errors.
 - Please adhere to the code indentation and formatting as it currently exists, aligning common elements vertically, etc. Tab characters are not allowed. Indentations should be done with *4* space characters.
 - *Do NOT* allow your editor to make a bunch of indentation or white space changes, that will introduce non-substantive changes on lines that you have not actually edited.

README.md

@@ -54,7 +54,7 @@ __NEWS:__ As of June 7, 2015,
 downloaded and installed with the [homebrew](https://brew.sh) package
 manager on Mac OS X. Once [homebrew](https://brew.sh) is installed,
 make sure that the formulae are up to date, view the package options
-and caveates, and install the
+and caveats, and install the
 [json-fortran formula](http://braumeister.org/formula/json-fortran):
 
 ```bash
@@ -170,7 +170,7 @@ Reading JSON from a string
 ---------------
 JSON can also be read directly from a character string like so:
 ```fortran
-    call json%load_from_string('{"name", "Leonidas"}')
+    call json%load_from_string('{"name": "Leonidas"}')
 ```
 
 Modifying variables in a JSON file
@@ -281,7 +281,7 @@ The API documentation for the latest release version can be found [here](http://
 [top](#json-fortran-)
 Contributing [![Ready in backlog](https://badge.waffle.io/jacobwilliams/json-fortran.png?label=Ready&title=Ready)](CONTRIBUTING.md)
 ------------
-Want to help?  Take a quick look at our [contributing guidelines](CONTRIBUTING.md) then claim something in [the "ready" column on our Waffle.io](https://waffle.io/jacobwilliams/json-fortran) and [Fork. Commit. Pull request.](https://help.github.com/articles/fork-a-repo).
+Want to help?  Take a quick look at our [contributing guidelines](CONTRIBUTING.md) then claim something in [the "ready" column on our Waffle.io](https://waffle.io/jacobwilliams/json-fortran) and [Fork. Commit. Pull request.](https://help.github.com/articles/fork-a-repo)
 
 [top](#json-fortran-)
 License

src/json_module.F90

@@ -7599,32 +7599,6 @@ subroutine parse_string(unit, str, string)
     end subroutine parse_string
 !*****************************************************************************************
 
-!*****************************************************************************************
-!.... gfortran bug ..... some problem.....
-!*****************************************************************************************
-    pure subroutine add_character_to_string(str,ip,c)
-
-    implicit none
-
-    character(kind=CK,len=:),allocatable,intent(inout) :: str
-    integer(IK),intent(inout) :: ip
-    character(kind=CK,len=1),intent(in) :: c
-
-    if (allocated(str)) then
-        !resize string if necessary:
-        if (ip>len(str)) str = str // repeat(space, chunk_size)
-    else
-        str = repeat(space, chunk_size)
-        ip = 1
-    end if
-
-    !append to string:
-    str(ip:ip) = c
-    ip = ip + 1
-
-    end subroutine add_character_to_string
-!*****************************************************************************************
-
 !*****************************************************************************************
 !****if* json_module/parse_for_chars
 !

src/tests/jf_test_7.f90

@@ -63,8 +63,12 @@ subroutine test_7(error_cnt)
 
     integer,intent(out) :: error_cnt
 
-    type(json_value),pointer :: root,a,b,c,d,e,e1,e2,escaped_string
+    type(json_value),pointer :: root,a,b,c,d,e,e1,e2,escaped_string,p
+    logical :: found
+    character(kind=CK,len=1), dimension(:), allocatable :: strvec
+    character(kind=CK,len=:), allocatable :: string
 
+    found=.false.
     error_cnt = 0
     call json_initialize()
     if (json_failed()) then
@@ -140,6 +144,12 @@ subroutine test_7(error_cnt)
         call json_print_error_message(error_unit)
         error_cnt = error_cnt + 1
     end if
+    call json_get_child(a,'chars',p)
+    call json_get(p,strvec)
+    if (json_failed()) then
+        call json_print_error_message(error_unit)
+        error_cnt = error_cnt + 1
+    end if
     call json_create_object(c,'c')
     if (json_failed()) then
         call json_print_error_message(error_unit)
@@ -201,23 +211,6 @@ subroutine test_7(error_cnt)
         call json_print_error_message(error_unit)
         error_cnt = error_cnt + 1
     end if
-        call json_create_object(escaped_string,'escaped string')
-    if (json_failed()) then
-        call json_print_error_message(error_unit)
-        error_cnt = error_cnt + 1
-    end if
-    call json_add(escaped_string,'escaped string',&
-         '\/'//&
-         achar(8)//&
-         achar(12)//&
-         achar(10)//&
-         achar(13)//&
-         achar(9))
-    if (json_failed()) then
-        call json_print_error_message(error_unit)
-        error_cnt = error_cnt + 1
-    end if
-
     call json_add(root,a)
     if (json_failed()) then
         call json_print_error_message(error_unit)
@@ -243,7 +236,19 @@ subroutine test_7(error_cnt)
         call json_print_error_message(error_unit)
         error_cnt = error_cnt + 1
     end if
-    call json_add(root,escaped_string)
+    call json_add(root,'escaped string',&
+         '\/'//&
+         achar(8)//&
+         achar(12)//&
+         achar(10)//&
+         achar(13)//&
+         achar(9))
+    if (json_failed()) then
+        call json_print_error_message(error_unit)
+        error_cnt = error_cnt + 1
+    end if
+    call json_add(root,'wacky string',['trim   ','  and  ',' adjust','   left'],&
+         trim_str=.true.,adjustl_str=.true.)
     if (json_failed()) then
         call json_print_error_message(error_unit)
         error_cnt = error_cnt + 1
@@ -263,6 +268,21 @@ subroutine test_7(error_cnt)
         call json_print_error_message(error_unit)
         error_cnt = error_cnt + 1
     end if
+    ! look for the 'escaped string' entry
+    call json_get(root,'escaped string',escaped_string,found)
+    if (json_failed() .or. .not. found) then
+        call json_print_error_message(error_unit)
+        error_cnt = error_cnt + 1
+    end if
+    call json_get(escaped_string,string)
+    if (json_failed()) then
+        call json_print_error_message(error_unit)
+        error_cnt = error_cnt + 1
+    end if
+    write(error_unit,'(A)') "Fetched unescaped 'escaped string': "//string
+
+    ! remove the escaped string entry
+    if (found) call json_remove(escaped_string,destroy=.true.)
     call json_print(root,error_unit)  !print to stderr
     if (json_failed()) then
         call json_print_error_message(error_unit)