From 3204e21a5d04bb24ef4d6c9ff7961b8db30b598d Mon Sep 17 00:00:00 2001 From: bloodstalker Date: Tue, 7 Aug 2018 06:23:55 +0430 Subject: update --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8bb20cd..32fdb2a 100644 --- a/README.md +++ b/README.md @@ -1 +1,50 @@ -# faultreiber \ No newline at end of file +# faultreiber +`faultreiber` generates a parser library in C for a structured file format. The input is an XML file that describes the format.
+The C source code will be in the form of multiple source and header files. a makefile is also included.
+The generated source code does not include a main.
+ +## faultreiber XML file +The root node should have two childs, named exactly `READ` and `DEFINITION`(order not important).
+The `READ` node will include the actual structures that the parser will read and can return.
+The `DEFINITION` node includes the definitions for the structures that are aggregate.
+For an explanation of the format for the XML file, let's look at the example XML file under `resources`. The XML file describes the format of a WASM object file:
+Any child node of either `DEFINITION` or `READ` will have to at least have the attributes `name` and `type` defined. The presence of the attribute `count` is optional but if it's not present faultreiber will assume that the count is one. The presence of the attribute `isaggregate` signifies the fact that the data structure is composed of other smaller parts. faultreiber will only read the children of a node that is the child of either the `DEFINITION` or `READ` node(unless a child node has the attribute `conditional` set). If a data structure requires more children then you should add a new node under `DEFINITION` and reference that node from it's parent.
+`count`, `size`, `type` and `condition` attributes can reference a child node of the `DEFINITION` node. To do that, you should use `self::TAG`.
+the tag names of the nodes that are on the same level should be unique. The `name` attribute of the nodes on the same level need to be unique as well.
+tags, needless to say, should follow the naming convention for naming XML nodes. The `name` attributes should follow the C identifier naming convention(if the value of the `name` attribute is invalid in C as as identifier you're going to end up with code that won't even build).
+The following values are valid values for the `type` attribute:
+int8 +uint8 +int16 +uint16 +int32 +uint32 +int64 +uint64 +int128 +uint128 +float +double +string +FT::conditional +self::TAG + +Whether `int128` or `uint128` are defined depends on your the C implementation you are using on your host. If 128-bit integers are not supported or you need to read in bigger integers, you can simply use a smaller int type and increase the `count` attribute accordingly.
+The `FT::conditional` tag for a type means that the actual content of the node will depend on a value. The attribute `condition` will provide what that condition is. The value for the condition should be provided as text for the different nodes that define what the actual contents should be.
+A node referencing another node as the value of its `type` attribute is insensitive to the order in which the nodes appear under their parent node, `DEFINITION`.
+`size` attribute is currently only meaningful when the `type` attribute is set as `string` in which case it denotes the size of the string.
+ +## limitations +Big-Endian reads are not supported.
+Only files that are instantly-decodable(need a single pass) are supported.
+None byte sized raw reads are not supported.
+String reads need to have a size. Currently null-terminated string reads without the size of the string are not supported.
+ +## makefile + +## TODO +All the items under limitations.
+Figure out what the license of the generated code is.
+ +## License +`faultreiber` along with the makefile are provided under MIT. I don't know if I have the legal right to license the generated files, but if I do, they are also under MIT as far as I'm concerned.
-- cgit v1.2.3