From 23df5ce7d69f715aca7e7a53d03a048830e99b69 Mon Sep 17 00:00:00 2001 From: JSDurand <mmemmew@gmail.com> Date: Sun, 30 Jul 2023 11:36:59 +0800 Subject: update README Use a better formatting style. --- README | 63 +++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 14 deletions(-) diff --git a/README b/README index bc1507b..0da3d7a 100644 --- a/README +++ b/README @@ -26,11 +26,15 @@ Manual compilation First clone this package: - git clone https://git.jsdurand.xyz/rep.git + ---------------------------------------------- + | git clone https://git.jsdurand.xyz/rep.git | + ---------------------------------------------- Then go into the cloned directory: - cd rep + ---------- + | cd rep | + ---------- [ Make sure the Rust tools are already installed. If not, then install the Rust compiler tools from the instructions on the website @@ -38,9 +42,11 @@ Then go into the cloned directory: Then run the autotools: - autoreconf -vif - -// TODO: Make the two build options and fix make. + ------------------- + | autoreconf -vif | + ------------------- + +// TODO: Make the two build options. Now there are two build options: debug and release. The debug build is for debugging the package, so turns off optimisations and includes @@ -50,17 +56,35 @@ build. If one wants to use the debug build, run: - ./configure --debug + ----------------------- + | ./configure --debug | + ----------------------- Otherwise just run: - ./configure + --------------- + | ./configure | + --------------- Finally run 'make' to build the package: - make + -------- + | make | + -------- Now there should be a file 'rep.so' located in the 'src' directory. +And one can directly load that file or move that dynamic library to +another more convenient location of choice. + +The commands to build this package are summarized as follows: + + ---------------------------------------------- + | git clone https://git.jsdurand.xyz/rep.git | + | cd rep | + | autoreconf -vif | + | ./configure | + | make | + ---------------------------------------------- Build on Windows ================ @@ -92,8 +116,10 @@ grammars are. In short, a grammar can be viewed as a "substitution machine". That is, a grammar consists of a set of variables, constants, and rules - X => Y ... Z - + ---------------- + | X => Y ... Z | + ---------------- + where X is a variable and Y ... Z are either variables or constants. The grammar then substitutes every occurence of X by the sequence at the right-hand side Y ... Z. And there is a "starting variable", @@ -124,9 +150,11 @@ sequence, the parser needs to find all possible ways. In fact, the number of ways to generate a sequence can even be infinite. For example, if the grammar has the following two rules: - S => S - S => "" - + ----------- + | S => S | + | S => "" | + ----------- + This grammar means that S can be subtituted by S itself, and it can be substituted by the empty sequence as well. In this case, the grammar can only generate the empty sequence, but it can generate the empty @@ -168,7 +196,9 @@ RFC 5234 for its detailed definition: <https://www.rfc-editor.org/rfc/rfc5234.txt>. The reason for this choice is that the RFC documents use this format, -so there are a lot of example grammars. +so there are an abundance of mature grammars to use. For example, the +ABNF format itself has a grammar in the ABNF format, so we can use the +generated parser to parse ABNF formats, immediately. There is also a plan to let the users choose their own favourite format, of course. @@ -181,3 +211,8 @@ not to my knowledge. So I think I will briefly explain how it works. TODO: Provide more details. + +Tokenization +------------ + +There is another abstraction used by this package. -- cgit v1.2.3-18-g5258