Items File_Item

File_Item

See original

SYNOPSIS

     use File_Item;
     $f_deep_thoughts = new File_Item("$Pgm_Root/data/remarks/deep_thoughts.txt");
     my $thought = read_next $f_deep_thoughts;
     set_index $f_deep_thoughts 1;
     
     $f_weather_forecast = new File_Item("$Pgm_Root/data/web/weather_forecast.tx t");
     set_watch $f_weather_forecast;
     display name $f_weather_forecast if changed $f_weather_forecast;
     
     $shoutcast_log = new File_Item 'd:/shoutcast/sc_serv.log';
     print "Log data: $state" if $New_Second and $state = said $shoutcast_log;

DESCRIPTION

An item for reading and/or monitoring a file

Use File_Item to read a line of (or all of the) data from a file, and/or to monitor a file for changes.

Note: These methods currently read the entire file, so if have big files (say, >1 meg) we want to read, we should invent some new methods.

INHERITS

NONE

Items.mht

METHODS

Method	Description
new('file_name')	Instantiation method. 'file_name' is the path and name of the file to read/monitor.
name()	Returns the path and name of the file associated with this item. Slashes are translated to backslashes on Windows system.
restore_string()	Returns a string used to restore the index after a restart. bin/mh calls this method (for each item that has it) every 5 minutes to create mh_temp.saved_states in the data directory.
set_watch('flag')	Sets the 'changed' time check.
changed()	Returns 0 if the file was not changed since the last set_watch call. When the file changes: if 'flag' was specified in the last set_watch call, 'flag' is returned, otherwise, it returns the number of seconds since the last set_watch call.
exist()	Returns 1 if the file exists, 0 otherwise.
exist_now()	Returns 1 if the file was created since the last exist_now test, 0 otherwise.
read_all()	Returns contents for the file. If used in a list context, a list is returned, otherwise a string of all the lines.
read_head(num)	Returns the first num lines of a file. Defaults to ten lines if num not given. See file_head.
read_tail(num)	Returns the last num lines of a file. Defaults to ten lines if num not given. See file_tail.
said()	Returns data added to a file since the last call. Only one record is returned per call. This is useful for monitoring log files. See mh/code/bruce/shoutcast_monitor.pl for an example.
read_random()	Reads a random record. This also re-sets the index to the random position.
read_next()	Reads the next record, according to the index. After reading the last record, it wraps back to the first.
read_next_tail()	Like read_next, except, it will not wrap back to the first record (i.e. after reaching the end of the file, it will always return the last record).
read_current()	meads the current record, according to the index.
index()	Deprecated. Use get_index() instead.
get_index()	Which record (line) of the file was last read. The index is saved between MiaterHouse sessions. If you use a File_Item that does not yet have an index set, a random index will be used and stored.
set_index(num)	Set the index to line num. Defaults to 1 (first line) if num not given.
get_type()	Returns the class (or type, in MisterHouse terminology) of this item.

INI PARAMETERS

debug: Include file in the comma separated list of debug keywords to produce debugging output from this item.

AUTHOR

Bruce Winter

SEE ALSO

None