In this version of the game, we're going to read room descriptions from a text file in the format:

RoomName##RoomDescription
RoomName##RoomDescription
RoomName##RoomDescription
...

This format indicates that each line specifies a single record (a room) and it has two fields, the room's name and description. Notice the ## between RoomName and RoomDescription -- that is a field delimiter and it can be any single or sequence of characters. You may be familiar with comma-separated values (CSV -- also known as comma-delimited -- format) where each field is separated by a comma. That choice of delimiter won't work well for our game because our room descriptions contain commas. Those commas will create errant fields. Thus, I chose a delimiter that would not be used as part of a field.

To begin, create a Rooms.txt file with the following contents:

Rocky Trail##You are on a rock-strewn trail.
South of House##You are facing the south side of a white house. There is no door here, and all the windows are barred.
Canyon View##You are at the top of the Great Canyon on its south wall.
Forest##This is a forest, with trees in all directions around you.
West of House##This is an open field west of a white house, with a boarded front door.
Behind House##You are behind the white house. In one corner of the house there is a small window which is slightly ajar.
Dense Woods##This is a dimly lit forest, with large trees all around. To the east, there appears to be sunlight.
North of House##You are facing the north side of a white house. There is no door here, and all the windows are barred.
Clearing##You are in a clearing, with a forest surrounding you on the west and south.

Note that you can do this from within Visual Studio through the File | New | File... menu option (Ctrl+N shortcut key) or through the right-click context menu on your project. Be certain that you save the file within the same directory as the rest of your source code for the project. Additionally, your application expects any files that you read to be at or below the output directory of your project (for example, the bin\Debug\netcoreapp2.1 directory when you're building the Debug configuration of the project). However, newly created text files won't be automatically copied to the output directory by default, this is a setting you have to enable.

With the Rooms.txt file selected in the Solution Explorer, open the Properties window (View | Properties Window or Alt+Enter) and change the Copy to Output Directory setting to Copy If Newer as shown in the following screenshot:

Next, move the declaration of the roomMap dictionary variable from the InitializeRoomDescriptions method to be a class data member. It should read:

private static readonly Dictionary<string, Room> RoomMap;

You may be wondering about the readonly modifier and the lack of an initializer list -- that seems contradictory. Doesn't readonly mean that the reference can't be modified after intialization? And yet we aren't initializing it? The answer is the following block of code:

This is known as a static constructor. A static constructor is used to initialize any static data members of the class -- including static readonly data members. A class can have just one static constructor, it executes exactly once, and it executes before any other class constructor. Thus, we can use this to initialize our RoomMap and guarantee that it will be populated before any other class method attempts to use it and guarantee that once it's populated it cannot be modified!

My rationale for moving the RoomMap variable to be static readonly is twofold: 1) we will be implementing two different methods for reading data from our file and both methods will employ the RoomMap variable -- so it can no longer be a local variable; 2) to introduce static constructors.

Next, update your InitializeRoomDescriptions method to the following code:

Notice that we've added a roomsFilename parameter to the method -- we'll expect to pass in our "Rooms.txt" string as this argument, but by specifying this as a method parameter (instead of a hard-coded string) we can accept a user-supplied file name that they can specify on application startup. We'll see how that's done shortly.

Next, observe the first two statements in the InitializeRoomDescriptions method -- declarations for the field delimiter and the expected number of fields. We've used the const keyword for each of these declarations and that means that these locals cannot be modified after initialization. It is a good programming practice to use const identifiers rather than scattering literals throughout your code. For example, we could have written:

string[] fields = line.Split("");
if (fields.Length != 2)

and accomplished the same thing. But those literals have no obvious meaning. We call such values, magic numbers and they decrease the readability of our programs. Furthermore, when you duplicate the use of the same values, they become more difficult (read: error-prone) to change. Constant identifiers for the win!

In the next statement we invoke the static ReadAllLines method from the System.IO.File class. In order to abbreviate the call add a using directive for System.IO to the top of Program.cs. File.ReadAllLines does exactly what it's name implies; it reads all of the lines from our roomFilename file and returns them as an array of strings. Each element in the array will contain the text from one line our our file. For example:

lines[0]: "Rocky Trail##You are on a rock-strewn trail."
lines[1]: "South of House##You are facing the south side of a white house.  There is no door here, and all the windows are barred."
lines[2]: "Canyon View##You are at the top of the Great Canyon on its south wall."
...

Now we can iterate through each of these lines in order to initialize each of the room descriptions. The first statement within the foreach loop invokes the string class' Split method to separate our line into fields. Split uses our ## field delimiter to accomplish this and returns the fields as an array of strings. Note that the ## delimiter will not be part of the returned array. On the first iteration of our loop, our fields array will look the following:

fields[0]: "Rocky Trail"
fields[1]: "You are on a rock-strewn trail."

The next block of code validates that each line contains exactly two fields. If not, it throws an exception indicating a malformed file. After validating the record, the next two statements retrieve the two fields in a readable fashion:

string name = fields[(int)Fields.Name];
string description = fields[(int)Fields.Description];

Remember that strings are reference types (because System.String is a class and the C# string keyword is synonymous with System.String) and that assignments like this do not copy the values -- they copy the references. Thus, there's no true cost here, we've just given names (identifiers) to the two elements of the array for more readability. But what's with the indices in to the fields array? The Fields type is an enum with the following definition:

Note that we've made this a private data type and it must, therefore, be nested within the Program class in order for methods within the Program class (like our InitializeRoomDescriotions method) to have access to it.

This Fields enum is just another way to remove magic numbers. We could have written:

string name = fields[0];
string description = fields[1];

But I find the above approach more readable and more easier to modify if the file format changes. Note that we have to cast the enum values to integers with the (int) cast operator. That's because enum values are "integers in disguise", but we have to be explicit about wanting to use the enum value as an integer. Also note that we don't have assign a value to each of the enumeration values, they increment from the first value (thus, Fields.Description is the value 1 in this example). We didn't even need to be explicit about starting Name at 0, since that's the default; but I like to do this for added readability and to inform the reader that these values are expected to be used as integers.

Finally, we assign the description to the room with the corresponding name with the code:

RoomMap[name].Description = description;

If the name isn't found in the RoomMap dictionary, we'll get a run-time exception. That's the behavior we're looking for in this version of the game. In the future, we'll make our game read the entire game world (not just the descriptions) from a file.

Next, update the call to InitializeRoomDescriptions (from the Main method) to pass in "Rooms.txt" as an argument:

string roomsFilename = "Rooms.txt";
initializeRoomDescriptionsFunc(roomsFilename);

If you run your game now, you should see the expected output. That's all well-and-good, but let's allow the player to specify a file name from the command-line, when they launch the game. We can do this by employing the heretofore ignored args parameter of the Main method:

static void Main(string[] args)

The args parameter is an array of strings that contains the values entered on the command-line when the application is executed. Remember that for .NET Core applications, we execute our application from the command-line with the following:

(from the project directory of your application -- where the Zork.csproj file resides)
> dotnet run

With that command, the args array is empty (Length 0) but we can specify additional arguments such as:

> dotnet run the quick brown fox

And our args array would have a Length of 4 with the following contents:

args[0]: "the"
args[1]: "quick"
args[2]: "brown"
args[3]: "fox"

As you can see, the command-line uses white-space as the delimiter. If you want spaces in your arguments you have to enclose them in double quotes; for example:

> dotnet run "the quick brown" fox

Would have an args array of Length 2 with the contents:

args[0]: "the quick brown"
args[1]: "fox"

We can use these commend line arguments to allow the user to specify a filename to read from with code like the following:

and the CommandLineArguments enum (again using an enum to avoid magic numbers):

If the player doesn't specify a filename, we get "Rooms.txt" otherwise, we'll use what the player specifies. Test this by creating a Rooms2.txt file with different descriptions that Rooms.txt.

The last bit we'll look at in this lesson is an alternate approach for reading from a text file using LINQ (Language-Integrated Query). This is a much larger topic than we will get into here but, by way of introduction, here is an implementation of the InitializeRoomDescriptions method using LINQ:

As an exercise, walk through this code and compare it to the original method. You will see many similarities in the use of File class to read the lines, line.Split, validation against the expected number of fields and an extraction of the name and description fields using the Fields enum. Aside from the syntax what is fundamentally different between these two approaches is how we ask for the data we're interested in. In the imperative approach (the non-LINQ version) our code performs a step-by-step set of instructions to process the data in our file. The focus of that code is how the program goes about getting at the data we are interested in.

In the declarative approach (the LINQ version) we declare what data we are interested without explicitly specifying how the program gets it. We split the request for the information from what we do with it once we have it! This approach to programming takes some getting used to, there are performance gotchas to look out for, and it's not an absolute replacement for imperative programming; but it's a wonderful addition to the programmer toolbox!