==================
 Resource Manager
==================
    Author:     Emily Rizzo
    Language:   C++
    Date:       March 2017

  - This is a command line resource management system, which allows the user to read text files into resource graphs,
    which can be manipulated and saved as text files.
  - The resource manager uses a custom Graph structure to store the items, where edges are represented as a list of
    dependencies. When a node is deleted by the user, any items which depend on that node are marked as "unusable."
  - When running, the program repeatedly prompts the user for a command, and prints out the current graph along with any
    messages generated by the last command.

  - Nodes can be deleted using the command "delete <node>". Note that this does not remove the node from the graph - it
    marks the node as unusable and updates any other nodes that depend on it.
  - Nodes can be added to the graph using the command "add <node>". This can either be used to add back a node previously
    deleted, or to create entirely new nodes. "add" can take in a list of dependencies to be added to the node as
    well, ex: "add dog food water" will add a node "dog" which depends on nodes "food" and "water." If "dog" already
    exists in the graph, the provided dependency list is appended to the existing list.
  - Graphs can be read from text files located in the directory RESOURCE-FILES. When using the "save" command, files are
    saved in this location as well.

  - Run ./resources to run the compiled resources.cpp from command line.

    Commands for Resource Manager:
        "delete <item>                          // deletes node <item> (makes unusable, not removed from graph3)
        "add <item>"                            // adds node <item> to graph, or makes <item> usable if already in graph
        "add <item> <dep1> <dep2> ..."          // adds <item> to graph w/ dependencies <dep1>, <dep2> ... <depN>,
                                                    or adds to <item>'s dependencies if <item> already exists
        "sort <-u or -n>"                       // sorts graph by usability (default, -u) or name (-n)
        "read <filename>"                       // reads a graph from <filename>, or from DEFAULT_FILE if <filename> is not
                                                    specified.
        "save <filename>"                       // saves the current graph to the provided <filename>, or to
                                                    currentFile if <filename> is not specified.
        "save -l"                               // prints out list of files saved since starting program
        "new"                                   // creates a new empty graph
        "file"                                  // prints out current file name, and default file name
        "q" or "exit"                           // quits the program


  - Source files should be in the format:
        <item1> <dependency1-1> <dependency1-2> ....
        <item2> <dependency2-1> <dependency2-2> ....
        .
        .
        .

    Where <item1> requires all <dependency1> nodes to be useable.
    All nodes in the file (including both <item> and <dependency>) become nodes in the graph.

===================
Contents of README
===================
I.      FILE CONTENTS                               //description of each file
II.     RESOURCES.H - CONTENTS                      //describes global functions defined in resources.h
III.    RESOURCES.CPP - STRUCTURE                   //structure of resources.cpp and details on running main()
IV.     RESOURCES.CPP - FUNCTIONS                   //important functions used by main()
V.      GRAPH.CPP - CLASSES                         //descriptions of the Node and Graph classes located in graph.cpp
VI.     FILE FORMAT NOTES                           //additional notes on format for the text files being read into graphs
VII.    CHANGING DEFAULT SETTINGS                   //variables to change default behavior of this program


=================
I. FILE CONTENTS
=================
    == resources.cpp ==
        - contains the main() function. This file runs the program, and manages a single graph g.
          main() runs on a while loop, repeatedly calling getCommand() and runCommand(), and printing out the graph.
          resources.cpp contains variables to keep track of saved files, and the file currently open.

    == resources.h ==
        - header file for resources program.
            Contains static function definitions for globally used functions
            Contains class declarations for the Node and Graph classes.
            Declares and defines default settings in variables:
                DEFAULT_FILE, FILE_EXT, DIR, and currentFile

    == graph.cpp ==
        - contains definitions for Node and Graph classes, global functions, and node comparators.

===========================
II. RESOURCES.H - CONTENTS
===========================

    STATIC VARIABLES (default settings for program behavior - can be modified)

        string DEFAULT_FILE = "resources.txt";
            - This is the default file to be read when the program starts.
              This file cannot be overwritten by the program.

        string FILE_EXT = ".txt";
            - This is the extension for file types allowed to be read from/written to
              (set to "" if no file type should be specified)

        string DIR = "RESOURCE-FILES/";
            - This is the default directory where resource files are stored (both reading and saving)


    GLOBAL FUNCTIONS

    == string createCopy(string file) ==
        returns a "copy" version of the <file> in the format <file> + "-copy" + FILE_EXT
        ex: "resources.txt" -> "resources-copy.txt"
        This function is used to ensure that the DEFAULT_FILE is not modified by the program, and instead saved as a copy

    == vector<string> split(string s, char delim) ==
        Splits the string s into a vector by delim - i.e. "A B C" returns the vector ["A", "B", "C"] when split on ' '.
        Default delimiter is ' '.
        Used when by Graph class when reading graph from text files, to split each line.
        Used when by main() when to split commands into a vector of arguments

    == vector<string> slice(vector<string> list, int begin, int end) ==
        Returns a slice of list from index begin to index end, i.e. split([A, B, C, D, E], 1, 3) would return [B, C, D]
        Used in conjunction with split() by Graph class when reading graph from text files, to separate item node from the list of dependency nodes
        Used in conjunction with split() by main() when reading commands, to separate the command action from the list of additional arguments


    CLASSES

        resources.h contains class declarations for the Node and Graph classes.
        Definitions for these classes are located in graph.cpp.

==============================
II. RESOURCES.CPP - STRUCTURE
==============================

    main() repeatedly loops and requests commands, which modify the current graph g.

    Global variables:
        Graph g;                    //graph which is generated either through commands or by reading in a text file
        vector<string> SAVES;       //list of files which have been saved since the program began running. Initially empty.
        string currentFile;         //most recent file saved or read into g


    Commands accepted by main():
        "delete <item>                          // deletes node <item> (makes unusable, not removed from graph3)
        "add <item>"                            // adds node <item> to graph, or makes <item> usable if already in graph
        "add <item> <dep1> <dep2> ..."          // adds <item> to graph w/ dependencies <dep1>, <dep2> ... <depN>,
                                                    or adds to <item>'s dependencies if <item> already exists
        "sort <-u or -n>"                       // sorts graph by usability (default, -u) or name (-n)
        "read <filename>"                       // reads a graph from <filename>, or from DEFAULT_FILE if <filename> is not
                                                    specified.
        "save <filename>"                       // saves the current graph to the provided <filename>, or to
                                                    currentFile if <filename> is not specified.
        "save -l"                               // prints out list of files saved since starting program
        "new"                                   // creates a new empty graph
        "file"                                  // prints out current file name, and default file name
        "q" or "exit"                           // quits the program

===============================
III. RESOURCES.CPP - FUNCTIONS
===============================
    == main() ==
        Generates g from DEFAULT_FILE
        Repeatedly prints out g, then prompts the user for commands using getCommand(), and executes the command with runCommand()
        Ends when user enters "q" or "exit"


    MAIN HELPER FUNCTIONS

        == string getCommand(string msg) ==
            prints out the current graph, then prints out msg, then prompts user for a command, and returns it
            Called repeatedly by main()

        == string runCommand(vector<string> command, string action, string item, int size) ==
            executes a command based on the values for action (first word of command), item (second word of command, if it exists), and the size of the command.
            returns any message generated by the command executed, including error messages.
            commands either print out information, or manipulate the graph g in some way.

        == bool checkFile(string file) ==
            Checks that the file has the correct extension specified by FILE_EXT.
            Used whenever a file is opened, before passing file to graph class


========================
IV. GRAPH.CPP - CLASSES
========================

    NODE CLASS
    ==========
        Class Variables
            - string name;                :name of node
            - vector<Node*> uses;         :list of dependencies that the node uses
            - vector<Node*> usedby;       :list of nodes that use this node
            - bool usable;                :true if the node is usable (and all dependencies are usable).

        Class Functions
            == void toString() ==
                - prints out Node in format "<Name>  || <Usable?> || <Dep1>, <Dep2>,...<DepN>"

            == void updateNode(bool u) ==
                - updates the node's usability to u, and updates all nodes in UsedBy list
                - calls checkDeps() to ensure that no nodes are erroneously set to usable when 1 of multiple missing dependencies is added


    GRAPH CLASS
    ===========
        Class Variables
            - vector<Node*> nodes;          :list of nodes currently in the graph
            - int longestItem;              :length of item in graph with the longest name, used for formatting printGraph()

        Class Functions
            == void addNewNode (string name, vector<string> dependsOn) ==
                - checks to see if the graph already contains a node n with name "name"
                - if n exists, updates n's' dependencies with the values in dependsOn.
                - otherwise, a new node is added to the graph with dependencies in dependsOn
                - calls checkDeps() to check the modified node's dependencies for usability

            == bool readFile (string fileName) ==
                - populates the graph from the file fileName.
                - Reads files by reading each line, splitting line into an item and a list of dependencies,
                    and calling addNewNode(item, dependencies)
                - returns true if the file is successfully opened. False indicates the file could not be found.

            == string saveFile (string fileName) ==
                - saves the current graph to the file specified by fileName, using a format readable by the program.
                - Additionally, checks if fileName would overwrite the default file, and updates fileName in this case using checkFile(fileName).
                - returns the file name that the graph was saved to.

            == Node* contains(string name) ==
                - returns a node n in the graph with name "name"
                - if node matching "name" exists in the graph, returns the existing node
                - otherwise, creates and adds a new node with name "name", and returns the new node.

            == void printGraph() ==
                - prints out the current graph by calling node->toString() on each node.
                - sample output (resources.txt):
                        Item    || Usable? || Uses
                        ========================================
                        handgun ||    o    || bullets,
                        bullets ||    o    || ore,
                        ore     ||    o    ||
                        bombs   ||    o    || ore,
                        turret  ||    o    || bullets,

            == string addNode(string name) ==
                - sets node "name" to be usable, and updates node. Called when command "add <item>" is used.
                - returns a string of missing dependencies if the node cannot be added.

            == sortGraphUSE() and sortGraphNAME() ==
                - sorts the nodes in the graph according to usability or node name, respectively.
                    - Usability: uses comparator compareNodesUse()
                        Default sort method, or called with flag "sort -u"
                        Sorts usable nodes with shortest dependency list first (the most 'basic' usable items).
                        Hierarchy of sorting is Usable -> node.uses.size() -> node.name
                    - Name: uses comparator compareNodesNAME()
                        Called with flag "sort -n"
                        Sorts nodes in alphabetical order by node.name

            == void removeGraph() ==
                - Empties graph, and frees memory allocated to nodes in the graph.
                - Used to clear graph when a file is read, or "new" is called.
                - Called before program exits to free memory.

===============
V. FILE FORMAT
===============

Source files should be in the format:

<item1> <dependency1-1> <dependency1-2> ....
<item2> <dependency2-1> <dependency2-2> ....
.
.
.


Notes:
    - Any number of dependencies (including 0) can be specified.
    - Node names must be a single word (i.e. "peanut butter" will be read as 2 separate nodes, use "peanutbutter" instead)
    - If a dependency is encountered that doesn't have a node already in the graph, one will be created.
    - items cannot be duplicated. if 2 rows of the file contain the same item name, dependencies will be combined.
        EXAMPLE:
            file containing:
                sandwich peanutbutter
                sandwich jelly
            yields a single node sandwich with dependencies: peanutbutter, jelly


EXAMPLE:

    "resources.txt" contains:
        handgun bullets
        bullets ore
        bombs ore
        turret bullets

    which yields the following graph:
        Item    || Usable? || Uses
        ========================================
        handgun ||    o    || bullets,
        bullets ||    o    || ore,
        ore     ||    o    ||
        bombs   ||    o    || ore,
        turret  ||    o    || bullets,


    Note that when saved, this graph whill write the file:
        handgun bullets
        bullets ore
        ore
        bombs ore
        turret bullets

    This file has an additional line for "ore" with no dependencies, but is read by the program as the same graph.

==============================
VI. CHANGING DEFAULT SETTINGS
==============================

    These variables are located at the top of resources.h.

        DEFAULT_FILE
        ============
            This string determines which file is read when the program initially opens and first constructs a graph.
            By default, this is the file "resources.txt".

        FILE_EXT
        ========
            This string determines which file extensions are accepted by checkFile(string file)
            By default this is ".txt". If any file should be accepted without checking extension, this should be set to ""

        DIR
        ===
            This string determines the directory where files are located, both for reading from and writing to files.
            By default, this is "RESOURCE-FILES/"