documentation

doc/scripts/DocSourcesList.cmake

@@ -19,6 +19,7 @@ rest_target(${psd} base/init-bare.bro internal)
 rest_target(${CMAKE_BINARY_DIR}/src base/bro.bif.bro)
 rest_target(${CMAKE_BINARY_DIR}/src base/const.bif.bro)
 rest_target(${CMAKE_BINARY_DIR}/src base/event.bif.bro)
+rest_target(${CMAKE_BINARY_DIR}/src base/input.bif.bro)
 rest_target(${CMAKE_BINARY_DIR}/src base/logging.bif.bro)
 rest_target(${CMAKE_BINARY_DIR}/src base/reporter.bif.bro)
 rest_target(${CMAKE_BINARY_DIR}/src base/strings.bif.bro)
@@ -31,6 +32,8 @@ rest_target(${psd} base/frameworks/cluster/setup-connections.bro)
 rest_target(${psd} base/frameworks/communication/main.bro)
 rest_target(${psd} base/frameworks/control/main.bro)
 rest_target(${psd} base/frameworks/dpd/main.bro)
+rest_target(${psd} base/frameworks/input/main.bro)
+rest_target(${psd} base/frameworks/input/readers/ascii.bro)
 rest_target(${psd} base/frameworks/intel/main.bro)
 rest_target(${psd} base/frameworks/logging/main.bro)
 rest_target(${psd} base/frameworks/logging/postprocessors/scp.bro)

scripts/base/frameworks/input/main.bro

@@ -1,52 +1,106 @@
+##! The input framework provides a way to read previously stored data either
+##! as an event stream or into a bro table.
 
 module Input;
 
 export {
+	## The default input reader used. Defaults to `READER_ASCII`.
 	const default_reader = READER_ASCII &redef;
 
+	## Stream decription type used for the `create_stream` method
 	type StreamDescription: record {
+		## String that allows the reader to find the source.
+		## For `READER_ASCII`, this is the filename.
 		source: string;
+		
+		## Reader to use for this steam
 		reader: Reader &default=default_reader;
 	};
 
+	## TableFilter description type used for the `add_tablefilter` method.
 	type TableFilter: record {
-		## descriptive name. for later removal
+		## Descriptive name. Used to remove a filter at a later time
 		name: string; 
 
-		## for tables
+		## Table which will contain the data read by the input framework
-		idx: any;
-		val: any;
 		destination: any;
+		## Record that defines the values used as the index of the table
+		idx: any;
+		## Record that defines the values used as the values of the table
+		val: any;
+		## Defines if the value of the table is a record (default), or a single value.
+		## Val can only contain one element when this is set to false.
 		want_record: bool &default=T;
+
+		## The event that is raised each time a value is added to, changed in or removed from the table.
+		## The event will receive an Input::Event enum as the first argument, the idx record as the second argument
+		## and the value (record) as the third argument.
 		ev: any &optional; # event containing idx, val as values.		
 
-		## decision function, that decides if an insertion, update or removal should really be executed.
+		## Predicate function, that can decide if an insertion, update or removal should really be executed.
-		## or events should be thought
+		## Parameters are the same as for the event. If true is returned, the update is performed. If false
+		## is returned, it is skipped
 		pred: function(typ: Input::Event, left: any, right: any): bool &optional;
 	};
 
+	## EventFilter description type used for the `add_eventfilter` method.
 	type EventFilter: record {
-		## descriptive name. for later removal
+		## Descriptive name. Used to remove a filter at a later time
 		name: string;
 
-		# the event
+		## Record describing the fields to be retrieved from the source input.
-		ev: any; 
-		# record describing the fields
 		fields: any;
-
+		## If want_record if false (default), the event receives each value in fields as a seperate argument.
-		# does the event want the field unrolled (default) or as a simple record value?
+		## If it is set to true, the event receives all fields in a signle record value.
 		want_record: bool &default=F;
+
+		## The event that is rised each time a new line is received from the reader.
+		## The event will receive an Input::Event enum as the first element, and the fields as the following arguments.
+		ev: any; 
+
 	};
 
 	#const no_filter: Filter = [$name="<not found>", $idx="", $val="", $destination=""]; # Sentinel.
 
-	global create_stream: function(id: Log::ID, description: Input::StreamDescription) : bool;
+	## Create a new input stream from a given source. Returns true on success.
-	global remove_stream: function(id: Log::ID) : bool;
+	##
-	global force_update: function(id: Log::ID) : bool;
+	## id: `Input::ID` enum value identifying this stream
-	global add_tablefilter: function(id: Log::ID, filter: Input::TableFilter) : bool;
+	## description: `StreamDescription` record describing the source.
-	global remove_tablefilter: function(id: Log::ID, name: string) : bool;
+	global create_stream: function(id: Input::ID, description: Input::StreamDescription) : bool;
-	global add_eventfilter: function(id: Log::ID, filter: Input::EventFilter) : bool;
+
-	global remove_eventfilter: function(id: Log::ID, name: string) : bool;
+	## Remove a current input stream. Returns true on success.
+	##
+	## id: `Input::ID` enum value identifying the stream to be removed
+	global remove_stream: function(id: Input::ID) : bool;
+
+	## Forces the current input to be checked for changes.
+	##
+	## id: `Input::ID` enum value identifying the stream
+	global force_update: function(id: Input::ID) : bool;
+
+	## Adds a table filter to a specific input stream. Returns true on success.
+	##
+	## id: `Input::ID` enum value identifying the stream
+	## filter: the `TableFilter` record describing the filter.
+	global add_tablefilter: function(id: Input::ID, filter: Input::TableFilter) : bool;
+
+	## Removes a named table filter to a specific input stream. Returns true on success.
+	##
+	## id: `Input::ID` enum value identifying the stream
+	## name: the name of the filter to be removed.
+	global remove_tablefilter: function(id: Input::ID, name: string) : bool;
+
+	## Adds an event filter to a specific input stream. Returns true on success.
+	##
+	## id: `Input::ID` enum value identifying the stream
+	## filter: the `EventFilter` record describing the filter.
+	global add_eventfilter: function(id: Input::ID, filter: Input::EventFilter) : bool;
+
+	## Removes a named event filter to a specific input stream. Returns true on success.
+	##
+	## id: `Input::ID` enum value identifying the stream
+	## name: the name of the filter to be removed.
+	global remove_eventfilter: function(id: Input::ID, name: string) : bool;
 	#global get_filter: function(id: ID, name: string) : Filter;
 
 }
@@ -85,13 +139,13 @@ function remove_tablefilter(id: Input::ID, name: string) : bool
 	return __remove_tablefilter(id, name);
 	}
 
-function add_eventfilter(id: Log::ID, filter: Input::EventFilter) : bool
+function add_eventfilter(id: Input::ID, filter: Input::EventFilter) : bool
 	{
 #	filters[id, filter$name] = filter;
 	return __add_eventfilter(id, filter);
 	}
 
-function remove_eventfilter(id: Log::ID, name: string) : bool
+function remove_eventfilter(id: Input::ID, name: string) : bool
 	{
 #	delete filters[id, name];
 	return __remove_eventfilter(id, name);