mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
Improve documentation of input framework
This commit is contained in:
Daniel Thayer
parent
401743313c
commit
aa5471ec15
1 changed files with 52 additions and 30 deletions
|
|
@ -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();
|
||||
};
|
||||
|
||||
## 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,6 +219,10 @@ export {
|
|||
|
||||
## Event that is called when the end of a data source has been reached,
|
||||
## including after an update.
|
||||
##
|
||||
## 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);
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue