summaryrefslogtreecommitdiffstats
path: root/parser/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--parser/README.md149
1 files changed, 149 insertions, 0 deletions
diff --git a/parser/README.md b/parser/README.md
new file mode 100644
index 000000000..50d55e3d6
--- /dev/null
+++ b/parser/README.md
@@ -0,0 +1,149 @@
+#### Introduction
+
+The parser will be used to process streaming and plugins input as well as metadata
+
+Usage
+
+1. Define a structure that will be used to share user state across calls
+1. Initialize the parser using `parser_init`
+2. Register keywords and associated callback function using `parser_add_keyword`
+3. Register actions on the keywords
+4. Start a loop until EOF
+ 1. Fetch the next line using `parser_next`
+ 2. Process the line using `parser_action`
+ 1. The registered callbacks are executed to parse the input
+ 2. The registered action for the callback is called for processing
+4. Release the parser using `parser_destroy`
+5. Release the user structure
+
+#### Functions
+
+----
+##### parse_init(RRDHOST *host, void *user, void *input, int flags)
+
+Initialize an internal parser with the specified user defined data structure that will be shared across calls.
+
+Input
+- Host
+ - The host this parser will be dealing with. For streaming with SSL enabled for this host
+- user
+ - User defined structure that is passed in all the calls
+- input
+ - Where the parser will get the input from
+- flags
+ - flags to define processing on the input
+
+Output
+- A parser structure
+
+
+
+----
+##### parse_push(PARSER *parser, char *line)
+
+Push a new line for processing
+
+Input
+
+- parser
+ - The parser object as returned by the `parser_init`
+- line
+ - The new line to process
+
+
+Output
+- The line will be injected into the stream and will be the next one to be processed
+
+Returns
+- 0 line added
+- 1 error detected
+
+----
+##### parse_add_keyword(PARSER *parser, char *keyword, keyword_function callback_function)
+
+The function will add callbacks for keywords. The callback function is defined as
+
+`typedef PARSER_RC (*keyword_function)(char **, void *);`
+
+Input
+
+- parser
+ - The parser object as returned by the `parser_init`
+- keyword
+ - The keyword to register
+- keyword_function
+ - The callback that will handle the keyword processing
+ * The callback function should return one of the following
+ * PARSER_RC_OK -- Callback was successful (continue with other callbacks)
+ * PARSER_RC_STOP -- Stop processing callbacks (return OK)
+ * PARSER_RC_ERROR -- Callback failed, exit
+
+Output
+- The corresponding keyword and callback will be registered
+
+Returns
+- 0 maximum callbacks already registered for this keyword
+- > 0 which is the number of callbacks associated with this keyword.
+
+
+----
+##### parser_next(PARSER *parser)
+Return the next item to parse
+
+Input
+- parser
+ - The parser object as returned by the `parser_init`
+
+Output
+- The parser will store internally the next item to parse
+
+Returns
+- 0 Next item fetched successfully
+- 1 No more items to parse
+
+----
+##### parser_action(PARSER *parser, char *input)
+Return the next item to parse
+
+Input
+- parser
+ - The parser object as returned by the `parser_init`
+- input
+ - Process the input specified instead of using the internal buffer
+
+Output
+- The current keyword will be processed by calling all the registered callbacks
+
+Returns
+- 0 Callbacks called successfully
+- 1 Failed
+
+----
+##### parser_destroy(PARSER *parser)
+Cleanup a previously allocated parser
+
+Input
+- parser
+ - The parser object as returned by the `parser_init`
+
+Output
+- The parser is deallocated
+
+Returns
+- none
+
+----
+##### parser_recover_input(PARSER *parser)
+Cleanup a previously allocated parser
+
+Input
+- parser
+ - The parser object as returned by the `parser_init`
+
+Output
+- The parser is deallocated
+
+Returns
+- none
+
+[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fparser%2FREADME&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]()