Clash.Netlist.Id

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

Utilities to use IdentifierSet

data IdentifierSet

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

Show IdentifierSet

Defined in Clash.Netlist.Types

Methods

showsPrec :: Int -> IdentifierSet -> ShowS

show :: IdentifierSet -> String

showList :: [IdentifierSet] -> ShowS

Generic IdentifierSet

Defined in Clash.Netlist.Types

Associated Types

type Rep IdentifierSet :: Type -> Type

Methods

from :: IdentifierSet -> Rep IdentifierSet x

to :: Rep IdentifierSet x -> IdentifierSet

NFData IdentifierSet

Defined in Clash.Netlist.Types

Methods

rnf :: IdentifierSet -> ()

HasIdentifierSet IdentifierSet

Defined in Clash.Netlist.Types

Methods

identifierSet :: Lens' IdentifierSet IdentifierSet

type Rep IdentifierSet

Defined in Clash.Netlist.Types

type Rep IdentifierSet = D1 ('MetaData "IdentifierSet" "Clash.Netlist.Types" "clash-lib-1.6.4-inplace" '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

An IdentifierSetMonad supports unique name generation for Clash Netlist

Methods

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

Instances

IdentifierSetMonad NetlistMonad

Defined in Clash.Netlist.Types

Methods

identifierSetM :: (IdentifierSet -> IdentifierSet) -> NetlistMonad IdentifierSet

HasIdentifierSet s => IdentifierSetMonad (State s)

Defined in Clash.Netlist.Types

Methods

identifierSetM :: (IdentifierSet -> IdentifierSet) -> State s IdentifierSet

HasIdentifierSet s => IdentifierSetMonad (State s)

Defined in Clash.Netlist.Types

Methods

identifierSetM :: (IdentifierSet -> IdentifierSet) -> State s IdentifierSet

IdentifierSetMonad m => IdentifierSetMonad (Ap m)

Defined in Clash.Netlist.Types

Methods

identifierSetM :: (IdentifierSet -> IdentifierSet) -> Ap m IdentifierSet

class HasIdentifierSet s where

Structures that hold an IdentifierSet

Methods

identifierSet :: Lens' s IdentifierSet

Instances

HasIdentifierSet IdentifierSet

Defined in Clash.Netlist.Types

Methods

identifierSet :: Lens' IdentifierSet IdentifierSet

HasIdentifierSet VerilogState

Defined in Clash.Backend.Verilog

Methods

identifierSet :: Lens' VerilogState IdentifierSet

HasIdentifierSet VHDLState

Defined in Clash.Backend.VHDL

Methods

identifierSet :: Lens' VHDLState IdentifierSet

HasIdentifierSet SystemVerilogState

Defined in Clash.Backend.SystemVerilog

Methods

identifierSet :: Lens' SystemVerilogState IdentifierSet

Backend backend => HasIdentifierSet (BlockState backend)

Defined in Clash.Primitives.DSL

Methods

identifierSet :: Lens' (BlockState backend) IdentifierSet

emptyIdentifierSet

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

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

Remove all identifiers from a set

Unsafe creation and extracting identifiers

data Identifier

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

Eq Identifier

Defined in Clash.Netlist.Types

Methods

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

(/=) :: Identifier -> Identifier -> Bool

Ord Identifier

Defined in Clash.Netlist.Types

Methods

compare :: Identifier -> Identifier -> Ordering

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

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

(>) :: Identifier -> Identifier -> Bool

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

max :: Identifier -> Identifier -> Identifier

min :: Identifier -> Identifier -> Identifier

Show Identifier

Defined in Clash.Netlist.Types

Methods

showsPrec :: Int -> Identifier -> ShowS

show :: Identifier -> String

showList :: [Identifier] -> ShowS

Generic Identifier

Defined in Clash.Netlist.Types

Associated Types

type Rep Identifier :: Type -> Type

Methods

from :: Identifier -> Rep Identifier x

to :: Rep Identifier x -> Identifier

Hashable Identifier

Defined in Clash.Netlist.Types

Methods

hashWithSalt :: Int -> Identifier -> Int

hash :: Identifier -> Int

NFData Identifier

Defined in Clash.Netlist.Types

Methods

rnf :: Identifier -> ()

Pretty Identifier

Defined in Clash.Netlist.Id.Internal

Methods

pretty :: Identifier -> Doc ann

prettyList :: [Identifier] -> Doc ann

type Rep Identifier

Defined in Clash.Netlist.Types

type Rep Identifier = D1 ('MetaData "Identifier" "Clash.Netlist.Types" "clash-lib-1.6.4-inplace" '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

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

Eq IdentifierType

Defined in Clash.Netlist.Types

Methods

(==) :: IdentifierType -> IdentifierType -> Bool

(/=) :: IdentifierType -> IdentifierType -> Bool

Show IdentifierType

Defined in Clash.Netlist.Types

Methods

showsPrec :: Int -> IdentifierType -> ShowS

show :: IdentifierType -> String

showList :: [IdentifierType] -> ShowS

Generic IdentifierType

Defined in Clash.Netlist.Types

Associated Types

type Rep IdentifierType :: Type -> Type

Methods

from :: IdentifierType -> Rep IdentifierType x

to :: Rep IdentifierType x -> IdentifierType

NFData IdentifierType

Defined in Clash.Netlist.Types

Methods

rnf :: IdentifierType -> ()

type Rep IdentifierType

Defined in Clash.Netlist.Types

type Rep IdentifierType = D1 ('MetaData "IdentifierType" "Clash.Netlist.Types" "clash-lib-1.6.4-inplace" 'False) (C1 ('MetaCons "Basic" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Extended" 'PrefixI 'False) (U1 :: Type -> Type))

unsafeMake :: HasCallStack => Text -> Identifier

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.

toText :: Identifier -> Text

Convert an identifier to string. Use unmake if you need the IdentifierType too.

toLazyText :: Identifier -> Text

Convert an identifier to string. Use unmake if you need the IdentifierType too.

toList :: IdentifierSet -> [Identifier]

union :: HasCallStack => IdentifierSet -> IdentifierSet -> IdentifierSet

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

Make unique identifier based on given string

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

Make unique basic identifier based on given string

makeBasicOr

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

Make unique identifier. Uses makeBasic if first argument is Basic

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

Add an identifier to an IdentifierSet

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

Add identifiers to an IdentifierSet

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

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

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]

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

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]

Same as nextM, but returns N fresh identifiers

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

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

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

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

Misc. and internals

stripDollarPrefixes :: Text -> Text

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

isBasic# :: HDL -> Text -> Bool

Is given string a valid basic identifier in given HDL?

isExtended# :: HDL -> Text -> Bool

Is given string a valid extended identifier in given HDL?