clash-lib-1.8.1: Clash: a functional hardware description language - As a library

Copyright | (C) 2020 QBayLogic B.V. 2022 Google Inc.
License | BSD2 (see the file LICENSE)
Maintainer | QBayLogic B.V. <devops@qbaylogic.com>
Safe Haskell | Safe-Inferred
Language | Haskell2010

Clash.Netlist.Id

Contents

- Utilities to use IdentifierSet
- Unsafe creation and extracting identifiers
- Creating and extending identifiers
- Misc. and internals

Description

Transform/format a Netlist Identifier so that it is acceptable as a HDL identifier

Synopsis

- data IdentifierSet
- class Monad m => IdentifierSetMonad m where
  - identifierSetM :: (IdentifierSet -> IdentifierSet) -> m IdentifierSet
- class HasIdentifierSet s where
  - identifierSet :: Lens' s IdentifierSet
- emptyIdentifierSet :: Bool -> PreserveCase -> HDL -> IdentifierSet
- makeSet :: Bool -> PreserveCase -> HDL -> HashSet Identifier -> IdentifierSet
- clearSet :: IdentifierSet -> IdentifierSet
- data Identifier
- data IdentifierType
  - = Basic
  - | Extended
- unsafeMake :: HasCallStack => Text -> Identifier
- unsafeFromCoreId :: HasCallStack => Id -> Identifier
- toText :: Identifier -> Text
- toLazyText :: Identifier -> Text
- toList :: IdentifierSet -> [Identifier]
- union :: HasCallStack => IdentifierSet -> IdentifierSet -> IdentifierSet
- make :: (HasCallStack, IdentifierSetMonad m) => Text -> m Identifier
- makeBasic :: (HasCallStack, IdentifierSetMonad m) => Text -> m Identifier
- makeBasicOr :: (HasCallStack, IdentifierSetMonad m) => Text -> Text -> m Identifier
- makeAs :: (HasCallStack, IdentifierSetMonad m) => IdentifierType -> Text -> m Identifier
- add :: HasCallStack => IdentifierSetMonad m => Identifier -> m ()
- addMultiple :: (HasCallStack, IdentifierSetMonad m, Foldable t) => t Identifier -> m ()
- addRaw :: (HasCallStack, IdentifierSetMonad m) => Text -> m Identifier
- deepen :: (HasCallStack, IdentifierSetMonad m) => Identifier -> m Identifier
- deepenN :: (HasCallStack, IdentifierSetMonad m) => Int -> Identifier -> m [Identifier]
- next :: (HasCallStack, IdentifierSetMonad m) => Identifier -> m Identifier
- nextN :: (HasCallStack, IdentifierSetMonad m) => Int -> Identifier -> m [Identifier]
- prefix :: (HasCallStack, IdentifierSetMonad m) => Identifier -> Text -> m Identifier
- suffix :: (HasCallStack, IdentifierSetMonad m) => Identifier -> Text -> m Identifier
- fromCoreId :: (HasCallStack, IdentifierSetMonad m) => Id -> m Identifier
- stripDollarPrefixes :: Text -> Text
- toBasicId# :: HDL -> PreserveCase -> Text -> Text
- isBasic# :: HDL -> Text -> Bool
- isExtended# :: HDL -> Text -> Bool

# Utilities to use IdentifierSet

data IdentifierSet Source #

A collection of unique identifiers. Allows for fast fresh identifier generation.

NB: use the functions in Clash.Netlist.Id. Don't use the constructor directly.

#### Instances

Instances details

Generic IdentifierSet Source # |
Instance details Defined in Clash.Netlist.Types Associated Types type Rep IdentifierSet :: Type -> Type Source # Methods from :: IdentifierSet -> Rep IdentifierSet x Source # to :: Rep IdentifierSet x -> IdentifierSet Source #
Show IdentifierSet Source # |
Instance details Defined in Clash.Netlist.Types Methods showsPrec :: Int -> IdentifierSet -> ShowS Source # show :: IdentifierSet -> String Source # showList :: [IdentifierSet] -> ShowS Source #
HasIdentifierSet IdentifierSet Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSet :: Lens' IdentifierSet IdentifierSet Source #
NFData IdentifierSet Source # |
Instance details Defined in Clash.Netlist.Types Methods rnf :: IdentifierSet -> () Source #
type Rep IdentifierSet Source # |

Instance details

Defined in Clash.Netlist.Types

type Rep IdentifierSet = D1 ('MetaData "IdentifierSet" "Clash.Netlist.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "IdentifierSet" 'PrefixI 'True) ((S1 ('MetaSel ('Just "is_allowEscaped") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool) :*: S1 ('MetaSel ('Just "is_lowerCaseBasicIds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 PreserveCase)) :*: (S1 ('MetaSel ('Just "is_hdl") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 HDL) :*: (S1 ('MetaSel ('Just "is_freshCache") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 FreshCache) :*: S1 ('MetaSel ('Just "is_store") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (HashSet Identifier))))))

class Monad m => IdentifierSetMonad m where Source #

An IdentifierSetMonad supports unique name generation for Clash Netlist

Methods

identifierSetM :: (IdentifierSet -> IdentifierSet) -> m IdentifierSet Source #

#### Instances

Instances details

IdentifierSetMonad NetlistMonad Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSetM :: (IdentifierSet -> IdentifierSet) -> NetlistMonad IdentifierSet Source #
HasIdentifierSet s => IdentifierSetMonad (State s) Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSetM :: (IdentifierSet -> IdentifierSet) -> State s IdentifierSet Source #
HasIdentifierSet s => IdentifierSetMonad (State s) Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSetM :: (IdentifierSet -> IdentifierSet) -> State s IdentifierSet Source #
IdentifierSetMonad m => IdentifierSetMonad (Ap m) Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSetM :: (IdentifierSet -> IdentifierSet) -> Ap m IdentifierSet Source #

class HasIdentifierSet s where Source #

Structures that hold an `IdentifierSet`

Methods

identifierSet :: Lens' s IdentifierSet Source #

#### Instances

Instances details

HasIdentifierSet SystemVerilogState Source # |
Instance details Defined in Clash.Backend.SystemVerilog Methods identifierSet :: Lens' SystemVerilogState IdentifierSet Source #
HasIdentifierSet VHDLState Source # |
Instance details Defined in Clash.Backend.VHDL Methods identifierSet :: Lens' VHDLState IdentifierSet Source #
HasIdentifierSet VerilogState Source # |
Instance details Defined in Clash.Backend.Verilog Methods identifierSet :: Lens' VerilogState IdentifierSet Source #
HasIdentifierSet IdentifierSet Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSet :: Lens' IdentifierSet IdentifierSet Source #
Backend backend => HasIdentifierSet (BlockState backend) Source # |
Instance details Defined in Clash.Primitives.DSL Methods identifierSet :: Lens' (BlockState backend) IdentifierSet Source #
HasIdentifierSet s => HasIdentifierSet (s, a) Source # |
Instance details Defined in Clash.Netlist.Types Methods identifierSet :: Lens' (s, a) IdentifierSet Source #

emptyIdentifierSet Source #

Arguments

:: Bool | Allow escaped identifiers?
-> PreserveCase | Should all basic identifiers be lower case?
-> HDL | HDL to generate names for
-> IdentifierSet |

Identifier set without identifiers

makeSet Source #

Arguments

:: Bool | Allow escaped identifiers?
-> PreserveCase | Should all basic identifiers be lower case?
-> HDL | HDL to generate names for
-> HashSet Identifier | Identifiers to add to set
-> IdentifierSet |

Make a identifier set filled with given identifiers

clearSet :: IdentifierSet -> IdentifierSet Source #

Remove all identifiers from a set

# Unsafe creation and extracting identifiers

data Identifier Source #

HDL identifier. Consists of a base name and a number of extensions. An identifier with a base name of "foo" and a list of extensions [1, 2] will be rendered as "foo_1_2".

Note: The Eq instance of Identifier is case insensitive! E.g., two identifiers with base names `fooBar` and `FoObAR` are considered the same. However, identifiers are stored case preserving. This means Clash won't generate two identifiers with differing case, but it will try to keep capitalization.

The goal of this data structure is to greatly simplify how Clash deals with identifiers internally. Any Identifier should be trivially printable to any HDL.

NB: use the functions in Clash.Netlist.Id. Don't use these constructors directly.

#### Instances

Instances details

Generic Identifier Source # |
Instance details Defined in Clash.Netlist.Types Associated Types type Rep Identifier :: Type -> Type Source # Methods from :: Identifier -> Rep Identifier x Source # to :: Rep Identifier x -> Identifier Source #
Show Identifier Source # |
Instance details Defined in Clash.Netlist.Types Methods showsPrec :: Int -> Identifier -> ShowS Source # show :: Identifier -> String Source # showList :: [Identifier] -> ShowS Source #
NFData Identifier Source # |
Instance details Defined in Clash.Netlist.Types Methods rnf :: Identifier -> () Source #
Eq Identifier Source # |
Instance details Defined in Clash.Netlist.Types Methods (==) :: Identifier -> Identifier -> Bool Source # (/=) :: Identifier -> Identifier -> Bool Source #
Ord Identifier Source # |

Instance details

Defined in Clash.Netlist.Types

Methods

compare :: Identifier -> Identifier -> Ordering Source #

(<) :: Identifier -> Identifier -> Bool Source #

(<=) :: Identifier -> Identifier -> Bool Source #

(>) :: Identifier -> Identifier -> Bool Source #

(>=) :: Identifier -> Identifier -> Bool Source #

max :: Identifier -> Identifier -> Identifier Source #

min :: Identifier -> Identifier -> Identifier Source #

Hashable Identifier Source # |
Instance details Defined in Clash.Netlist.Types Methods hashWithSalt :: Int -> Identifier -> Int Source # hash :: Identifier -> Int Source #
Pretty Identifier Source # |
Instance details Defined in Clash.Netlist.Id.Internal Methods pretty :: Identifier -> Doc ann Source # prettyList :: [Identifier] -> Doc ann Source #
type Rep Identifier Source # |

Instance details

Defined in Clash.Netlist.Types

type Rep Identifier = D1 ('MetaData "Identifier" "Clash.Netlist.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "RawIdentifier" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Identifier)) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 CallStack))) :+: C1 ('MetaCons "UniqueIdentifier" 'PrefixI 'True) ((S1 ('MetaSel ('Just "i_baseName") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: (S1 ('MetaSel ('Just "i_baseNameCaseFold") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: S1 ('MetaSel ('Just "i_extensionsRev") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Word]))) :*: (S1 ('MetaSel ('Just "i_idType") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 IdentifierType) :*: (S1 ('MetaSel ('Just "i_hdl") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 HDL) :*: S1 ('MetaSel ('Just "i_provenance") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 CallStack)))))

data IdentifierType Source #

Constructors

Basic | A basic identifier: does not have to be escaped in order to be a valid identifier in HDL.
Extended | An extended identifier: has to be escaped, wrapped, or otherwise postprocessed before writhing it to HDL.

#### Instances

Instances details

Generic IdentifierType Source # |
Instance details Defined in Clash.Netlist.Types Associated Types type Rep IdentifierType :: Type -> Type Source # Methods from :: IdentifierType -> Rep IdentifierType x Source # to :: Rep IdentifierType x -> IdentifierType Source #
Show IdentifierType Source # |
Instance details Defined in Clash.Netlist.Types Methods showsPrec :: Int -> IdentifierType -> ShowS Source # show :: IdentifierType -> String Source # showList :: [IdentifierType] -> ShowS Source #
NFData IdentifierType Source # |
Instance details Defined in Clash.Netlist.Types Methods rnf :: IdentifierType -> () Source #
Eq IdentifierType Source # |
Instance details Defined in Clash.Netlist.Types Methods (==) :: IdentifierType -> IdentifierType -> Bool Source # (/=) :: IdentifierType -> IdentifierType -> Bool Source #
type Rep IdentifierType Source # |
Instance details Defined in Clash.Netlist.Types type Rep IdentifierType = D1 ('MetaData "IdentifierType" "Clash.Netlist.Types" "clash-lib-1.8.1-9u9U7p5PpHf8vtRevUOpPF" 'False) (C1 ('MetaCons "Basic" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Extended" 'PrefixI 'False) (U1 :: Type -> Type))

unsafeMake :: HasCallStack => Text -> Identifier Source #

Like `addRaw`, `unsafeMake` creates an identifier that will be spliced at verbatim in the HDL. As opposed to `addRaw`, the resulting Identifier might be generated at a later point as it is NOT added to an IdentifierSet.

unsafeFromCoreId :: HasCallStack => Id -> Identifier Source #

Like 'fromCoreId, `unsafeFromCoreId` creates an identifier that will be spliced at verbatim in the HDL. As opposed to `fromCoreId`, the resulting Identifier might be generated at a later point as it is NOT added to an IdentifierSet.

toText :: Identifier -> Text Source #

Convert an identifier to string

toLazyText :: Identifier -> Text Source #

Convert an identifier to string

toList :: IdentifierSet -> [Identifier] Source #

union :: HasCallStack => IdentifierSet -> IdentifierSet -> IdentifierSet Source #

Union of two identifier sets. Errors if given sets have been made with different options enabled.

# Creating and extending identifiers

make :: (HasCallStack, IdentifierSetMonad m) => Text -> m Identifier Source #

Make unique identifier based on given string

makeBasic :: (HasCallStack, IdentifierSetMonad m) => Text -> m Identifier Source #

Make unique basic identifier based on given string

makeBasicOr Source #

Arguments

:: (HasCallStack, IdentifierSetMonad m) |
=> Text | Name hint
-> Text | If name hint can't be converted to a sensible basic id, use this instead
-> m Identifier |

Make unique basic identifier based on given string. If given string can't be converted to a basic identifier (i.e., it would yield an empty string) the alternative name is used.

makeAs :: (HasCallStack, IdentifierSetMonad m) => IdentifierType -> Text -> m Identifier Source #

Make unique identifier. Uses `makeBasic` if first argument is `Basic`

add :: HasCallStack => IdentifierSetMonad m => Identifier -> m () Source #

Add an identifier to an IdentifierSet

addMultiple :: (HasCallStack, IdentifierSetMonad m, Foldable t) => t Identifier -> m () Source #

Add identifiers to an IdentifierSet

addRaw :: (HasCallStack, IdentifierSetMonad m) => Text -> m Identifier Source #

Add a string as is to an IdentifierSet. Should only be used for identifiers that should be spliced at verbatim in HDL, such as port names. It's sanitized version will still be added to the identifier set, to prevent freshly generated variables clashing with the raw one.

deepen :: (HasCallStack, IdentifierSetMonad m) => Identifier -> m Identifier Source #

Given identifier "foo_1_2" return "foo_1_2_0". If "foo_1_2_0" is already a member of the given set, return "foo_1_2_1" instead, etc. Identifier returned is guaranteed to be unique.

deepenN :: (HasCallStack, IdentifierSetMonad m) => Int -> Identifier -> m [Identifier] Source #

Same as `deepenM`, but returns N fresh identifiers. For example, given "foo_23" is would return "foo_23_0", "foo_23_1", ...

next :: (HasCallStack, IdentifierSetMonad m) => Identifier -> m Identifier Source #

Given identifier "foo_1_2" return "foo_1_3". If "foo_1_3" is already a member of the given set, return "foo_1_4" instead, etc. Identifier returned is guaranteed to be unique.

nextN :: (HasCallStack, IdentifierSetMonad m) => Int -> Identifier -> m [Identifier] Source #

Same as `nextM`, but returns N fresh identifiers

prefix :: (HasCallStack, IdentifierSetMonad m) => Identifier -> Text -> m Identifier Source #

Given identifier "foo_1_2" and a prefix "bar", return an identifier called "bar_foo". Identifier returned is guaranteed to be unique according to the rules of `nextIdentifier`.

suffix :: (HasCallStack, IdentifierSetMonad m) => Identifier -> Text -> m Identifier Source #

Given identifier "foo_1_2" and a suffix "bar", return an identifier called "foo_bar". Identifier returned is guaranteed to be unique according to the rules of `nextIdentifier`.

fromCoreId :: (HasCallStack, IdentifierSetMonad m) => Id -> m Identifier Source #

Convert a Clash Core Id to an identifier. Makes sure returned identifier is unique.

# Misc. and internals

stripDollarPrefixes :: Text -> Text Source #

toBasicId# :: HDL -> PreserveCase -> Text -> Text Source #

isBasic# :: HDL -> Text -> Bool Source #

Is given string a valid basic identifier in given HDL?

isExtended# :: HDL -> Text -> Bool Source #

Is given string a valid extended identifier in given HDL?