The cl-vhdl Reference Manual

Table of Contents

The cl-vhdl Reference Manual

This is the cl-vhdl Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:56:18 2020 GMT+0.

1 Introduction

cl-vhdl

Parser of VHDL (VHSIC Hardware Description Language) into very low-level s-exp representation. Can be used as a basis for simulators/synthetizers.

To be actually useful, must be complemented with the following:

• emitter from low-level s-exp back to VHDL source text.
• hi-level s-exp syntax, that is more convenient than the low-level one and allows for incremental compilation of parts of the design.

Main functions are VHDL-PARSE and PARSE-VHDL-FILE

(vhdl-parse 'design-file str) ; will parse a string, containing VHDL source
(parse-vhdl-file "example.vhd") ; will parse a VHDL file

TODO: -- now, when parsing fails (usually, due to some minor discrepancy in a file), error message is completely non-illuminating. The reason is, right now error reporting in ESRAP-LIQUID is not good. You may help a lot by designing a better one.

For examples, see tests.lisp

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-vhdl

Author

Alexandr Popolitov <popolit@gmail.com>

License

MIT

Description

My attempt to understand VHDL, and basicly make VHDL with Lisp-macro

Version

0.1

Dependencies

• iterate
• cl-itertools
• cl-ppcre
• cl-interpol
• esrap-liquid
• alexandria

Source

cl-vhdl.asd (file)

Components

• package.lisp (file)
• parse (module)
• cl-vhdl.lisp (file)
• sketches (file)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 cl-vhdl/parse

Dependency

package.lisp (file)

Parent

cl-vhdl (system)

Location

src/parse/

Components

• parsing-macro.lisp (file)
• parsing-ebnf.lisp (file)
• parsing.lisp (file)
• grammar (module)
• parsing-api.lisp (file)

3.2 cl-vhdl/parse/grammar

Dependency

parsing.lisp (file)

Parent

parse (module)

Location

src/parse/

Components

• parse-design-file.lisp (file)
• parse-decls.lisp (file)
• parse-concurrent.lisp (file)
• parse-sequential.lisp (file)
• parse-interfaces.lisp (file)
• parse-type.lisp (file)
• parse-expressions.lisp (file)
• parse-misc.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 cl-vhdl.asd

Location

cl-vhdl.asd

Systems

cl-vhdl (system)

4.1.2 cl-vhdl/package.lisp

Parent

cl-vhdl (system)

Location

package.lisp

Packages

cl-vhdl

4.1.3 cl-vhdl/parse/parsing-macro.lisp

Parent

parse (module)

Location

src/parse/parsing-macro.lisp

Exported Definitions

vhdl-parse (macro)

Internal Definitions

• define-c-ebnf-aux-rule (macro)
• define-c-vhdl-rule (macro)
• define-ebnf-aux-rule (macro)
• define-vhdl-rule (macro)
• ebnf-aux-contexts (special variable)
• ebnf-aux-parse (macro)
• ebnf-aux-parse-stream (macro)
• ebnf-aux-parse-token-iter (macro)
• ebnf-aux-rules (special variable)
• mk-ebnf-aux-tokenizer (macro)
• mk-vhdl-tokenizer (macro)
• register-ebnf-aux-context (macro)
• register-vhdl-context (macro)
• vhdl-contexts (special variable)
• vhdl-parse-stream (macro)
• vhdl-parse-token-iter (macro)
• vhdl-rules (special variable)
• with-ebnf-aux-contexts (macro)
• with-ebnf-aux-rules (macro)
• with-vhdl-contexts (macro)
• with-vhdl-rules (macro)

4.1.4 cl-vhdl/parse/parsing-ebnf.lisp

Dependency

parsing-macro.lisp (file)

Parent

parse (module)

Location

src/parse/parsing-ebnf.lisp

Exported Definitions

s-exp<-ebnf (function)

Internal Definitions

• *greedy-char-map* (special variable)
• *special-symbols* (special variable)
• define-plural-rule (macro)
• esrap-liquid-body (function)
• joinl (function)
• special-form-p (function)
• token-p (function)
• transform-vararg-times (function)
• update-greedy-char-seq-table (function)

4.1.5 cl-vhdl/parse/parsing.lisp

Dependency

parsing-ebnf.lisp (file)

Parent

parse (module)

Location

src/parse/parsing.lisp

Exported Definitions

• *vhdl-strict* (special variable)
• *vhdl-version* (special variable)

Internal Definitions

• $+0 (special variable)
• $-0 (special variable)
• $0 (special variable)
• %define-ebnf-rule (function)
• aif (macro)
• binary-char-p (function)
• convert-to-binary-string (function)
• define-c-ebnf-rule (macro)
• define-ebnf-rule (macro)
• fail-if-reserved (macro)
• hex-char-p (function)
• intern-here (function)
• nil-toplevel-p (function)
• octal-char-p (function)
• reserved-word-p (function)
• t-toplevel-p (function)
• toplevel (special variable)
• vhdl-reserved (special variable)
• with-list-places (macro)
• wrapping-in-label (macro)

4.1.6 cl-vhdl/parse/grammar/parse-design-file.lisp

Parent

grammar (module)

Location

src/parse/parse-design-file.lisp

4.1.7 cl-vhdl/parse/grammar/parse-decls.lisp

Parent

grammar (module)

Location

src/parse/parse-decls.lisp

4.1.8 cl-vhdl/parse/grammar/parse-concurrent.lisp

Parent

grammar (module)

Location

src/parse/parse-concurrent.lisp

4.1.9 cl-vhdl/parse/grammar/parse-sequential.lisp

Parent

grammar (module)

Location

src/parse/parse-sequential.lisp

4.1.10 cl-vhdl/parse/grammar/parse-interfaces.lisp

Parent

grammar (module)

Location

src/parse/parse-interfaces.lisp

4.1.11 cl-vhdl/parse/grammar/parse-type.lisp

Parent

grammar (module)

Location

src/parse/parse-type.lisp

4.1.12 cl-vhdl/parse/grammar/parse-expressions.lisp

Parent

grammar (module)

Location

src/parse/parse-expressions.lisp

Internal Definitions

• %shunting-yard (function)
• hash<-assoc (function)
• maybe-a-binary-operator (macro)
• not-double-quote (function)
• populate-precedence (function)
• shunting-yard (function)

4.1.13 cl-vhdl/parse/grammar/parse-misc.lisp

Parent

grammar (module)

Location

src/parse/parse-misc.lisp

4.1.14 cl-vhdl/parse/parsing-api.lisp

Dependency

grammar (module)

Parent

parse (module)

Location

src/parse/parsing-api.lisp

Exported Definitions

parse-vhdl-file (function)

4.1.15 cl-vhdl/cl-vhdl.lisp

Dependency

parse (module)

Parent

cl-vhdl (system)

Location

cl-vhdl.lisp

Internal Definitions

foo (function)

4.2 Static

4.2.1 cl-vhdl/sketches

Dependency

cl-vhdl.lisp (file)

Parent

cl-vhdl (system)

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-vhdl-20160421-git/sketches (not found)

5 Packages

Packages are listed by definition order.

5.1 cl-vhdl

Source

package.lisp (file)

Use List

• cl-itertools
• iterate
• esrap-liquid
• common-lisp

Exported Definitions

• *vhdl-strict* (special variable)
• *vhdl-version* (special variable)
• parse-vhdl-file (function)
• s-exp<-ebnf (function)
• vhdl-parse (macro)

Internal Definitions

• $+0 (special variable)
• $-0 (special variable)
• $0 (special variable)
• %define-ebnf-rule (function)
• %shunting-yard (function)
• *greedy-char-map* (special variable)
• *special-symbols* (special variable)
• aif (macro)
• binary-char-p (function)
• convert-to-binary-string (function)
• define-c-ebnf-aux-rule (macro)
• define-c-ebnf-rule (macro)
• define-c-vhdl-rule (macro)
• define-ebnf-aux-rule (macro)
• define-ebnf-rule (macro)
• define-plural-rule (macro)
• define-vhdl-rule (macro)
• ebnf-aux-contexts (special variable)
• ebnf-aux-parse (macro)
• ebnf-aux-parse-stream (macro)
• ebnf-aux-parse-token-iter (macro)
• ebnf-aux-rules (special variable)
• esrap-liquid-body (function)
• fail-if-reserved (macro)
• foo (function)
• hash<-assoc (function)
• hex-char-p (function)
• intern-here (function)
• joinl (function)
• maybe-a-binary-operator (macro)
• mk-ebnf-aux-tokenizer (macro)
• mk-vhdl-tokenizer (macro)
• nil-toplevel-p (function)
• not-double-quote (function)
• octal-char-p (function)
• populate-precedence (function)
• register-ebnf-aux-context (macro)
• register-vhdl-context (macro)
• reserved-word-p (function)
• shunting-yard (function)
• special-form-p (function)
• t-toplevel-p (function)
• token-p (function)
• toplevel (special variable)
• transform-vararg-times (function)
• update-greedy-char-seq-table (function)
• vhdl-contexts (special variable)
• vhdl-parse-stream (macro)
• vhdl-parse-token-iter (macro)
• vhdl-reserved (special variable)
• vhdl-rules (special variable)
• with-ebnf-aux-contexts (macro)
• with-ebnf-aux-rules (macro)
• with-list-places (macro)
• with-vhdl-contexts (macro)
• with-vhdl-rules (macro)
• wrapping-in-label (macro)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *vhdl-strict*

When this parameter is NIL, some restrictions on possible VHDL syntax are relaxed, so as to make it more lispy

Package

cl-vhdl

Source

parsing.lisp (file)

Special Variable: *vhdl-version*

Package

cl-vhdl

Source

parsing.lisp (file)

6.1.2 Macros

Macro: vhdl-parse EXPRESSION TEXT &key START END JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

6.1.3 Functions

Function: parse-vhdl-file FILE-NAME &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-api.lisp (file)

Function: s-exp<-ebnf SYNTAX

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: $+0

Package

cl-vhdl

Source

parsing.lisp (file)

Special Variable: $-0

Package

cl-vhdl

Source

parsing.lisp (file)

Special Variable: $0

Package

cl-vhdl

Source

parsing.lisp (file)

Special Variable: *greedy-char-map*

In this, all the dynamically found misc keywords would be placed, for later greedy parsing

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Special Variable: *special-symbols*

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Special Variable: ebnf-aux-contexts

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Special Variable: ebnf-aux-rules

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Special Variable: toplevel

Package

cl-vhdl

Source

parsing.lisp (file)

Special Variable: vhdl-contexts

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Special Variable: vhdl-reserved

Package

cl-vhdl

Source

parsing.lisp (file)

Special Variable: vhdl-rules

Package

cl-vhdl

Source

parsing-macro.lisp (file)

6.2.2 Macros

Macro: aif TEST THEN &optional ELSE

Package

cl-vhdl

Source

parsing.lisp (file)

Macro: define-c-ebnf-aux-rule SYMBOL ARGS &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: define-c-ebnf-rule NAME SYNTAX &body BODY

Package

cl-vhdl

Source

parsing.lisp (file)

Macro: define-c-vhdl-rule SYMBOL ARGS &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: define-ebnf-aux-rule SYMBOL ARGS &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: define-ebnf-rule NAME SYNTAX &body BODY

Package

cl-vhdl

Source

parsing.lisp (file)

Macro: define-plural-rule NAME SINGLE DELIM

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Macro: define-vhdl-rule SYMBOL ARGS &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: ebnf-aux-parse EXPRESSION TEXT &key START END JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: ebnf-aux-parse-stream EXPRESSION STREAM &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: ebnf-aux-parse-token-iter EXPRESSION TOKEN-ITER &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: fail-if-reserved &optional THING

Package

cl-vhdl

Source

parsing.lisp (file)

Macro: maybe-a-binary-operator ()

Package

cl-vhdl

Source

parse-expressions.lisp (file)

Macro: mk-ebnf-aux-tokenizer EXPRESSION TOKEN-ITER &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: mk-vhdl-tokenizer EXPRESSION TOKEN-ITER &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: register-ebnf-aux-context CONTEXT-VAR &rest PLAUSIBLE-CONTEXTS

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: register-vhdl-context CONTEXT-VAR &rest PLAUSIBLE-CONTEXTS

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: vhdl-parse-stream EXPRESSION STREAM &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: vhdl-parse-token-iter EXPRESSION TOKEN-ITER &key JUNK-ALLOWED

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: with-ebnf-aux-contexts &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: with-ebnf-aux-rules &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: with-list-places (LST) &body BODY

Package

cl-vhdl

Source

parsing.lisp (file)

Macro: with-vhdl-contexts &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: with-vhdl-rules &body BODY

Package

cl-vhdl

Source

parsing-macro.lisp (file)

Macro: wrapping-in-label &optional EXPR

Package

cl-vhdl

Source

parsing.lisp (file)

6.2.3 Functions

Function: %define-ebnf-rule NAME SYNTAX BODY &key CONTEXT-SENSITIVE

Package

cl-vhdl

Source

parsing.lisp (file)

Function: %shunting-yard CUR-OP CUR-LST LST-ITER &optional TOPLEVEL-P

Package

cl-vhdl

Source

parse-expressions.lisp (file)

Function: binary-char-p X

Package

cl-vhdl

Source

parsing.lisp (file)

Function: convert-to-binary-string STR INIT-RADIX &optional EXPAND-UNKNOWN-CHARS

Package

cl-vhdl

Source

parsing.lisp (file)

Function: esrap-liquid-body THING

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Function: foo &optional JUNK-ALLOWED

Package

cl-vhdl

Source

cl-vhdl.lisp (file)

Function: hash<-assoc X

Package

cl-vhdl

Source

parse-expressions.lisp (file)

Function: hex-char-p X

Package

cl-vhdl

Source

parsing.lisp (file)

Function: intern-here X

Package

cl-vhdl

Source

parsing.lisp (file)

Function: joinl JOINEE LST

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Function: nil-toplevel-p X

Package

cl-vhdl

Source

parsing.lisp (file)

Function: not-double-quote X

Package

cl-vhdl

Source

parse-expressions.lisp (file)

Function: octal-char-p X

Package

cl-vhdl

Source

parsing.lisp (file)

Function: populate-precedence LST

Package

cl-vhdl

Source

parse-expressions.lisp (file)

Function: reserved-word-p SYM

Package

cl-vhdl

Source

parsing.lisp (file)

Function: shunting-yard LST OPS

I actually don’t know if it’s an actual shunting yard of Dijkstra – I just thought about my own solution.

Package

cl-vhdl

Source

parse-expressions.lisp (file)

Function: special-form-p X

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Function: t-toplevel-p X

Package

cl-vhdl

Source

parsing.lisp (file)

Function: token-p X

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Function: transform-vararg-times EXPR

Here we recursively look for all { ... }’s and replace them with +’s

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Function: update-greedy-char-seq-table STR

Package

cl-vhdl

Source

parsing-ebnf.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types