#lang scribble/doc

@begin[(require scribble/manual)
       (require scribble/eval)
       (require scribble/basic)
       (require (for-label (except-in scheme/base exn:fail:syntax struct:exn:fail:syntax make-exn:fail:syntax exn:fail:syntax?)))
       (require (for-label scheme/contract))
       (require (for-label "../syntax.ss"))
       (require "utils.ss")]

@title[#:tag "syntax"]{C Syntax}

This library provides data types representing C abstract syntax, a C parser,
and macros for constructing C abstract syntax with a convenient parenthesized syntax.
It can be required via:

@defmodule/this-package[syntax]

@section[#:tag "expressions"]{Expressions}

@defstruct[expr:lit ([type symbol?] [value any])]{}
@defstruct[expr:binop ([op symbol?] [left expr?] [right expr?])]{}

@section[#:tag "declarations"]{Declarations}

@;XXX: generalize this contract
@defstruct[decl:type:def ([root type?] [defs (listof (cons symbol? #f))])]{}
@defstruct[decl:type:tagged ([type (or/c type:struct? type:union? type:enum?)])]{}

@section[#:tag "types"]{Types}

@defstruct[type:ref ([name symbol?])]{}
@defstruct[type:struct ([tag (optional symbol?)] [fields (listof (cons symbol? type?))])]{}
@defstruct[type:union ([tag (optional symbol?)] [variants (listof (cons symbol? type?))])]{}
@;XXX: fix this contract
@defstruct[type:enum ([tag (optional symbol?)] [variants list?])]{}
@defstruct[type:array ([type type?] [size expr?])]{}
@defstruct[type:pointer ([type type?])]{}
@;XXX: optional argument names?
@defstruct[type:function ([return type?] [args (listof type?)])]{}

@section[#:tag "utilities"]{Utility Functions}

@defproc[(type? (x any)) boolean?]{Determines whether @scheme[x] is a type.}
@defproc[(expr? (x any)) boolean?]{Determines whether @scheme[x] is an expression.}
@defproc[(decl? (x any)) boolean?]{Determines whether @scheme[x] is a declaration.}

@section[#:tag "pseudo-c"]{S-Expression Syntax}

@deftogether[[
@defform/subs[#:id typedef
              (typedef type alias-id)
              ([type struct type-id])]
@defform*/subs[#:id struct
               [(struct tag-id)
                (struct tag-id (struct-field ...))
                (struct (struct-field ...))]
               [(struct-field [type field-id] field-id)]]
@defform*/subs[#:id union
               [(union tag-id)
                (union tag-id (union-variant ...))
                (union (union-variant ...))]
               [(union-variant [type variant-id] variant-id)]]
@defform*/subs[#:id enum
               [(enum tag-id)
                (enum tag-id (enum-variant ...))
                (enum (enum-variant ...))]
               [(enum-variant [variant-id expr] variant-id)]]
]]

@defproc[(array [type type?] [size expr?]) type:array?]{}
@defproc[(pointer [type type?]) type:pointer?]{}

@section[#:tag "parse"]{Parsing}

@defproc[(parse-decl [in (or/c input-port? string? path?)]) decl?]{Parses a C declaration.}
@defproc[(parse-decls [in (or/c input-port? string? path?)]) (listof decl?)]{Parses a sequence of C declarations.}

@section[#:tag "reader"]{C Reader}

The module

@defmodule/this-package[reader]

provides a reader for C syntax. Using this reader, it is possible to embed C syntax
directly into Scheme programs. For example:

@schemeblock[
(define decls
  #, @schemekeywordfont|{#reader}| (planet dherman/c/reader) #, @schemeparenfont|{{}|
  #, @schemefont|{  typedef int INT;}|
  #, @schemefont|{  struct tm {}|
  #, @schemefont|{      INT tm_sec;}|
  #, @schemefont|{      INT tm_min;}|
  #, @schemefont|{      INT tm_hour;}|
  #, @schemefont|{      INT tm_mday;}|
  #, @schemefont|{      INT tm_mon;}|
  #, @schemefont|{      INT tm_year;}|
  #, @schemefont|{      INT tm_wday;}|
  #, @schemefont|{      INT tm_yday;}|
  #, @schemefont|{      INT tm_isdst;}|
  #, @schemefont|{  };}|
  #, @schemeparenfont|{}}|)
]

The C reader produces a quoted literal list of declarations.