Added README.txt files for all utilities

src/utils/braintree_viewer/README.txt

@@ -0,0 +1,7 @@
+Braintree Viewer
+=================
+
+If you export the braintree to xml then you can use this utility to view the tree in a GUI
+
+python3 view.py /path/to/xml/file
+

src/utils/braintree_viewer/viewer.py

@@ -166,7 +166,7 @@ def _walk_xml(self, node, depth=0, parent=""):
     filename = sys.argv[1]
 
     root = Tk()
-    with open(filename, "r+") as xml_file:
+    with open(filename, "r") as xml_file:
         xml = xml_file.read()
     XML_Viewer(root, xml, heading_text="Braintree").pack(fill=BOTH, expand=YES)
     root.mainloop()

src/utils/corpus_creator/README.txt

@@ -0,0 +1,6 @@
+Corpus Creator
+===============
+
+Creates a spelling corpus from a given file which can then be used as input into the spelling checker
+
+python3 corpus_creator.py input_file output_file

src/utils/csv_tools/README.txt

@@ -0,0 +1,35 @@
+CSV Tools
+==========
+A set of tools for converting to and from AIML from CSV
+
+AIML to CSV
+------------
+Takes a single AIML file and converts to CSV file format
+Useful for exporting to CSV, making bulk changes and then converting back to AIML
+
+Usage:
+python3 aiml_to_csv.py input_aiml output_csv
+
+File Format:
+Any AIML 1.x or 2.x compliant xml file
+
+CSV to AIML
+------------
+Takes a CSV file conforming to the format described below and converts to AIML
+
+Usage:
+python3 csv_to_aiml.py input_csv output_aiml
+
+File Format:
+The format is made up for 4 columns
+    - Pattern
+    - Topic
+    - That
+    - Template
+
+E.g.
+    "HELLO","*","*","Hello there"
+    "HELLO *","*","*","<srai>HELLO</srai>"
+    "BYE","FAREWELL","*","See ya"
+    "MAYBE","*","THINKING","OK THEN"
+    "LA LA LA","SINGING","SING A SONG","Ouch that hurts"

src/utils/csv_tools/csv_to_aiml.py

@@ -22,20 +22,20 @@ def run(self):
             for line in csv_reader:
                 if line:
                     tab = ""
-                    template = line[0].strip(' "')
+                    pattern = line[0].strip(' "')
                     topic = line[1].strip(' "')
                     that = line[2].strip(' "')
-                    pattern = line[3].strip(' "')
+                    template = line[3].strip(' "')
 
                     if topic != "*":
                         aiml_file.write('<topic name="%s">\n'%topic)
                         tab = "\t"
                     aiml_file.write('%s<category>\n'%tab)
-                    aiml_file.write('%s\t<pattern>%s</pattern>\n'%(tab, template))
+                    aiml_file.write('%s\t<pattern>%s</pattern>\n'%(tab, pattern))
                     if that != "*":
                         aiml_file.write('%s\t<that>%s</that>\n' % (tab, that))
                     aiml_file.write('%s\t<template>\n'%tab)
-                    aiml_file.write('%s\t\t%s\n'%(tab, pattern))
+                    aiml_file.write('%s\t\t%s\n'%(tab, template))
                     aiml_file.write('%s\t</template>\n'%tab)
                     aiml_file.write('%s</category>\n'%tab)
 

src/utils/data_creators/README.txt

@@ -0,0 +1,9 @@
+A suite of tools used to create mock data for the unit tests
+
+Only really useful of the data format changes as the data is already created and stored in the unit tests
+
+
+geonames.py - creates geolocation data for use in unit tests geonames module
+googledata.py - creates data for use in unit testing google maps and directions modules
+metoffice.py - creates unit test data for the metoffice unit tests
+newsapi.py - creates unit test data for the newapi module

src/utils/pattern_lister/README.txt

@@ -0,0 +1,25 @@
+Pattern Lister
+==============
+Creates a single CSV file containingall AIML patterns from the files specified in the directory ( and sub directories )
+
+Useful tool for debugging and seeing the spread of AIML categories across files.
+
+Usage:
+    python3 pattern_lister aiml_dir csv_file
+
+CSV File Format:
+
+../../../bots/y-bot/aiml/core/system/repeat.aiml, #, AGAIN, #
+../../../bots/y-bot/aiml/core/profanity/insults.aiml, #, B, ASTERISK, ASTERISK, ASTERISK, ASTERISK
+../../../bots/y-bot/aiml/extensions/energy/directdebits.aiml, #, CANCEL, #, DIRECT, DEBUT, #
+../../../bots/y-bot/aiml/extensions/energy/directdebits.aiml, #, CHANGE, #, DIRECT, DEBUT, #
+../../../bots/y-bot/aiml/extensions/maps/maps.aiml, #, DISTANCE, *, BETWEEN, *
+../../../bots/y-bot/aiml/extensions/maps/maps.aiml, #, DISTANCE, *, TO, *
+../../../bots/y-bot/aiml/extensions/maps/maps.aiml, #, DISTANCE, BETWEEN, *, AND, *
+../../../bots/y-bot/aiml/extensions/maps/maps.aiml, #, DISTANCE, FROM, *, TO, *
+../../../bots/y-bot/aiml/core/personality.aiml, #, GLASS, HALF, #
+../../../bots/y-bot/aiml/personality/hello.aiml, #, HEY, #
+../../../bots/y-bot/aiml/personality/hello.aiml, #, HI, #
+../../../bots/y-bot/aiml/personality/hello.aiml, #, HIYA, #
+../../../bots/y-bot/aiml/extensions/maps/maps.aiml, #, HOW, #, GET, FROM, *, TO, *
+../../../bots/y-bot/aiml/extensions/energy/directdebits.aiml, #, HOW, MUCH, #, DIRECT, DEBIT, #

src/utils/pattern_lister/pattern_lister.py

@@ -8,10 +8,6 @@
     aiml_dir = sys.argv[1]
     csv_file = sys.argv[2]
 
-    default = None
-    if len(sys.argv) > 5:
-        default = sys.argv[5]
-
     print("aiml_dir:", aiml_dir)
     print("csv_file:", csv_file)
 

src/utils/rdf_lister/README.txt

@@ -0,0 +1,10 @@
+RDF Lister
+==========
+Creates a single CSV file from all the rdf files found in the directory ( and sub directories ) specified
+All entries are sorted by Subject, then predicate, then entity value.
+
+This tool is useful to debugging RDF to make sure all RDF entities are in the same file and located next to each
+other
+
+Usage:
+    python3 rdf_lister rdf_dir csv_file

src/utils/rdf_lister/rdf_lister.py

@@ -6,10 +6,6 @@
     rdf_dir = sys.argv[1]
     csv_file = sys.argv[2]
 
-    default = None
-    if len(sys.argv) > 5:
-        default = sys.argv[5]
-
     print("rdf_dir:", rdf_dir)
     print("csv_file:", csv_file)
 

src/utils/rdf_tools/README.txt

@@ -0,0 +1,12 @@
+RDF Formatter
+=============
+
+A simple utility to reformat an RDF knowledge file. I've found a number of ALice2 RDF files which have entity data
+scattered across the file as new predicates are added to the end of files. This utility therefore builds all entities
+in memory first and then re-writes the file so that all subject -> predicate -> entity values are in the appropriate
+order
+
+Usage:
+python3 rdf_formatter.py rdf_file
+
+    rdf_file - Name of an rdf file to reformat

src/utils/socket_client/README.txt

@@ -0,0 +1,13 @@
+Socket Client
+==============
+Test client for the TCP Socket Bot Client
+
+Usage:
+python3 socket_client.py host port question clientid [max_buffer_size]
+
+    host - IP Address of host to connect to
+    port - Port of the host to connect to
+    question - Question to send to the bot
+    clientid - Client id to send with the question
+    max_buffer_size - Optional value to set the max tcp buffer size, defaults to 1024 bytes
+

src/utils/test_creator/README.txt

@@ -0,0 +1,45 @@
+Test Creator
+============
+
+Creates AIML based unit tests
+
+
+Usage:
+python3 test_creator.py aiml_file test_file ljust replace_file [default]
+
+    aiml_file       - AIML File to create tests from
+    test_file       - Test file to create with associated unit tests
+    ljust           - Left justifies the first csv column, a good value is 40 or 80
+    replace_file    - When creating tests you can specify replacements certain data types
+                        *, #, ^, _ - For each wildcard the associated text is set instead of the wildcard
+                        SET - Replaces the set with a single value, typically this will be one value from the set
+                        BOT - Replaces the bot with a single value, typically this will be one value from the bot
+    default         - Optional value which sets a default value for each answer
+
+Example Output File:
+(This file is created from the aiml file in y-bot\aiml\core\temporal\datetime_core.aiml)
+
+"SEASON", "Winter", "Spring", "Summer", "Autumn", "Fall"
+"DAY", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"
+"TOMORROW", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"
+"YEAR", "This is [0-9]*"
+"NEXT YEAR", "[0-9]*"
+"LAST YEAR", "[0-9]*"
+"MONTH", "This is [January|February|March|April|May|June|July|August|September|October|November|December]"
+"TIME", "The time is [0-9]{2}:[0-9]{2} [AM|PM]"
+"DATE", "Today is *. [0-9]{2},[0-9]{4}"
+"DAY PHASE", "Morning", "Noon", "Afternoon", "Night", "Midnight"
+"DATE AND TIME", "The date and time is .* .* [0-9]* [0-9]{2}:[0-9]{2}:[0-9]{2} [0-9]{4}"
+"DAYS UNTIL CHRISTMAS", "[0-9]* days until Christmas."
+"DAYS UNTIL JANUARY 01 2020", "[0-9]* days."
+"DAYS UNTIL JANUARY 01", "-?[0-9]* days"
+"DATE TOMORROW", "[0-9]{2},[0-9]{4}"
+
+Example Replacement File:
+    SET,animal:cow
+    SET,animals:cows
+    SET,number:2
+    *:STAR
+    #:HASH
+    ^:ARROW
+    _:UNDERLINE

src/utils/test_runner/README.txt

@@ -0,0 +1,17 @@
+Test Runner
+===========
+After creating AIML unit tests with the test_creator.py utility, use test_runner to execute the tests and flag up
+any errors or invalid responses
+
+Usage:
+    python3 test_runner.py --test_dir test-dir --qna_file qna-file --verbose
+or
+    python3 test_runner.py --test_file test_file --qna_file qna-file --verbose
+
+    --test_dir  - Directory to search for aiml files to execute, includes sub directories in search
+    --test_file - Name of a single aiml unit test file to execute, useful during test creation process
+    --qna_file  - This file is created during test execution and provides a record of all questions and their answers
+    --verbose   - Prints out more detailed debugging information as the test runner executes each test. Useful of you
+                  have a large number of tests and want to monitor progress
+
+Filel Format: