bluespec-docs/content/chapter1/_index.md

+++
title = "Introduction"
weight = 1
sort_by = "weight"
insert_anchor_links = "right"
+++

BH (Bluespec Haskell/Classic) is a language for hardware design. The
language borrows its notation, type and package system from an existing
general-purpose functional programming language called Haskell
[@haskell12] where those constructs have been well tested for over a
decade. Unlike Haskell, BH is meant solely for hardware design--- a BH
program represents a circuit. The abstract model for these circuits is a
Term Rewriting System (TRS); details about using TRSs for describing
circuits, and compiling these descriptions to real hardware, may be
found in James Hoe's thesis [@jhoe]. BH has several restrictions and
extensions relative to Haskell, arising out of this hardware focus.


This document is not meant as a tutorial on BH (separate documents exist
for that purpose). Nevertheless, this document has numerous small
examples to explicate BH notation.


## Meta notation


The grammar rules in the presentation below mostly follow the usual EBNF
(Extended BNF) structure. Grammar alternatives are separated by
"$\mid$". Items enclosed in \[ \] are optional. Items enclosed in { }
can be repeated zero or more times. The last piece of notation is used
sloppily; sometimes there must be at least one item, and also, the last
terminal inside the { } is sometimes a separator rather than terminator.


## Identifiers and the rôle of upper and lower case


An identifier in BH consists of a letter followed by zero or more
letters, digits, underscores and single quotes. Identifiers are case
sensitive: `glurph`, `gluRph` and `Glurph` are three distinct
identifiers.


The case of the first letter in an identifier is very important. If the
first letter is lower case, the identifier is a "variable identifier",
referred to in the grammar rules as a *varId*. If the first letter is
upper case, the identifier is a "constructor identifier", referred to in
the grammar rules as a *conId*.


In BH, package names (*packageId*), type names (*tycon*) and value
constructor names are all constructor identifiers. (Ordinary) variables,
field names and type variables are all variable identifiers.


A lone underscore, "` `", is treated as a special identifier--- it is
used as a "don't care" pattern or expression (more details in Sections
[5.10](fixme) and
[6.1](fixme)).


## The Standard Prelude


The Standard Prelude is a predefined package that is imported implicitly
into every BH package. It contains a number of useful predefined
entities (types, values/functions, classes, instances, etc.). It is
somewhat analogous to the combination of various ".h" files and standard
libraries in C, except that in BH no special action is needed to import
the prelude or to link it in. We will refer to the prelude periodically
in the following sections, and there are more details in appendix
[15](fixme).


## Lexical syntax/layout


In BH, there are various syntactic constructs that involve zero or more
items enclosed in braces and separated by semicolons:  These braces and semicolons can be omitted
entirely if the components are laid out with proper indentation.


Suppose the parser discovers a missing open brace (e.g., after the
keywords `where`, `let`, `do` and `of`). Then, the indentation of the
next lexical element is remembered (and the missing open brace is
implicitly inserted before it). For each subsequent line, if it contains
only whitespace or is indented more, then it is treated as a
continuation of the current item. If it is indented the same amount, it
is treated as the beginning of the next item (*i.e.,* a semicolon is
inserted implicitly before the item). If it is indented less, then the
list of items is considered to be complete (*i.e.,* a closing brace is
implicitly inserted). An explicit brace is never matched against an
implicit one. Thus, while using the layout rule, if the parser
encounters an explicit open brace, then it does not resume using the
layout rule for this list of items until it has "emerged" past the
explicit corresponding closing brace (a construct nested inside this
list of items may still use the layout rule).


## Comments in BH programs


In a BH program, a *comment* is legal as whitespace, and may be
introduced in two ways. An *ordinary comment* is introduced by a lexical
token consisting of two or more consecutive dashes followed by a
non-symbol, and extends up to and including the end of the line. (See
Section
[\[sec-infix-applications\]](fixme) for the list of symbols.) Note: the
lexical token `—>` is a legal token in BH, and since it contains three
consecutive dashes followed by a symbol, it does not begin a comment.


A *nested comment* is introduced by the lexeme "`{-`" and extends until
the next matching "`-}`", possibly spanning multiple lines. A nested
comment can itself contain another nested comment; this nesting can be
repeated to any depth.


In an ordinary comment, the character sequences "`{-`" and "`-}`" have
no special significance, and, in a nested comment, a sequence of dashes
has no special significance.


## General organization of this document


A concept that is pervasive in BH is the notion of a *type*. Every value
expression in BH, even a basic value identifier, has a type, and the
compiler does extensive static type checking to rule out absurd use of
values (such as taking the square root of an IP address). Types are
discussed in section [2](fixme).


A BH program consists of one or more packages. These outermost
constructs are described in section
[3](fixme). As
explained later, a BH package is a linguistic namespace-management
mechanism and does not have any direct correlation with any hardware
module being described by the program. Hardware modules correspond to
*modules*, a particular type of value in BH.


Within each package is a collection of top-level definitions. These are
described in section [4](fixme).


Amongst the top-level definitions are *value definitions* (section
[4.7](fixme)),
which constitute the actual meat of the code. Value definitions are
built around *expressions*, which are described in section
[5](fixme).