\input texinfo.tex
@setfilename nyacc-c99-hg.info
@settitle C99 User's Guide

@include ../../memodefs.texi

@ifnottex
@node Top, Introduction, (dir), (dir)
@top Introduction
@end ifnottex

@copying
Copyright (C) 2017 -- Matthew R. Wette.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included with the distribution as COPYING.DOC.
@end copying

@c reset page header/footer then just page
@headings off
@everyfooting @| @thispage @|

@c @node Top
@c @top C99 Parser User's Guide
@c @format
@c Matt Wette
@c April 14, 2017
@c @end format
@title C99 Parser User's Guide
@subtitle rough and incomplete
@author Matt Wette
@vskip 5pt
@quotation
Copyright @copyright{} 2017 -- Matthew R. Wette.
Permissions regarding this document are provided in the ``Copying'' section.
@end quotation
@vskip 5pt

@menu
* Introduction ::
@end menu

The C99 parsers can use ``include helpers''.  This allows files to be
parsed without reading full include files.  The user provides
typenames (types defined using @code{typedef}) and defines.  The
syntax for the include-helper optional argument to the parsers is

@node Introduction
@section Introduction

This is a manual for ...

Note on CPP replacement text: IIRC, C99 will remove comments from CPP
statements before processing.  I preserve this and remove inside the
CPP parser.

@subsection Include Helpers

The C99 parsers can use ``include helpers''.  This allows files to be
parsed without reading full include files.  The user provides
typenames (types defined using @code{typedef}) and defines.  The
syntax for the include-helper optional argument to the parsers is
@example
(define my-inc-helper
 '(("foo.h" "foo_t" "ABC=123" "SUM(X,Y)=((X)+(Y))")
   ("bar.h" "bar_t" "DEF=456" "MAX(X,Y)=((X)>(Y)?(X):(Y))"))
@end example

The special helper @code{"__builtin"} will be ``included'' automatically
at the start of parsing.  This allows one to generate definitions for
compiler builtins like @code{__builtin_va_list}.
@example
(define inc-helper
 '(("__builtin" "__builtin_va_list=void*")))
@end example


The C99 @code{parser} and @code{xparser} modules export
@code{c99-std-help}.

@subsection Misc Items

The special symbol @code{C99_ANY} can be used for symbols which you
don't want to define.  In the parser will handle this as XXX

@section The Unit Parser

TALK ABOUT @code{fixed-width-int-names}

TALK ABOUT @code{c99-std-help}

TALK ABOUT @code{stripdown}

@deffn Procedure parse-c99 [#:cpp-defs def-a-list] [#:inc-dirs dir-list] [#:mode ('code|'file)] [#:debug bool]
This needs to be explained in some detail.
Default mode is @code{'code}.
@example
(with-input-from-file "abc.c"
  (parse-c #:cpp-defs '("ABC=123"))
           #:inc-dirs (append '("./incs") c99-std-dict)
           #:inc-help '(("myinc.h" "foo_t" "bar_t"))
           #:mode 'file))
@end example
@end deffn

@subsection Modes
There are several modes for parsing which affect the way the C
preprocessor statements are handled, and how the parse tree is
generated.  The following list explains the intent behind these
parsing modes.  Later we mention some fine points.
@itemize
@item @emph{code} mode (the default)
In this mode, the proprocess works like a normal C compiler.  The
preprocessor statements are evaluated as they are read and macros in
the code are expanded as they are read.
@item @emph{decl} mode
This mode is intended to be used for tools which want to
extract the declarations and definitions which are explicit in a file,
but allow access to declarations and definitions in included files.
@item @emph{file} mode
is intended to be used for tools which want to
transform C files somehow.  For example, one could parse a file and
remove all comments.  This will keep the CPP structure at the top
level.  Preprocessor statements at the top level are not evaluted.
@*
Note:
There is a change in versions starting with 0.77.0.
In these all defines required for evaluating CPP expressions in
if-then have to be resolved.
@end itemize

Options are as follows
@iffalse
@table @code
@item #:cpp-defs
This is a list of define strings (e.g., @code{'("ABC=123")}.
@item #:inc-dirs
This is an ordered list of directories to search for include files.
@item #:inc-help
This is an a-list of include helpers, where keys are the include file
or path (e.g., @code{sys/types.h}).
@item #:mode
This is the mode: @code{'code}, @code{'decl} or @code{'file}.  The default is
@code{'code}.
@item #:xdef?
This is a predicate function to determine whether to expand a
definition (used in file mode).  See below.
@end table
@fi

Note: The user needs to define 
@code{"__has_include(X)=__has_include__(X)"} to enable has-include;
@code{"__has_include=__has_include__"} will not work.  (Should I
worry that it does not?)

@deffn xdef? name mode => #t|#f
Given string @var{name} and @var{mode} indicate whether the parser
should expand using CPP defines.  The default is
@code{(lambda(name mode) (eqv? mode 'code))}.
@end deffn

@section Expression Parser

stuff


@section Copying

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included with the distribution as COPYING.DOC.

The Free Documentation License is included in the Guile Reference
Manual.  It is included with the @sc{nyacc} source as COPYING.DOC.

@bye
@c --- last line
