doc+check: added documentation and checks

- Cleaned up readme.md for easier reference.

- enabled checks using make check/test

- Added license header in the .inc and .F90 files

- Added travis build system

- I had created filter.sed, but forgotten to add it

- The tests for memory where using towards 2 Gb of memory
  I have cut it down to 1 Gb to limit the requiremente of the
  hardware.

- added default .arch.make file

- add quick_test.sh which runs the make check using the
  .arch.make file.

.arch.make

@@ -0,0 +1,9 @@
+FC=gfortran
+FFLAGS = -g
+
+.F90.o:
+	$(FC) -c $(INC) $(FFLAGS) $<
+
+.f90.o:
+	$(FC) -c $(INC) $(FFLAGS) $<
+

.travis.yml

@@ -0,0 +1,18 @@
+language: fortran
+
+notifications:
+   email:
+      recipients:
+         - [email protected]
+      on_failure: always
+      on_success: change
+
+before_install:
+   - ln -s .arch.make arch.make
+   - sudo apt-get install -qq gfortran
+
+install:
+   - make
+
+script:
+   - make check

Makefile

@@ -34,6 +34,8 @@ $(LIB): $(OBJS)
 	$(RANLIB) $(LIB)
 
 .PHONY: test
+.PHONY: check
+check: test
 test: lib
 	$(MAKE) -C test
 

README.md

@@ -1,17 +1,56 @@
-fdict
-====
+# fdict #
 
-Supplying a variable and dictionary module which does not restrict the type used.
+A variable and dictionary in pure fortran for retaining any data-type
+and a fast hash-table dictionary.
 
+## Usage ##
 
-Type free variable
-==================
+This module consists of two separate modules which co-exist for
+maintenance and usage reasons.
+
+First, the variable module which is a type-free variable that can contain
+any variable type, and any dimension as well.
+
+Second, the dictionary module which contains a hash-table of variables
+that can contain _any_ data-type allowed by the variable module.
+
+## Downloading and installation ##
+
+Installing fdict requires a download of the library 
+hosted at [github](https://github.com/) at [fdict@git].
+
+Extract and create an `arch.make` file for compilation, a minimal
+`arch.make` file can look like this
+
+	FC=gfortran
+	FFLAGS = -g
+
+	.F90.o:
+	    $(FC) -c $(INC) $(FFLAGS) $<
+
+	.f90.o:
+	    $(FC) -c $(INC) $(FFLAGS) $<
+
+Type `make` and a library called `libvardict.a` is created.
+
+To use the dictionary you need to add include statements for the
+modules as well as linking to the program.
+
+To link fdict to your program the following can be used in a `Makefile`
+
+    FDICT_PATH  = /path/to/fdict/parent
+    FDICT_LIBS  = -L$(FDICT_PATH) -lvardict
+    FDICT_INC   = -I$(FDICT_PATH)
+
+
+### variable ###
 
 Using this module one gains access to a generic type variable which
-can contain *any* data format.
+can contain _any_ data format.
 
 Basically it is used like this:
 ```
+use variable
 integer :: a(3)
 type(var) :: v
 a = 2
@@ -21,7 +60,7 @@ call assign(a,v)
 ```
 
 Also the variable contains an abbreviation for assigning pointers to 
-not copy data, but retain data locality.
+not copy data, but retain data locality:
 ```
 integer, target :: a(3)
 type(var) :: v
@@ -33,32 +72,36 @@ a = 3
 
 To delete a variable one simply does:
 ```
+use variable
 type(var) :: v
 call delete(v)
 ```
 However, when the variable is using pointers, instead the user can do
 ```
+use variable
 type(var) :: v
 call delete(v,dealloc=.false.)
+! or
+call nullify(v)
 ```
 which merely destroys the variable object and thus retains the data
 where it is. As with any other pointer arithmetic it is up to the programmer
 to ensure no memory leaks.
 
 
-Dictionary
-==========
+### dictionary ###
 
-Using the `type(var)` it becomes easy to create dictionaries in fortran.
+Using `type(var)` it becomes easy to create dictionaries in fortran.
 
-Using this module we implement a dictionary which can contain *any* data
+Using this module we implement a dictionary which can contain _any_ data
 format using a `key:val` based formalism. The underlying data structure is a
 linked list sorted according to hash-values of the keys. Hence searching 
-for specific elements in the dictionary is *extremely* fast. Concatenating 
+for specific elements in the dictionary is _extremely_ fast. Concatenating 
 dictionaries is also very fast.
 
 Creating a dictionary is almost as easy as the Python equivalent:
 ```
+use dictionary
 type(dict) :: dic
 dic = ('KEY'.kv.1)
 ```
@@ -76,16 +119,52 @@ r = 4
 ```
 will change the value in the dictionary.
 
-Note that the dictionary can also contain *any* data type.
+Note that the dictionary can also contain _any_ data type.
+
 However, if it needs to do custom data-types the programmer needs to
 extend the code by supplying a few custom routines.
 
 Intrinsically the dictionary can contain dictionaries by this:
 ```
+use dictionary
 type(dict) :: d1, d2
 d1 = ('hello'.kv.'world')
 d2 = ('hello'.kv.'world')
-d1 = d1 // ('dict'.kv.d2)
+d1 = d1 // ('dict'.kvp.d2)
 ```
-But it will be up to the user to *know* the key for data types other than
-integers, reals, complex numbers and characters.
+But it will be up to the user to _know_ the key for data types other than
+integers, reals, complex numbers and characters.
+
+Note that the dictionary contained is passed by reference, and thus
+if you delete `d2`, you will have a dangling pointer in `d1`.
+
+
+## Contributions, issues and bugs ##
+
+I would advice any users to contribute as much feedback and/or PRs to further
+maintain and expand this library.
+
+Please do not hesitate to contribute!
+
+If you find any bugs please form a [bug report/issue][issue].
+
+If you have a fix please consider adding a [pull request][pr].
+
+
+## License ##
+
+The fdict license is [lgpl], see the LICENSE file.
+
+## Thanks ##
+
+A big thanks goes to Alberto Garcia for contributing ideas and given
+me bug-reports.
+
+<!---
+Links to external and internal sites.
+-->
+[fdict@git]: https://github.com/zerothi/fdict
+<!-- [fdict-doc]: https://github.com/zerothi/fdict/wiki -->
+[issue]: https://github.com/zerothi/fdict/issues
+[pr]: https://github.com/zerothi/fdict/pulls
+[lgpl]: http://www.gnu.org/licenses/lgpl.html

dict_funcs_inc.inc

@@ -1,3 +1,6 @@
+#ifdef COMMENTS
+! @LICENSE@, see README.md
+#endif
 function ROUTINE(dict_kv,VAR)(key,val) result(this)
 character(len=*), intent(in) :: key
 VAR_TYPE, intent(in)DIMS :: val

dictionary_pp.F90

@@ -1,3 +1,5 @@
+! @LICENSE@, see README.md
+
 ! A simple dictionary module for a key-value based system...
 ! 
 ! This module has entirely been created by:

filter.sed

@@ -0,0 +1,27 @@
+# Replace the marker NEWLINE by a '\n' character.
+# This will work in Linux and OSX. *Keep it in two lines!*
+s/NEWLINE/\
+/g
+# Basically the following commands translates
+# pre-processors within another preprocessor
+# which isn't allowed.
+# Hence a small workaround is needed.
+#
+# This is for removing empty and comment lines
+/^$$/d;/^\!.*&/d
+#
+# This is for removing double hash and too much space
+# Strictly not needed
+s/[[:space:]]*\#\#[[:space:]]*\([^[:space:]]*\)/\1/g
+#
+# This is for changing the include statements
+# to direct include statements, certain platforms
+# requires you to do this kind of trick :(
+s/[[:space:]]*\#\([^i][^[:space:]]*\)/"\1"/g
+#
+# This is for translating direct endif statements to
+# preprocessor statements
+#s/"endif"/\n\#endif/g
+s/"endif"/\
+\#endif/g
+

quick_test.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# Create link from .arch.make to
+# arch.make
+
+_old_arch=
+if [ -L arch.make ]; then
+    # We assume the arch.make is 
+    # a link to .arch.make
+    # Simply delete it, we will re-instantiate it
+    rm arch.make
+elif [ -e arch.make ]; then
+    _old_arch=.temporary_arch.make
+    mv arch.make $_old_arch
+fi
+
+# Create link to arch.make
+ln -s .arch.make arch.make
+
+# call make...
+make clean
+make
+make check
+
+if [ -z "$_old_arch" ]; then
+    # the link should sustain,
+    # it still links to .arch.make
+    echo "do nothing" > /dev/null
+else
+    rm arch.make
+    mv $_old_arch arch.make
+fi

settings.inc

@@ -1,3 +1,6 @@
+#ifdef COMMENTS
+! @LICENSE@, see README.md
+#endif
 #define _cc2_1(x,y) _cc2_2(x,y)
 #define _cc2_2(x,y) x ## y
 #define _cc3_1(x,y,z) _cc3_2(x,y,z)

test/tst_dict_mem1.F90

@@ -6,7 +6,7 @@ program tests
 
   integer :: i, N, step
 
-  N = 1000
+  N = 500
   step = 25
 
   write(*,*)'Delete and deallocation'

test/tst_dict_mem2.F90

@@ -6,7 +6,7 @@ program tests
 
   integer :: i, N, step
 
-  N = 1000
+  N = 500
   step = 25
 
   write(*,*)'Remove and delete var'

test/tst_dict_mem4.F90

@@ -6,7 +6,7 @@ program tests
 
   integer :: i, N, step
 
-  N = 1000
+  N = 500
   step = 25
 
   write(*,*)'Pop and delete var'

test/tst_dict_overwrite.F90

@@ -10,7 +10,7 @@ program test_dict
   ! fill dictionary
   dic = ('string'.kv."Hello world")
 
-  N = 1000
+  N = 500
   step = 25
 
   write(*,*) 'Overwriting same key'

test/tst_mem.F90

@@ -7,7 +7,7 @@ program tests
 
   integer :: i, N, step
 
-  N = 1000
+  N = 500
   step = 25
 
   write(*,*)'Running with deallocation'

var_funcs_inc.inc

@@ -1,3 +1,6 @@
+#ifdef COMMENTS
+! @LICENSE@, see README.md
+#endif
 #include "settings.inc"
 subroutine ROUTINE(assign_set,VAR)(this,rhs,dealloc)
   type(var), intent(inout) :: this

variable_pp.F90

@@ -1,3 +1,5 @@
+! @LICENSE@, see README.md
+
 ! Generic purpose variable as in any scripting language
 ! It has the power to transform into any variable at any time
 module variable