diff options
| -rw-r--r-- | doc/flex.texi | 67 | ||||
| -rw-r--r-- | src/c99-flex.skl | 30 | ||||
| -rw-r--r-- | src/cpp-flex.skl | 30 |
3 files changed, 52 insertions, 75 deletions
diff --git a/doc/flex.texi b/doc/flex.texi index 9453e6b..faee28c 100644 --- a/doc/flex.texi +++ b/doc/flex.texi @@ -8688,6 +8688,16 @@ to appear in a URI, including spaces and control characters. See This appendix describes how to add support for a new target language to Flex. +@menu +* Overview:: +* Getting Started:: +* Development Steps:: +* Translation Guidelines:: +@end menu + +@node Overview, , , Retargeting Flex +@subsection Overview + The Flex code has been factored to isolate knowledge of the specifics of each target language from the logic for building the lexer state/transition tables. Code in the target language is generated via @@ -8719,9 +8729,35 @@ file named @file{cpp_backend.c} (so named because both languages use the C preprocessor), and in a skeleton file named @file{cpp-flex.skl} which is digested into a member of the method table when Flex is built. -To get started on writing a new back end, read the definition of -struct backend_t in @file{src/flexdefs.h}, and attached comments -first. Then read a skeleton file. +@node Getting Started, Development Steps, Overview, Retargeting Flex +@subsection Getting Started + +To get started on writing a new back end, browse +@code{src/skeletons,c} to get some idea of how skeleton files are +queried, then read a skeleton file. If no sketon exists of a language +that is closer to your target, the C99 back end is specifically +intended to be cloned and used as a launch pont for new back ends. + +This file you are looking at is processed through GNU m4 during the +pre-compilation stage of Flex. At this time only macros starting with +`m4preproc_' are processed, and quoting is normal. The main purpose of +this expansion phase is to set Flex version symbols. + +At Flex compilation time, the preprocessed skeleton is translated into a comma-separated +list of doublequoted strings which is stuffed into a language- +specific method block compiled into the flex binary. + +At scanner generation time, , the skeleton is generated and filtered +(again) through m4. Macros beginning with `m4_' will be processed. +The quoting is "[[" and "]]" so we don't interfere with user code. + +A line beginning with ``%# `` is comment. Thesev comments are omitted +from the generated scanner. + +A line beginning with ``%%'' us stop-point, where code is inserted by +Flex. Each stop-point is numbered here and also in the code +generator. Stop points will be inserted into the generated scanner as +a comment. This is to aid those who edit skeletons. You'll want to start by studying the @code{M4_PROPERTY_*} macros near the top of the skeleton file. They declare properties of the back end like @@ -8745,18 +8781,24 @@ generated code. The names of such macros have the prefixes grepping for these prefixes. Many of these symbols correspond to Flex command-line options. +@node Development Steps, Translation Guidelines, Getting Started, Retargeting Flex +@subsection Development Steps + To write support for a language, you'll want to do the following steps: @enumerate @item -Clone one of the existing back-end/skeleton pairs. If the language -you are supporting is named @var{foo}, you should create files named -@file{foo_backend.c} and @file{foo-flex.skl}. +Clone one of the existing skeletons. If the language you are +supporting is named @var{foo}, you should create a file named +@file{foo-flex.skl}. @item -Add @file{foo_backend.c} to COMMON_SOURCES in @file{src/Makefile.am}. Add the -name of your skeleton file to EXTRA_DIST. +Modify @code{skeleton.c} to ass the digested form of your skeleton +to the @code{backends} list. + +@item +Add the name of your skeleton file to EXTRA_DIST. @item Add a production to @file{src/Makefile.am} parallel to the one that @@ -8765,12 +8807,6 @@ initializer from your skeleton file that can be linked with flex and is pointed at by the skel nember of your language back end. @item -Add some logic to @file{main.c} that enables the new back end with a -new Flex option. Following this step you should be -able to run Flex on a specification and get code out in the -language of whatever back end you cloned. - -@item The interesting part: mutate your new back end and skeleton so they produce code in your desired target langage. @@ -8794,7 +8830,8 @@ complexity of what needs to be translated to a new target language. These features are: the Bison bridge, header generation, and loadable tables. -Some notes about the interesting part: +@node Translation Guidelines, , Development Steps, Retargeting Flex +@subsection Translation Guidelines @itemize @item diff --git a/src/c99-flex.skl b/src/c99-flex.skl index 5a1f119..6a4c245 100644 --- a/src/c99-flex.skl +++ b/src/c99-flex.skl @@ -1,20 +1,4 @@ %# -*-C-*- vi: set ft=c: -%# This file is processed in several stages. -%# Here are the stages, as best as I can describe: -%# -%# 1. This is processed through GNU m4 during the -%# pre-compilation stage of flex. Only macros starting -%# with `m4preproc_' are processed, and quoting is normal. -%# -%# 2. The preprocessed skeleton is translated into a comma-separated -%# list of doublequoted strings which is stuffed into a language- -%# specific method block compiled into the flex binary. The %# comment -%# lines are removed. -%# -%# 3. At runtime, the skeleton is generated and filtered (again) -%# through m4. Macros beginning with `m4_' will be processed. -%# The quoting is "[[" and "]]" so we don't interfere with -%# user code. %# %# All generated macros for the m4 stage contain the text "m4" or "M4" %# in them. This is to distinguish them from CPP macros. @@ -36,20 +20,6 @@ m4_changecom m4_changequote m4_changequote([[, ]]) -%# -%# Lines in this skeleton starting with a "%" character are "control lines" -%# and affect the generation of the scanner. The possible control codes are -%# listed and processed in misc.c. -%# -%# %# - A comment. The current line is omitted from the generated scanner. -%# %% - A stop-point, where code is inserted by flex. -%# Each stop-point is numbered here and also in the code generator. -%# (See gen.c, etc. for details.) -%# -%# Stop points will be inserted into the generated scanner as a comment. -%# This is to aid those who edit the skeleton. -%# - %# Properties not used in the skeleton - meant to be read by the Flex code m4_define([[M4_PROPERTY_BACKEND_NAME]], [[C99]]) m4_define([[M4_PROPERTY_SOURCE_SUFFIX]], [[.c]]) diff --git a/src/cpp-flex.skl b/src/cpp-flex.skl index aec3538..6c0920a 100644 --- a/src/cpp-flex.skl +++ b/src/cpp-flex.skl @@ -1,20 +1,4 @@ %# -*-C-*- vi: set ft=c: -%# This file is processed in several stages. -%# Here are the stages, as best as I can describe: -%# -%# 1. This is processed through GNU m4 during the -%# pre-compilation stage of flex. Only macros starting -%# with `m4preproc_' are processed, and quoting is normal. -%# -%# 2. The preprocessed skeleton is translated into a comma-separated -%# list of doublequoted strings which is stuffed into a language- -%# specific method block compiled into the flex binary. The %# comment -%# lines are removed. -%# -%# 3. At runtime, the skeleton is generated and filtered (again) -%# through m4. Macros beginning with `m4_' will be processed. -%# The quoting is "[[" and "]]" so we don't interfere with -%# user code. %# %# All generated macros for the m4 stage contain the text "m4" or "M4" %# in them. This is to distinguish them from CPP macros. @@ -36,20 +20,6 @@ m4_changecom m4_changequote m4_changequote([[, ]]) -%# -%# Lines in this skeleton starting with a "%" character are "control lines" -%# and affect the generation of the scanner. The possible control codes are -%# listed and processed in misc.c. -%# -%# %# - A comment. The current line is omitted from the generated scanner. -%# %% - A stop-point, where code is inserted by flex. -%# Each stop-point is numbered here and also in the code generator. -%# (See gen.c, etc. for details.) -%# -%# Stop points will be inserted into the generated scanner as a comment. -%# This is to aid those who edit the skeleton. -%# - %# Properties not used in the skeleton - meant to be read by the Flex code m4_define([[M4_PROPERTY_BACKEND_NAME]], [[C/C++]]) %#m4_define([[M4_PROPERTY_SOURCE_SUFFIX]], [[]]) |