From aa5471ec153c5b21371097fe862a6bbe53e0abbd Mon Sep 17 00:00:00 2001 From: Daniel Thayer Date: Mon, 21 Sep 2015 16:42:53 -0500 Subject: [PATCH] Improve documentation of input framework --- scripts/base/frameworks/input/main.bro | 82 ++++++++++++++++---------- 1 file changed, 52 insertions(+), 30 deletions(-) diff --git a/scripts/base/frameworks/input/main.bro b/scripts/base/frameworks/input/main.bro index 82c46b870c..41e42d2da9 100644 --- a/scripts/base/frameworks/input/main.bro +++ b/scripts/base/frameworks/input/main.bro @@ -1,18 +1,25 @@ ##! The input framework provides a way to read previously stored data either -##! as an event stream or into a bro table. +##! as an event stream or into a Bro table. module Input; export { type Event: enum { + ## New data has been imported. EVENT_NEW = 0, + ## Existing data has been changed. EVENT_CHANGED = 1, + ## Previously existing data has been removed. EVENT_REMOVED = 2, }; + ## Type that defines the input stream read mode. type Mode: enum { + ## Do not automatically reread the file after it has been read. MANUAL = 0, + ## Reread the entire file each time a change is found. REREAD = 1, + ## Read data from end of file each time new data is appended. STREAM = 2 }; @@ -47,11 +54,11 @@ export { ## abort. Defaults to false (abort). const accept_unsupported_types = F &redef; - ## TableFilter description type used for the `table` method. + ## A table input stream type used to send data to a Bro table. type TableDescription: record { # Common definitions for tables and events - ## String that allows the reader to find the source. + ## String that allows the reader to find the source of the data. ## For `READER_ASCII`, this is the filename. source: string; @@ -61,7 +68,8 @@ export { ## Read mode to use for this stream. mode: Mode &default=default_mode; - ## Descriptive name. Used to remove a stream at a later time. + ## Name of the input stream. This is used by some functions to + ## manipulate the stream. name: string; # Special definitions for tables @@ -76,29 +84,32 @@ export { ## If this is undefined, then *destination* must be a set. val: any &optional; - ## Defines if the value of the table is a record (default), or a single value. - ## When this is set to false, then *val* can only contain one element. + ## Defines if the value of the table is a record (default), or a single + ## value. When this is set to false, then *val* can only contain one + ## element. 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. + ## 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::TableDescription as the first argument, an Input::Event + ## enum as the second argument, the *idx* record as the third argument + ## and the value (record) as the fourth argument. + ev: any &optional; ## Predicate function that can decide if an insertion, update or removal - ## should really be executed. Parameters are the same as for the event. + ## should really be executed. Parameters have same meaning 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; - ## A key/value table that will be passed on the reader. - ## Interpretation of the values is left to the writer, but + ## A key/value table that will be passed to the reader. + ## Interpretation of the values is left to the reader, but ## usually they will be used for configuration purposes. - config: table[string] of string &default=table(); + config: table[string] of string &default=table(); }; - ## EventFilter description type used for the `event` method. + ## An event input stream type used to send input data to a Bro event. type EventDescription: record { # Common definitions for tables and events @@ -117,20 +128,26 @@ export { # Special definitions for events - ## Record describing the fields to be retrieved from the source input. + ## Record type describing the fields to be retrieved from the input + ## source. fields: any; - ## If this is false, the event receives each value in fields as a separate argument. - ## If this is set to true (default), the event receives all fields in a single record value. + ## If this is false, the event receives each value in *fields* as a + ## separate argument. + ## If this is set to true (default), the event receives all fields in + ## a single record value. want_record: bool &default=T; ## The event that is raised 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. + ## reader. The event will receive an Input::EventDescription record + ## as the first argument, an Input::Event enum as the second + ## argument, and the fields (as specified in *fields*) as the following + ## arguments (this will either be a single record value containing + ## all fields, or each field value as a separate argument). ev: any; - ## A key/value table that will be passed on the reader. - ## Interpretation of the values is left to the writer, but + ## A key/value table that will be passed to the reader. + ## Interpretation of the values is left to the reader, but ## usually they will be used for configuration purposes. config: table[string] of string &default=table(); }; @@ -157,28 +174,29 @@ export { ## field will be the same value as the *source* field. name: string; - ## A key/value table that will be passed on the reader. - ## Interpretation of the values is left to the writer, but + ## A key/value table that will be passed to the reader. + ## Interpretation of the values is left to the reader, but ## usually they will be used for configuration purposes. config: table[string] of string &default=table(); }; - ## Create a new table input from a given source. + ## Create a new table input stream from a given source. ## ## description: `TableDescription` record describing the source. ## ## Returns: true on success. global add_table: function(description: Input::TableDescription) : bool; - ## Create a new event input from a given source. + ## Create a new event input stream from a given source. ## ## description: `EventDescription` record describing the source. ## ## Returns: true on success. global add_event: function(description: Input::EventDescription) : bool; - ## Create a new file analysis input from a given source. Data read from - ## the source is automatically forwarded to the file analysis framework. + ## Create a new file analysis input stream from a given source. Data read + ## from the source is automatically forwarded to the file analysis + ## framework. ## ## description: A record describing the source. ## @@ -201,7 +219,11 @@ export { ## Event that is called when the end of a data source has been reached, ## including after an update. - global end_of_data: event(name: string, source:string); + ## + ## name: Name of the input stream. + ## + ## source: String that identifies the data source (such as the filename). + global end_of_data: event(name: string, source: string); } @load base/bif/input.bif