fileStreamObject.cpp

Public Functions

ConsoleDocClass(FileStreamObject , "@brief A wrapper around <a href="/coding/class/classstreamobject/">StreamObject</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> parsing text and data from <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">files.\n\n</a>" "<a href="/coding/class/classfilestreamobject/">FileStreamObject</a> inherits from <a href="/coding/class/classstreamobject/">StreamObject</a> and provides some unique methods <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> working " "with strings. If you're looking <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> general <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> handling)

DefineEngineMethod(FileStreamObject , close , void , () )

DefineEngineMethod(FileStreamObject , open , bool , (const char *filename, const char *openMode) , "@brief Open <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> reading, writing , reading and writing, or <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">appending\n\n</a>" "Using \"Read\" for the open <a href="/coding/file/zipobject_8cpp/#zipobject_8cpp_1ac6c3dfb4c3a68f849f32cbfb21da4e77">mode</a> allows you <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> parse the contents of file, but not making modifications. \"Write\" will create <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/tmm__on_8h/#tmm__on_8h_1a1ac41480eb2e4aadd52252ee550b630a">new</a> " "<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> <a href="/coding/file/tsmeshintrinsics_8cpp/#tsmeshintrinsics_8cpp_1a4e4fa7e3399708e0777b5308db01278c">if</a> it does not exist, or erase the contents of an existing <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> when opened. Write also allows you <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> modify the contents of the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">file.\n\n</a>" "\"ReadWrite\" will provide the ability <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> parse data (read it in) and manipulate data (write it out) interchangeably. Keep in mind the stream can " "move during each operation. Finally, \"WriteAppend\" will open <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> <a href="/coding/file/tsmeshintrinsics_8cpp/#tsmeshintrinsics_8cpp_1a4e4fa7e3399708e0777b5308db01278c">if</a> it exists, but will not clear the contents. You can write <a href="/coding/file/tmm__on_8h/#tmm__on_8h_1a1ac41480eb2e4aadd52252ee550b630a">new</a> data starting " " at the end of the files existing <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">contents.\n\n</a>" " @param filename Name of <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">open\n</a>" " @param openMode One of \"Read\" , \"Write\" , \"ReadWrite\" or \"WriteAppend\"\n\n" "@<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">tsexample\n</a>" "// Create <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a702945180aa732857b380a007a7e2a21">file</a> stream object <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">reading\n</a>" "% fsObject, false <a href="/coding/file/tsmeshintrinsics_8cpp/#tsmeshintrinsics_8cpp_1a4e4fa7e3399708e0777b5308db01278c">if</a> something went wrong" " @see close()" )

IMPLEMENT_CONOBJECT(FileStreamObject )

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#include "core/stream/fileStreamObject.h"
 25#include "console/engineAPI.h"
 26
 27//-----------------------------------------------------------------------------
 28// Local Globals
 29//-----------------------------------------------------------------------------
 30
 31static const struct
 32{
 33   const char *strMode;
 34   Torque::FS::File::AccessMode mode;
 35} gModeMap[]=
 36{
 37   { "read", Torque::FS::File::Read },
 38   { "write", Torque::FS::File::Write },
 39   { "readwrite", Torque::FS::File::ReadWrite },
 40   { "writeappend", Torque::FS::File::WriteAppend },
 41   { NULL, (Torque::FS::File::AccessMode)0 }
 42};
 43
 44//-----------------------------------------------------------------------------
 45// Constructor/Destructor
 46//-----------------------------------------------------------------------------
 47
 48FileStreamObject::FileStreamObject()
 49{
 50}
 51
 52FileStreamObject::~FileStreamObject()
 53{
 54   close();
 55}
 56
 57IMPLEMENT_CONOBJECT(FileStreamObject);
 58
 59ConsoleDocClass( FileStreamObject,
 60   "@brief A wrapper around StreamObject for parsing text and data from files.\n\n"
 61
 62   "FileStreamObject inherits from StreamObject and provides some unique methods for working "
 63   "with strings.  If you're looking for general file handling, you may want to use FileObject.\n\n"
 64
 65   "@tsexample\n"
 66   "// Create a file stream object for reading\n"
 67   "%fsObject = new FileStreamObject();\n\n"
 68   "// Open a file for reading\n"
 69   "%fsObject.open(\"./test.txt\", \"read\");\n\n"
 70   "// Get the status and print it\n"
 71   "%status = %fsObject.getStatus();\n"
 72   "echo(%status);\n\n"
 73   "// Always remember to close a file stream when finished\n"
 74   "%fsObject.close();\n"
 75   "@endtsexample\n\n"
 76
 77   "@see StreamObject for the list of inherited functions variables\n"
 78   "@see FileObject for general file handling.\n"
 79
 80   "@ingroup FileSystem\n"
 81);
 82
 83//-----------------------------------------------------------------------------
 84
 85bool FileStreamObject::onAdd()
 86{
 87   // [tom, 2/12/2007] Skip over StreamObject's onAdd() so that we can
 88   // be instantiated from script.
 89   return SimObject::onAdd();
 90}
 91
 92//-----------------------------------------------------------------------------
 93// Public Methods
 94//-----------------------------------------------------------------------------
 95
 96bool FileStreamObject::open(const char *filename, Torque::FS::File::AccessMode mode)
 97{
 98   close();
 99
100   if(! mFileStream.open(filename, mode))
101      return false;
102
103   mStream = &mFileStream;
104   return true;
105}
106
107void FileStreamObject::close()
108{
109   mFileStream.close();
110   mStream = NULL;
111}
112
113//-----------------------------------------------------------------------------
114// Console Methods
115//-----------------------------------------------------------------------------
116
117DefineEngineMethod( FileStreamObject, open, bool, (const char* filename, const char* openMode),,
118   "@brief Open a file for reading, writing, reading and writing, or appending\n\n"
119   
120   "Using \"Read\" for the open mode allows you to parse the contents of file, but not making modifications. \"Write\" will create a new "
121   "file if it does not exist, or erase the contents of an existing file when opened. Write also allows you to modify the contents of the file.\n\n"
122
123   "\"ReadWrite\" will provide the ability to parse data (read it in) and manipulate data (write it out) interchangeably. Keep in mind the stream can "
124   "move during each operation. Finally, \"WriteAppend\" will open a file if it exists, but will not clear the contents. You can write new data starting "
125   " at the end of the files existing contents.\n\n"
126
127   "@param filename Name of file to open\n"
128   "@param openMode One of \"Read\", \"Write\", \"ReadWrite\" or \"WriteAppend\"\n\n"
129
130   "@tsexample\n"
131   "// Create a file stream object for reading\n"
132   "%fsObject = new FileStreamObject();\n\n"
133   "// Open a file for reading\n"
134   "%fsObject.open(\"./test.txt\", \"read\");\n\n"
135   "// Get the status and print it\n"
136   "%status = %fsObject.getStatus();\n"
137   "echo(%status);\n\n"
138   "// Always remember to close a file stream when finished\n"
139   "%fsObject.close();\n"
140   "@endtsexample\n\n"
141
142   "@return True if the file was successfully opened, false if something went wrong"
143   
144   "@see close()")
145{
146   for(S32 i = 0;gModeMap[i].strMode;++i)
147   {
148      if(dStricmp(gModeMap[i].strMode, openMode) == 0)
149      {
150         Torque::FS::File::AccessMode mode = gModeMap[i].mode;
151         char buffer[1024];
152         Con::expandScriptFilename(buffer, sizeof(buffer), filename);
153         return object->open(buffer, mode);
154      }
155   }
156
157   Con::errorf("FileStreamObject::open - Mode must be one of Read, Write, ReadWrite or WriteAppend.");
158   return false;
159}
160
161DefineEngineMethod( FileStreamObject, close, void, (),,
162   "@brief Close the file. You can no longer read or write to it unless you open it again.\n\n"
163   
164   "@tsexample\n"
165   "// Create a file stream object for reading\n"
166   "%fsObject = new FileStreamObject();\n\n"
167   "// Open a file for reading\n"
168   "%fsObject.open(\"./test.txt\", \"read\");\n\n"
169   "// Always remember to close a file stream when finished\n"
170   "%fsObject.close();\n"
171   "@endtsexample\n\n"
172   
173   "@see open()")
174{
175   object->close();
176}
177