-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
333 lines (259 loc) · 16.3 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
==================
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/"