verilog_parser.cpp

Go to the documentation of this file.

#include "verilog_parser/verilog_parser.h"
 
#include "hal_core/netlist/endpoint.h"
#include "hal_core/netlist/gate.h"
#include "hal_core/netlist/netlist.h"
#include "hal_core/netlist/netlist_factory.h"
#include "hal_core/utilities/enums.h"
#include "hal_core/utilities/log.h"
#include "hal_core/utilities/utils.h"
 
#include <fstream>
#include <iomanip>
#include <numeric>
#include <queue>
 
namespace hal
{
    namespace
    {
        // Strict double parse: must consume the full string (no trailing junk).
        bool is_double_strict(const std::string& s)
        {
            if (s.empty())
            {
                return false;
            }
            try
            {
                size_t idx;
                std::stod(s, &idx);
                return idx == s.size();
            }
            catch (...)
            {
                return false;
            }
        }
    }    // namespace
 
    Result<std::monostate> VerilogParser::parse(const std::filesystem::path& file_path)
    {
        m_path = file_path;
        m_modules.clear();
        m_modules_by_name.clear();
 
        {
            std::ifstream ifs;
            ifs.open(file_path.string(), std::ifstream::in);
            if (!ifs.is_open())
            {
                return ERR("could not parse Verilog file '" + m_path.string() + "' : unable to open file");
            }
            m_fs << ifs.rdbuf();
            ifs.close();
        }
 
        // tokenize file
        tokenize();
 
        // parse tokens into intermediate format
        try
        {
            if (auto res = parse_tokens(); res.is_error())
            {
                return ERR_APPEND(res.get_error(), "could not parse Verilog file '" + file_path.string() + "': unable to parse tokens");
            }
        }
        catch (TokenStream<std::string>::TokenStreamException& e)
        {
            if (e.line_number != (u32)-1)
            {
                return ERR("could not parse Verilog file '" + m_path.string() + "': " + e.message + " (line " + std::to_string(e.line_number) + ")");
            }
            else
            {
                return ERR("could not parse Verilog file '" + m_path.string() + "': " + e.message);
            }
        }
 
        if (m_modules.empty())
        {
            return ERR("could not parse Verilog file '" + m_path.string() + "': does not contain any modules");
        }
 
        // expand module port identifiers, signals, and assignments
        for (auto& [module_name, verilog_module] : m_modules_by_name)
        {
            // expand port identifiers
            for (const auto& port : verilog_module->m_ports)
            {
                const bool stands_for_one_signal = port->m_expression_parts.size() == 1 && std::holds_alternative<identifier_t>(port->m_expression_parts.front());
                if (!stands_for_one_signal)
                {
                    // the width of the port is the width of its expression, whose signals are declared by now
                    const std::vector<std::string> expanded_expression = expand_assignment_expression(verilog_module, port->m_expression_parts);
                    if (expanded_expression.empty())
                    {
                        return ERR("could not parse Verilog file '" + m_path.string() + "': unable to expand the expression of port '" + port->m_identifier + "' of module '" + verilog_module->m_name + "'");
                    }
                    if (expanded_expression.size() == 1)
                    {
                        port->m_expanded_identifiers = {port->m_identifier};
                    }
                    else
                    {
                        std::vector<u32> range(expanded_expression.size());
                        std::iota(range.begin(), range.end(), 0);
                        port->m_ranges               = {range};
                        port->m_expanded_identifiers = expand_ranges(port->m_identifier, port->m_ranges);
                    }
                    for (u32 i = 0; i < expanded_expression.size(); i++)
                    {
                        verilog_module->m_expanded_port_identifiers_to_expressions[port->m_expanded_identifiers.at(i)] = expanded_expression.at(i);
                    }
                }
                else if (const identifier_t& signal = std::get<identifier_t>(port->m_expression_parts.front()); signal != port->m_identifier)
                {
                    // the port stands for one whole signal of another name, bit for bit
                    port->m_expanded_identifiers = port->m_ranges.empty() ? std::vector<std::string>{port->m_identifier} : expand_ranges(port->m_identifier, port->m_ranges);
                    const std::vector<std::string> expanded_expression = port->m_ranges.empty() ? std::vector<std::string>{signal} : expand_ranges(signal, port->m_ranges);
                    for (u32 i = 0; i < expanded_expression.size(); i++)
                    {
                        verilog_module->m_expanded_port_identifiers_to_expressions[port->m_expanded_identifiers.at(i)] = expanded_expression.at(i);
                    }
                }
                else
                {
                    port->m_expanded_identifiers = port->m_ranges.empty() ? std::vector<std::string>{port->m_identifier} : expand_ranges(port->m_identifier, port->m_ranges);
                }
            }
 
            // expand signals
            for (auto& signal : verilog_module->m_signals)
            {
                if (!signal->m_ranges.empty())
                {
                    signal->m_expanded_names = expand_ranges(signal->m_name, signal->m_ranges);
                }
                else
                {
                    signal->m_expanded_names = std::vector<std::string>({signal->m_name});
                }
            }
 
            // expand assignments
            for (auto& assignment : verilog_module->m_assignments)
            {
                const std::vector<std::string> left_signals  = expand_assignment_expression(verilog_module, assignment.m_variable);
                const std::vector<std::string> right_signals = expand_assignment_expression(verilog_module, assignment.m_assignment);
                if (left_signals.empty() || right_signals.empty())
                {
                    return ERR("could not parse Verilog file '" + m_path.string() + "': unable to expand assignments within module '" + verilog_module->m_name + "'");
                }
 
                u32 left_size  = left_signals.size();
                u32 right_size = right_signals.size();
                if (left_size <= right_size)
                {
                    // cut off redundant bits
                    for (u32 i = 0; i < left_size; i++)
                    {
                        verilog_module->m_expanded_assignments.push_back(std::make_pair(left_signals.at(i), right_signals.at(i)));
                    }
                }
                else
                {
                    for (u32 i = 0; i < right_size; i++)
                    {
                        verilog_module->m_expanded_assignments.push_back(std::make_pair(left_signals.at(i), right_signals.at(i)));
                    }
 
                    // implicit "0"
                    for (u32 i = 0; i < left_size - right_size; i++)
                    {
                        verilog_module->m_expanded_assignments.push_back(std::make_pair(left_signals.at(i + right_size), "'0'"));
                    }
                }
            }
        }
 
        // expand module port assignments
        for (auto& [module_name, verilog_module] : m_modules_by_name)
        {
            for (auto& instance : verilog_module->m_instances)
            {
                if (auto module_it = m_modules_by_name.find(instance->m_type); module_it != m_modules_by_name.end())
                {
                    instance->m_is_module = true;
                    if (!instance->m_port_assignments.empty())
                    {
                        // all port assignments by name
                        if (instance->m_port_assignments.front().m_port_name.has_value())
                        {
                            for (const auto& port_assignment : instance->m_port_assignments)
                            {
                                const std::vector<std::string> right_port = expand_assignment_expression(verilog_module, port_assignment.m_assignment);
                                if (!right_port.empty())
                                {
                                    VerilogPort* port;
                                    if (const auto port_it = module_it->second->m_ports_by_identifier.find(port_assignment.m_port_name.value());
                                        port_it == module_it->second->m_ports_by_identifier.end())
                                    {
                                        return ERR("could not parse Verilog file '" + m_path.string() + "': unable to assign signal to port '" + port_assignment.m_port_name.value()
                                                   + "' as it is not a port of module '" + module_it->first + "'");
                                    }
                                    else
                                    {
                                        port = port_it->second;
                                    }
                                    const std::vector<std::string>& left_port = port->m_expanded_identifiers;
                                    if (left_port.empty())
                                    {
                                        return ERR("could not parse Verilog file '" + m_path.string() + "': unable to expand port assignment");
                                    }
 
                                    u32 max_size = right_port.size() <= left_port.size() ? right_port.size() : left_port.size();
 
                                    for (u32 i = 0; i < max_size; i++)
                                    {
                                        instance->m_expanded_port_assignments.push_back(std::make_pair(left_port.at(i), right_port.at(i)));
                                    }
                                }
                            }
                        }
                        // all port assignments by order
                        else
                        {
                            std::vector<std::string> ports;
                            for (const auto& port : m_modules_by_name.at(instance->m_type)->m_ports)
                            {
                                ports.insert(ports.end(), port->m_expanded_identifiers.begin(), port->m_expanded_identifiers.end());
                            }
 
                            auto port_it = ports.begin();
 
                            for (const auto& port_assignment : instance->m_port_assignments)
                            {
                                std::vector<std::string> right_port = expand_assignment_expression(verilog_module, port_assignment.m_assignment);
                                if (!right_port.empty())
                                {
                                    std::vector<std::string> left_port;
 
                                    for (u32 i = 0; i < right_port.size() && port_it != ports.end(); i++)
                                    {
                                        left_port.push_back(*port_it++);
                                    }
 
                                    u32 max_size = right_port.size() <= left_port.size() ? right_port.size() : left_port.size();
 
                                    for (u32 i = 0; i < max_size; i++)
                                    {
                                        instance->m_expanded_port_assignments.push_back(std::make_pair(left_port.at(i), right_port.at(i)));
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
 
        return OK({});
    }
 
    Result<std::unique_ptr<Netlist>> VerilogParser::instantiate(const GateLibrary* gate_library)
    {
        // create empty netlist
        std::unique_ptr<Netlist> result = netlist_factory::create_netlist(gate_library);
        m_netlist                       = result.get();
        if (m_netlist == nullptr)
        {
            return ERR("could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name() + "': failed to create empty netlist");
        }
 
        m_gate_types.clear();
        m_gnd_gate_types.clear();
        m_vcc_gate_types.clear();
        m_module_instantiation_count.clear();
        m_instance_name_occurences.clear();
        m_net_name_occurences.clear();
        m_net_by_name.clear();
        m_nets_to_merge.clear();
        m_module_ports.clear();
        m_module_port_by_net.clear();
        for (const auto& verilog_module : m_modules)
        {
            for (const auto& instance : verilog_module->m_instances)
            {
                if (!instance->m_is_module)
                {
                    instance->m_expanded_port_assignments.clear();
                }
            }
        }
 
        // buffer gate types
        m_gate_types     = gate_library->get_gate_types();
        m_gnd_gate_types = gate_library->get_gnd_gate_types();
        m_vcc_gate_types = gate_library->get_vcc_gate_types();
 
        // create const 0 and const 1 net, will be removed if unused
        m_zero_net = m_netlist->create_net("'0'");
        if (m_zero_net == nullptr)
        {
            return ERR("could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name() + "': failed to create zero net");
        }
        m_net_by_name[m_zero_net->get_name()] = m_zero_net;
 
        m_one_net = m_netlist->create_net("'1'");
        if (m_one_net == nullptr)
        {
            return ERR("could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name() + "': failed to create one net");
        }
        m_net_by_name[m_one_net->get_name()] = m_one_net;
 
        // a module marked (* top = 1 *), as Yosys does, is the top module; otherwise it is the one module nobody instantiates
        std::vector<std::string> marked_top_modules;
        for (const auto& [name, module] : m_modules_by_name)
        {
            for (const VerilogDataEntry& attribute : module->m_attributes)
            {
                if (attribute.m_name == "top" && utils::trim(attribute.m_value) == "1")
                {
                    marked_top_modules.push_back(name);
                    break;
                }
            }
        }
        if (marked_top_modules.size() > 1)
        {
            return ERR("could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name() + "': several modules carry the top attribute: "
                       + utils::join(", ", marked_top_modules));
        }
 
        std::map<std::string, u32> module_name_to_refereneces;
        for (const auto& [_name, module] : m_modules_by_name)
        {
            for (const auto& instance : module->m_instances)
            {
                if (const auto it = m_modules_by_name.find(instance->m_type); it != m_modules_by_name.end())
                {
                    module_name_to_refereneces[it->first]++;
                }
            }
        }
 
        std::vector<std::string> top_module_candidates = marked_top_modules;
        if (top_module_candidates.empty())
        {
            for (const auto& [name, module] : m_modules_by_name)
            {
                if (module_name_to_refereneces.find(name) == module_name_to_refereneces.end())
                {
                    top_module_candidates.push_back(name);
                }
            }
        }
 
        if (top_module_candidates.empty())
        {
            return ERR("could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name() + "': unable to find any top module candidates");
        }
 
        if (top_module_candidates.size() > 1)
        {
            return ERR("could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name()
                       + "': found multiple modules as candidates for the top module, none of them marked (* top = 1 *): " + utils::join(", ", top_module_candidates));
        }
 
        // construct the netlist with the the top module
        VerilogModule* top_module = m_modules_by_name.at(top_module_candidates.front());
 
        if (const auto res = construct_netlist(top_module); res.is_error())
        {
            return ERR_APPEND(res.get_error(), "could not instantiate Verilog netlist '" + m_path.string() + "' with gate library '" + gate_library->get_name() + "': unable to construct netlist");
        }
 
        // delete unused nets
        std::queue<Net*> nets_to_be_deleted;
 
        for (auto net : m_netlist->get_nets())
        {
            const u32 num_of_sources      = net->get_num_of_sources();
            const u32 num_of_destinations = net->get_num_of_destinations();
            const bool no_source          = num_of_sources == 0 && !(net->is_global_input_net() && num_of_destinations != 0);
            const bool no_destination     = num_of_destinations == 0 && !(net->is_global_output_net() && num_of_sources != 0);
            if (no_source && no_destination)
            {
                nets_to_be_deleted.push(net);
            }
        }
 
        while (!nets_to_be_deleted.empty())
        {
            Net* net = nets_to_be_deleted.front();
            nets_to_be_deleted.pop();
            m_netlist->delete_net(net);
        }
 
        m_netlist->load_gate_locations_from_data();
 
        return OK(std::move(result));
    }
 
    // ###########################################################################
    // ###########          Parse HDL into Intermediate Format          ##########
    // ###########################################################################
 
    void VerilogParser::tokenize()
    {
        const std::string delimiters = "`,()[]{}\\#*: ;=./";
        std::string current_token;
        u32 line_number = 0;
 
        std::string line;
        char prev_char  = 0;
        bool in_string  = false;
        bool escaped    = false;
        bool in_comment = false;
 
        std::vector<Token<std::string>> parsed_tokens;
        while (std::getline(m_fs, line))
        {
            line_number++;
            // this->remove_comments(line, multi_line_comment);
 
            for (char c : line)
            {
                // deal with comments
                if (in_comment)
                {
                    if (c == '/' && prev_char == '*')
                    {
                        in_comment = false;
                    }
 
                    prev_char = c;
                    continue;
                }
 
                // deal with escaping and strings
                if (!in_string && c == '\\')
                {
                    escaped = true;
                    continue;
                }
                else if (escaped && std::isspace(c))
                {
                    escaped = false;
                    continue;
                }
                else if (!escaped && c == '"')
                {
                    in_string = !in_string;
                }
 
                if (!in_comment && ((!std::isspace(c) && delimiters.find(c) == std::string::npos) || escaped || in_string))
                {
                    current_token += c;
                }
                else
                {
                    // deal with floats
                    if (!current_token.empty())
                    {
                        if (parsed_tokens.size() > 1 && utils::is_digits(parsed_tokens.at(parsed_tokens.size() - 2).string) && parsed_tokens.at(parsed_tokens.size() - 1) == "."
                            && utils::is_digits(current_token))
                        {
                            parsed_tokens.pop_back();
                            parsed_tokens.back() += "." + current_token;
                        }
                        else
                        {
                            parsed_tokens.emplace_back(line_number, current_token);
                        }
                        current_token.clear();
                    }
 
                    if (!parsed_tokens.empty())
                    {
                        // deal with multi-character tokens
                        if (c == '(' && parsed_tokens.back() == "#")
                        {
                            parsed_tokens.back() = "#(";
                            continue;
                        }
                        else if (c == '*' && parsed_tokens.back() == "(")
                        {
                            parsed_tokens.back() = "(*";
                            continue;
                        }
                        else if (c == ')' && parsed_tokens.back() == "*")
                        {
                            parsed_tokens.back() = "*)";
                            continue;
                        }
                        // start a comment
                        else if (c == '/' && parsed_tokens.back() == "/")
                        {
                            parsed_tokens.pop_back();
                            break;
                        }
                        else if (c == '*' && parsed_tokens.back() == "/")
                        {
                            in_comment = true;
                            parsed_tokens.pop_back();
                            continue;
                        }
                    }
 
                    if (!std::isspace(c))
                    {
                        parsed_tokens.emplace_back(line_number, std::string(1, c));
                    }
                }
            }
            if (!current_token.empty())
            {
                parsed_tokens.emplace_back(line_number, current_token);
                current_token.clear();
            }
        }
 
        m_token_stream = TokenStream(parsed_tokens, {"(", "["}, {")", "]"});
    }
 
    Result<std::monostate> VerilogParser::parse_tokens()
    {
        std::vector<VerilogDataEntry> attributes;
        u32 line_number;
 
        while (m_token_stream.remaining() > 0)
        {
            if (m_token_stream.peek() == "(*")
            {
                parse_attribute(attributes);
            }
            else if (m_token_stream.peek() == "`")
            {
                m_token_stream.consume_current_line();
                log_warning("verilog_parser", "could not parse compiler directives.");
            }
            else
            {
                line_number = m_token_stream.peek().number;
                if (auto res = parse_module(attributes); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse tokens: unable to parse module (line " + std::to_string(line_number) + ")");
                }
            }
        }
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_module(std::vector<VerilogDataEntry>& attributes)
    {
        std::set<std::string> port_names;
        std::vector<VerilogDataEntry> internal_attributes;
 
        m_token_stream.consume("module", true);
        const u32 line_number         = m_token_stream.peek().number;
        const std::string module_name = m_token_stream.consume();
 
        // verify entity name
        if (const auto it = m_modules_by_name.find(module_name); it != m_modules_by_name.end())
        {
            return ERR("could not parse module '" + module_name + "' (line " + std::to_string(line_number) + "): a module with the same name already exists (line "
                       + std::to_string(it->second->m_line_number) + ")");
        }
 
        auto verilog_module               = std::make_unique<VerilogModule>();
        VerilogModule* verilog_module_raw = verilog_module.get();
        verilog_module_raw->m_line_number = line_number;
        verilog_module_raw->m_name        = module_name;
 
        // parse parameter list
        if (m_token_stream.consume("#("))
        {
            // TODO add support for parameter parsing
            m_token_stream.consume_until(")");
            m_token_stream.consume(")", true);
            log_warning("verilog_parser", "could not parse parameter list provided for module '{}'.", module_name);
        }
 
        // parse port (declaration) list
        m_token_stream.consume("(", true);
        Token<std::string> next_token = m_token_stream.peek();
        if (next_token == "input" || next_token == "output" || next_token == "inout")
        {
            if (auto res = parse_port_declaration_list(verilog_module_raw); res.is_error())
            {
                return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "': unable to parse port declaration list (line " + std::to_string(line_number) + ")");
            }
        }
        else
        {
            if (auto res = parse_port_list(verilog_module_raw); res.is_error())
            {
                return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "' (line " + std::to_string(line_number) + "): unable to parse port list");
            }
        }
 
        m_token_stream.consume(";", true);
 
        next_token = m_token_stream.peek();
        while (next_token != "endmodule")
        {
            if (next_token == "input" || next_token == "output" || next_token == "inout")
            {
                if (auto res = parse_port_definition(verilog_module_raw, internal_attributes); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "': unable to parse port definition (line " + std::to_string(line_number) + ")");
                }
            }
            else if (next_token == "wire" || next_token == "tri")
            {
                if (auto res = parse_signal_definition(verilog_module_raw, internal_attributes); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "': unable to parse signal definition (line " + std::to_string(line_number) + ")");
                }
            }
            else if (next_token == "parameter")
            {
                // TODO add support for parameter parsing
                m_token_stream.consume_until(";");
                m_token_stream.consume(";", true);
                log_warning("verilog_parser", "could not parse parameter provided for module '{}'.", module_name);
            }
            else if (next_token == "assign")
            {
                if (auto res = parse_assignment(verilog_module_raw); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "': unable to parse assignment (line " + std::to_string(line_number) + ")");
                }
            }
            else if (next_token == "defparam")
            {
                if (auto res = parse_defparam(verilog_module_raw); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "': unable to parse defparam (line " + std::to_string(line_number) + ")");
                }
            }
            else if (next_token == "(*")
            {
                parse_attribute(internal_attributes);
            }
            else
            {
                if (auto res = parse_instance(verilog_module_raw, internal_attributes); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse module '" + module_name + "': unable to parse instance (line " + std::to_string(line_number) + ")");
                }
            }
 
            next_token = m_token_stream.peek();
        }
 
        m_token_stream.consume("endmodule", true);
 
        // assign attributes to entity
        if (!attributes.empty())
        {
            verilog_module->m_attributes.insert(verilog_module->m_attributes.end(), attributes.begin(), attributes.end());
            attributes.clear();
        }
 
        // add to collection of entities
        m_modules.push_back(std::move(verilog_module));
        m_modules_by_name[module_name] = verilog_module_raw;
        m_last_module                  = module_name;
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_port_list(VerilogModule* verilog_module)
    {
        TokenStream<std::string> ports_stream = m_token_stream.extract_until(")");
        m_token_stream.consume(")", true);
 
        while (ports_stream.remaining() > 0)
        {
            Token<std::string> next_token = ports_stream.consume();
            auto port                     = std::make_unique<VerilogPort>();
 
            if (next_token == ".")
            {
                port->m_identifier = ports_stream.consume().string;
                ports_stream.consume("(", true);
                TokenStream<std::string> expression_stream = ports_stream.extract_until(")");
                ports_stream.consume(")", true);
 
                // a port expression is anything a right-hand side may be: a signal, a slice of one, or a concatenation
                // of those, which Vivado writes for a port that is partly constant, e.g. .sum({<const0> ,\^sum [1:0]})
                auto parts_res = parse_assignment_expression(std::move(expression_stream));
                if (parts_res.is_error())
                {
                    return ERR_APPEND(parts_res.get_error(), "could not parse port list: invalid expression of port '" + port->m_identifier + "' (line " + std::to_string(next_token.number) + ")");
                }
                port->m_expression_parts = parts_res.get();
            }
            else
            {
                port->m_identifier       = next_token.string;
                port->m_expression_parts = {identifier_t(next_token.string)};
            }
 
            // the body declares direction and width on the signals the port stands for, so each of them has to find the port
            for (const auto& part : port->m_expression_parts)
            {
                if (const identifier_t* identifier = std::get_if<identifier_t>(&part); identifier != nullptr)
                {
                    verilog_module->m_ports_by_expression[*identifier] = port.get();
                }
                else if (const ranged_identifier_t* ranged = std::get_if<ranged_identifier_t>(&part); ranged != nullptr)
                {
                    verilog_module->m_ports_by_expression[ranged->first] = port.get();
                }
            }
 
            verilog_module->m_ports_by_identifier[port->m_identifier] = port.get();
            verilog_module->m_ports.push_back(std::move(port));
 
            ports_stream.consume(",", ports_stream.remaining() > 0);
        }
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_port_declaration_list(VerilogModule* verilog_module)
    {
        TokenStream<std::string> ports_stream = m_token_stream.extract_until(")");
        m_token_stream.consume(")", true);
 
        while (ports_stream.remaining() > 0)
        {
            // direction
            const Token<std::string> direction_token = ports_stream.consume();
            PinDirection direction                   = enum_from_string<PinDirection>(direction_token.string, PinDirection::none);
            if (direction == PinDirection::none || direction == PinDirection::internal)
            {
                return ERR("could not parse port declaration list: invalid direction '" + direction_token.string + "' (line " + std::to_string(direction_token.number) + ")");
            }
 
            // ranges
            std::vector<std::vector<u32>> ranges;
            while (ports_stream.consume("["))
            {
                const std::vector<u32> range = parse_range(ports_stream);
                ports_stream.consume("]", true);
 
                ranges.emplace_back(range);
            }
 
            // port expressions
            do
            {
                const Token<std::string> next_token = ports_stream.peek();
                if (next_token == "input" || next_token == "output" || next_token == "inout")
                {
                    break;
                }
                ports_stream.consume();
 
                auto port                          = std::make_unique<VerilogPort>();
                const std::string& port_expression = next_token.string;
                port->m_identifier                 = port_expression;
                port->m_expression_parts           = {identifier_t(port_expression)};
                port->m_direction                  = direction;
                if (!ranges.empty())
                {
                    port->m_ranges = ranges;
                }
                verilog_module->m_ports_by_identifier[port_expression] = port.get();
                verilog_module->m_ports_by_expression[port_expression] = port.get();
                verilog_module->m_ports.push_back(std::move(port));
 
                // every port implicitly creates a wire, so create signal if not already declared explicitly
                if (verilog_module->m_signals_by_name.find(port_expression) == verilog_module->m_signals_by_name.end())
                {
                    auto signal    = std::make_unique<VerilogSignal>();
                    signal->m_name = port_expression;
                    if (!ranges.empty())
                    {
                        signal->m_ranges = ranges;
                    }
                    verilog_module->m_signals_by_name[port_expression] = signal.get();
                    verilog_module->m_signals.push_back(std::move(signal));
                }
            } while (ports_stream.consume(",", ports_stream.remaining() > 0));
        }
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_port_definition(VerilogModule* verilog_module, std::vector<VerilogDataEntry>& attributes)
    {
        // port direction
        const Token<std::string> direction_token = m_token_stream.consume();
        PinDirection direction                   = enum_from_string<PinDirection>(direction_token.string, PinDirection::none);
        if (direction == PinDirection::none || direction == PinDirection::internal)
        {
            return ERR("could not parse port definition: invalid direction '" + direction_token.string + "' (line " + std::to_string(direction_token.number) + ")");
        }
 
        // ranges
        std::vector<std::vector<u32>> ranges;
        while (m_token_stream.consume("["))
        {
            const std::vector<u32> range = parse_range(m_token_stream);
            m_token_stream.consume("]", true);
 
            ranges.emplace_back(range);
        }
 
        // port expressions
        do
        {
            Token<std::string> port_expression_token = m_token_stream.consume();
            std::string port_expression              = port_expression_token.string;
 
            VerilogPort* port;
            if (const auto it = verilog_module->m_ports_by_expression.find(port_expression); it == verilog_module->m_ports_by_expression.end())
            {
                return ERR("could not parse port definition: a port with name '" + port_expression + "' does not exist for module '" + verilog_module->m_name + "' (line "
                           + std::to_string(direction_token.number) + ")");
            }
            else
            {
                port = it->second;
            }
 
            port->m_direction = direction;
            // the ranges of a concatenation's signals belong to those signals, the port's width follows from the expression
            const bool stands_for_one_signal = port->m_expression_parts.size() == 1 && std::holds_alternative<identifier_t>(port->m_expression_parts.front());
            if (!ranges.empty() && stands_for_one_signal)
            {
                port->m_ranges = ranges;
            }
 
            // every port implicitly creates a wire, so create signal if not already declared explicitly
            if (const auto signal_it = verilog_module->m_signals_by_name.find(port_expression); signal_it == verilog_module->m_signals_by_name.end())
            {
                auto signal    = std::make_unique<VerilogSignal>();
                signal->m_name = port_expression;
                if (!ranges.empty())
                {
                    signal->m_ranges = ranges;
                }
                signal->m_attributes.insert(signal->m_attributes.end(), attributes.begin(), attributes.end());
                verilog_module->m_signals_by_name[port_expression] = signal.get();
                verilog_module->m_signals.push_back(std::move(signal));
            }
            else
            {
                auto* signal = signal_it->second;
                signal->m_attributes.insert(signal->m_attributes.end(), attributes.begin(), attributes.end());
            }
        } while (m_token_stream.consume(",", false));
 
        m_token_stream.consume(";", true);
        attributes.clear();
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_signal_definition(VerilogModule* verilog_module, std::vector<VerilogDataEntry>& attributes)
    {
        // consume "wire" or "tri"
        u32 line_number = m_token_stream.consume().number;
 
        TokenStream<std::string> signal_stream = m_token_stream.extract_until(";");
        m_token_stream.consume(";", true);
 
        // extract bounds
        std::vector<std::vector<u32>> ranges;
        while (signal_stream.consume("["))
        {
            const std::vector<u32> range = parse_range(signal_stream);
            signal_stream.consume("]", true);
 
            ranges.emplace_back(range);
        }
 
        // extract names
        do
        {
            Token<std::string> signal_name = signal_stream.consume();
            if (signal_stream.remaining() > 0 && signal_stream.peek() == "=")
            {
                VerilogAssignment assignment;
                assignment.m_variable.push_back(signal_name);
                signal_stream.consume("=", true);
                if (auto res = parse_assignment_expression(signal_stream.extract_until(",")); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse signal definition: unable to parse assignment expression (line " + std::to_string(line_number) + ")");
                }
                else
                {
                    assignment.m_assignment = res.get();
                }
                verilog_module->m_assignments.push_back(std::move(assignment));
            }
 
            // create signal if not already implicitly declared otherwise
            if (const auto signal_it = verilog_module->m_signals_by_name.find(signal_name.string); signal_it == verilog_module->m_signals_by_name.end())
            {
                auto signal    = std::make_unique<VerilogSignal>();
                signal->m_name = signal_name.string;
                if (!ranges.empty())
                {
                    signal->m_ranges = ranges;
                }
                signal->m_attributes.insert(signal->m_attributes.end(), attributes.begin(), attributes.end());
                verilog_module->m_signals_by_name[signal_name.string] = signal.get();
                verilog_module->m_signals.push_back(std::move(signal));
            }
            else
            {
                auto* signal = signal_it->second;
                signal->m_attributes.insert(signal->m_attributes.end(), attributes.begin(), attributes.end());
            }
 
        } while (signal_stream.consume(",", false));
 
        attributes.clear();
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_assignment(VerilogModule* verilog_module)
    {
        m_token_stream.consume("assign", true);
        u32 line_number = m_token_stream.peek().number;
        VerilogAssignment assignment;
 
        if (auto res = parse_assignment_expression(m_token_stream.extract_until("=")); res.is_error())
        {
            return ERR_APPEND(res.get_error(), "could not parse assignment: unable to parse assignment expression (line " + std::to_string(line_number) + ")");
        }
        else
        {
            assignment.m_variable = res.get();
        }
        m_token_stream.consume("=", true);
 
        if (auto res = parse_assignment_expression(m_token_stream.extract_until(";")); res.is_error())
        {
            return ERR_APPEND(res.get_error(), "could not parse assignment: unable to parse assignment expression (line " + std::to_string(line_number) + ")");
        }
        else
        {
            assignment.m_assignment = res.get();
        }
 
        // every assignment implicitly creates a wire, so create signal if not already declared explicitly
        for (const auto& var : assignment.m_variable)
        {
            if (const auto* identifier = std::get_if<identifier_t>(&var); identifier != nullptr)
            {
                if (verilog_module->m_signals_by_name.find(*identifier) == verilog_module->m_signals_by_name.end())
                {
                    auto signal                                    = std::make_unique<VerilogSignal>();
                    signal->m_name                                 = *identifier;
                    verilog_module->m_signals_by_name[*identifier] = signal.get();
                    verilog_module->m_signals.push_back(std::move(signal));
                }
            }
            else if (const auto* ranged_identifier = std::get_if<ranged_identifier_t>(&var); ranged_identifier != nullptr)
            {
                const auto& signal_name = std::get<0>(*ranged_identifier);
                if (verilog_module->m_signals_by_name.find(signal_name) == verilog_module->m_signals_by_name.end())
                {
                    auto signal                                    = std::make_unique<VerilogSignal>();
                    signal->m_name                                 = signal_name;
                    signal->m_ranges                               = std::get<1>(*ranged_identifier);
                    verilog_module->m_signals_by_name[signal_name] = signal.get();
                    verilog_module->m_signals.push_back(std::move(signal));
                }
            }
        }
        m_token_stream.consume(";", true);
 
        verilog_module->m_assignments.push_back(std::move(assignment));
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_defparam(VerilogModule* module)
    {
        m_token_stream.consume("defparam", true);
        std::string instance_name = m_token_stream.consume().string;
        m_token_stream.consume(".", true);
 
        if (const auto inst_it = module->m_instances_by_name.find(instance_name); inst_it != module->m_instances_by_name.end())
        {
            VerilogDataEntry param;
            param.m_name = m_token_stream.consume().string;
            m_token_stream.consume("=", true);
 
            if (const auto res = parse_parameter_value(param.m_name, m_token_stream.consume()); res.is_ok())
            {
                const auto& [parsed_param, value_str] = res.get();
                param.m_value                         = value_str;
                param.m_parameter                     = parsed_param;
                inst_it->second->m_parameters.push_back(std::move(param));
            }
            else
            {
                log_warning("verilog_parser", "{}", res.get_error().get());
            }
        }
        else
        {
            m_token_stream.consume(";", true);
            return ERR("could not parse defparam: no instance with name '" + instance_name + "' exists within module '" + module->m_name + "'");
        }
 
        m_token_stream.consume(";", true);
        return OK({});
    }
 
    void VerilogParser::parse_attribute(std::vector<VerilogDataEntry>& attributes)
    {
        m_token_stream.consume("(*", true);
 
        // extract attributes
        do
        {
            VerilogDataEntry attribute;
            attribute.m_name = m_token_stream.consume().string;
 
            // attribute value specified?
            if (m_token_stream.consume("="))
            {
                attribute.m_value = m_token_stream.consume();
 
                // remove "
                if (attribute.m_value[0] == '\"' && attribute.m_value.back() == '\"')
                {
                    attribute.m_value = attribute.m_value.substr(1, attribute.m_value.size() - 2);
                }
            }
 
            attributes.push_back(std::move(attribute));
 
        } while (m_token_stream.consume(",", false));
 
        m_token_stream.consume("*)", true);
    }
 
    Result<std::monostate> VerilogParser::parse_instance(VerilogModule* verilog_module, std::vector<VerilogDataEntry>& attributes)
    {
        auto instance    = std::make_unique<VerilogInstance>();
        u32 line_number  = m_token_stream.peek().number;
        instance->m_type = m_token_stream.consume().string;
 
        // parse generics map
        if (m_token_stream.consume("#("))
        {
            if (auto res = parse_parameter_assign(); res.is_error())
            {
                return ERR_APPEND(res.get_error(), "could not parse instance of type '" + instance->m_type + "': unable to parse parameter assignment (line " + std::to_string(line_number) + ")");
            }
            else
            {
                instance->m_parameters = res.get();
            }
        }
 
        // parse instance name
        instance->m_name = m_token_stream.consume().string;
 
        // parse port map
        if (auto res = parse_port_assign(instance.get()); res.is_error())
        {
            return ERR_APPEND(res.get_error(),
                              "could not parse instance '" + instance->m_name + "' of type '" + instance->m_type + "': unable to parse port assignment (line " + std::to_string(line_number) + ")");
        }
 
        // assign attributes to instance
        instance->m_attributes = attributes;
        attributes.clear();
 
        verilog_module->m_instances_by_name[instance->m_name] = instance.get();
        verilog_module->m_instances.push_back(std::move(instance));
 
        return OK({});
    }
 
    Result<std::monostate> VerilogParser::parse_port_assign(VerilogInstance* instance)
    {
        u32 line_number = m_token_stream.peek().number;
        m_token_stream.consume("(", true);
        u32 line_end = m_token_stream.find_next(";");
        if (m_token_stream.peek() == ".")
        {
            do
            {
                m_token_stream.consume(".");
                VerilogPortAssignment port_assignment;
                port_assignment.m_port_name = m_token_stream.consume().string;
                m_token_stream.consume("(", true);
                if (auto res = parse_assignment_expression(m_token_stream.extract_until(")")); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse port assignment: unable to parse assignment expression (line " + std::to_string(line_number) + ")");
                }
                else
                {
                    port_assignment.m_assignment = res.get();
                }
                m_token_stream.consume(")", true);
                if (port_assignment.m_assignment.empty())
                {
                    continue;
                }
                instance->m_port_assignments.push_back(std::move(port_assignment));
            } while (m_token_stream.consume(",", false));
        }
        else
        {
            do
            {
                VerilogPortAssignment port_assignment;
                if (auto res = parse_assignment_expression(m_token_stream.extract_until(",", line_end - 1)); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse port assignment: unable to parse assignment expression (line " + std::to_string(line_number) + ")");
                }
                else
                {
                    port_assignment.m_assignment = res.get();
                }
                if (port_assignment.m_assignment.empty())
                {
                    continue;
                }
                instance->m_port_assignments.push_back(std::move(port_assignment));
            } while (m_token_stream.consume(",", false));
        }
 
        m_token_stream.consume(")", true);
        m_token_stream.consume(";", true);
 
        return OK({});
    }
 
    Result<std::vector<VerilogParser::VerilogDataEntry>> VerilogParser::parse_parameter_assign()
    {
        std::vector<VerilogDataEntry> generics;
 
        do
        {
            if (m_token_stream.consume(".", false))
            {
                const Token<std::string> lhs = m_token_stream.join_until("(", "");
                m_token_stream.consume("(", true);
                const Token<std::string> rhs = m_token_stream.join_until(")", "");
                m_token_stream.consume(")", true);
 
                if (const auto res = parse_parameter_value(lhs.string, rhs); res.is_ok())
                {
                    const auto& [param, value_str] = res.get();
                    VerilogDataEntry entry;
                    entry.m_name      = lhs.string;
                    entry.m_value     = value_str;
                    entry.m_parameter = param;
                    generics.push_back(std::move(entry));
                }
                else
                {
                    log_warning("verilog_parser", "{}", res.get_error().get());
                }
            }
        } while (m_token_stream.consume(",", false));
 
        m_token_stream.consume(")", true);
 
        return OK(generics);
    }
 
    // ###########################################################################
    // ###########      Assemble Netlist from Intermediate Format       ##########
    // ###########################################################################
 
    Result<std::monostate> VerilogParser::construct_netlist(VerilogModule* top_module)
    {
        m_netlist->set_design_name(top_module->m_name);
        m_netlist->enable_automatic_net_checks(false);
 
        // preparations for alias: count the occurences of all names
        std::queue<VerilogModule*> q;
        q.push(top_module);
 
        while (!q.empty())
        {
            VerilogModule* module = q.front();
            q.pop();
 
            m_module_instantiation_count[module->m_name]++;
 
            // collect and count all net names in the netlist
            for (const auto& s : module->m_signals)
            {
                std::vector<std::string> expanded_names;
                expand_ranges_recursively(expanded_names, s->m_name, s->m_ranges, 0);
                for (const auto& net_name : expanded_names)
                {
                    m_net_name_occurences[net_name]++;
                }
            }
 
            for (const auto& instance : module->m_instances)
            {
                m_instance_name_occurences[instance->m_name]++;
 
                // add type of instance to q if it is a module
                if (const auto it = m_modules_by_name.find(instance->m_type); it != m_modules_by_name.end())
                {
                    q.push(it->second);
                }
            }
        }
 
        for (auto& [module_name, verilog_module] : m_modules_by_name)
        {
            // detect unused modules
            if (m_module_instantiation_count[module_name] == 0)
            {
                log_warning("verilog_parser", "module '{}' has been defined in the netlist but is not instantiated.", module_name);
                continue;
            }
 
            // expand gate pin assignments
            for (const auto& instance : verilog_module->m_instances)
            {
                if (const auto gate_type_it = m_gate_types.find(instance->m_type); gate_type_it != m_gate_types.end())
                {
                    if (!instance->m_port_assignments.empty())
                    {
                        // all port assignments by name
                        if (instance->m_port_assignments.front().m_port_name.has_value())
                        {
                            // cache pin groups
                            std::unordered_map<std::string, std::vector<std::string>> pin_groups;
                            for (const auto pin_group : gate_type_it->second->get_pin_groups())
                            {
                                const auto pins = pin_group->get_pins();
                                for (auto it = pins.rbegin(); it != pins.rend(); it++)
                                {
                                    const auto* pin = *it;
                                    pin_groups[pin_group->get_name()].push_back(pin->get_name());
                                }
                            }
 
                            for (const auto& port_assignment : instance->m_port_assignments)
                            {
                                std::vector<std::string> right_port = expand_assignment_expression(verilog_module, port_assignment.m_assignment);
                                if (!right_port.empty())
                                {
                                    std::vector<std::string> left_port;
 
                                    const auto& port_name = port_assignment.m_port_name.value();
                                    if (const auto group_it = pin_groups.find(port_name); group_it != pin_groups.end())
                                    {
                                        left_port = group_it->second;
                                    }
                                    else
                                    {
                                        left_port.push_back(port_name);
                                    }
 
                                    u32 max_size = right_port.size() <= left_port.size() ? right_port.size() : left_port.size();
 
                                    for (u32 i = 0; i < max_size; i++)
                                    {
                                        instance->m_expanded_port_assignments.push_back(std::make_pair(left_port.at(i), right_port.at(i)));
                                    }
                                }
                            }
                        }
                        // all port assignments by order
                        else
                        {
                            // cache pins
                            std::vector<std::string> pins = gate_type_it->second->get_pin_names();
                            auto pin_it                   = pins.begin();
 
                            for (const auto& port_assignment : instance->m_port_assignments)
                            {
                                std::vector<std::string> right_port = expand_assignment_expression(verilog_module, port_assignment.m_assignment);
                                if (!right_port.empty())
                                {
                                    std::vector<std::string> left_port;
 
                                    for (u32 i = 0; i < right_port.size() && pin_it != pins.end(); i++)
                                    {
                                        left_port.push_back(*pin_it++);
                                    }
 
                                    u32 max_size = right_port.size() <= left_port.size() ? right_port.size() : left_port.size();
 
                                    for (u32 i = 0; i < max_size; i++)
                                    {
                                        instance->m_expanded_port_assignments.push_back(std::make_pair(left_port.at(i), right_port.at(i)));
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
 
        // for the top module, generate global i/o signals for all ports
        std::unordered_map<std::string, std::string> top_assignments;
        for (const auto& port : top_module->m_ports)
        {
            for (const auto& expanded_port_identifier : port->m_expanded_identifiers)
            {
                const auto signal_name = get_unique_alias("", expanded_port_identifier + "__GLOBAL_IO__", m_net_name_occurences);
                m_net_name_occurences[signal_name]++;
 
                Net* global_port_net = m_netlist->create_net(signal_name);
                if (global_port_net == nullptr)
                {
                    return ERR("could not construct netlist: failed to create global I/O net '" + signal_name + "'");
                }
 
                m_net_by_name[signal_name] = global_port_net;
 
                // assign global port nets to ports of top module
                top_assignments[expanded_port_identifier] = signal_name;
 
                if (port->m_direction == PinDirection::input || port->m_direction == PinDirection::inout)
                {
                    if (!global_port_net->mark_global_input_net())
                    {
                        return ERR("could not construct netlist: failed to mark global I/O net '" + signal_name + "' as global input");
                    }
                }
 
                if (port->m_direction == PinDirection::output || port->m_direction == PinDirection::inout)
                {
                    if (!global_port_net->mark_global_output_net())
                    {
                        return ERR("could not construct netlist: failed to mark global I/O net '" + signal_name + "' as global output");
                    }
                }
            }
        }
 
        if (auto res = instantiate_module("top_module", top_module, nullptr, top_assignments); res.is_error())
        {
            return ERR_APPEND(res.get_error(), "could not construct netlist: unable to instantiate top module");
        }
 
        // merge nets without gates in between them
        std::unordered_map<std::string, std::string> merged_nets;
        std::unordered_map<std::string, std::vector<std::string>> master_to_slaves;
 
        for (auto& [master, slave] : m_nets_to_merge)
        {
            // check if master net has already been merged into other net
            while (true)
            {
                if (const auto master_it = merged_nets.find(master); master_it != merged_nets.end())
                {
                    master = master_it->second;
                }
                else
                {
                    break;
                }
            }
 
            // check if slave net has already been merged into other net
            while (true)
            {
                if (const auto slave_it = merged_nets.find(slave); slave_it != merged_nets.end())
                {
                    slave = slave_it->second;
                }
                else
                {
                    break;
                }
            }
 
            auto master_net = m_net_by_name.at(master);
            auto slave_net  = m_net_by_name.at(slave);
 
            if (master_net == slave_net)
            {
                continue;
            }
            else if (slave_net == m_zero_net || slave_net == m_one_net)
            {
                auto* tmp_net = master_net;
                master_net    = slave_net;
                slave_net     = tmp_net;
 
                auto tmp_name = master;
                master        = slave;
                slave         = tmp_name;
            }
 
            // merge sources
            if (slave_net->is_global_input_net())
            {
                master_net->mark_global_input_net();
            }
 
            for (auto src : slave_net->get_sources())
            {
                Gate* src_gate   = src->get_gate();
                GatePin* src_pin = src->get_pin();
 
                if (!slave_net->remove_source(src))
                {
                    return ERR("could not construct netlist: failed to remove source from net '" + slave_net->get_name() + "' with ID " + std::to_string(slave_net->get_id()));
                }
 
                if (!master_net->is_a_source(src_gate, src_pin))
                {
                    if (!master_net->add_source(src_gate, src_pin))
                    {
                        return ERR("could not construct netlist: failed to add source to net '" + master_net->get_name() + "' with ID " + std::to_string(master_net->get_id()));
                    }
                }
            }
 
            // merge destinations
            if (slave_net->is_global_output_net())
            {
                master_net->mark_global_output_net();
            }
 
            for (auto dst : slave_net->get_destinations())
            {
                Gate* dst_gate   = dst->get_gate();
                GatePin* dst_pin = dst->get_pin();
 
                if (!slave_net->remove_destination(dst))
                {
                    return ERR("could not construct netlist: failed to remove destination from net '" + slave_net->get_name() + "' with ID " + std::to_string(slave_net->get_id()));
                }
 
                if (!master_net->is_a_destination(dst_gate, dst_pin))
                {
                    if (!master_net->add_destination(dst_gate, dst_pin))
                    {
                        return ERR("could not construct netlist: failed to add destination to net '" + master_net->get_name() + "' with ID " + std::to_string(master_net->get_id()));
                    }
                }
            }
 
            // merge generics and attributes
            for (const auto& [identifier, content] : slave_net->get_data_map())
            {
                if (!master_net->set_data(std::get<0>(identifier), std::get<1>(identifier), std::get<0>(content), std::get<1>(content)))
                {
                    log_warning("verilog_parser",
                                "unable to transfer data from slave net '{}' with ID {} to master net '{}' with ID {}.",
                                slave_net->get_name(),
                                slave_net->get_id(),
                                master_net->get_name(),
                                master_net->get_id());
                }
            }
 
            // update module ports
            if (const auto it = m_module_port_by_net.find(slave_net); it != m_module_port_by_net.end())
            {
                for (auto [module, index] : it->second)
                {
                    std::get<1>(m_module_ports.at(module).at(index)) = master_net;
                }
                m_module_port_by_net[master_net].insert(m_module_port_by_net[master_net].end(), it->second.begin(), it->second.end());
                m_module_port_by_net.erase(it);
            }
 
            m_netlist->delete_net(slave_net);
            m_net_by_name.erase(slave);
            merged_nets[slave] = master;
            master_to_slaves[master].push_back(slave);
        }
 
        // annotate all surviving master nets with the net names that where merged into them
        for (auto& master_net : m_netlist->get_nets())
        {
            const auto master_name = master_net->get_name();
 
            if (const auto m2s_it = master_to_slaves.find(master_name); m2s_it != master_to_slaves.end())
            {
                std::vector<std::vector<std::string>> merged_slaves;
                auto current_slaves = m2s_it->second;
 
                while (!current_slaves.empty())
                {
                    std::vector<std::string> next_slaves;
                    for (const auto& s : current_slaves)
                    {
                        if (const auto m2s_inner_it = master_to_slaves.find(s); m2s_inner_it != master_to_slaves.end())
                        {
                            next_slaves.insert(next_slaves.end(), m2s_inner_it->second.begin(), m2s_inner_it->second.end());
                        }
                    }
 
                    merged_slaves.push_back(current_slaves);
                    current_slaves = next_slaves;
                    next_slaves.clear();
                }
 
                // annotate all merged slave wire names as a JSON formatted list of list of strings
                // each net can span a tree of "consumed" slave wire names where the nth list represents all wire names that where merged at depth n
                std::string merged_str = "";
                bool has_merged_nets   = false;
                for (const auto& vec : merged_slaves)
                {
                    if (!vec.empty())
                    {
                        has_merged_nets = true;
                    }
                    const auto s = utils::join(", ", vec, [](const auto e) { return '"' + e + '"'; });
                    merged_str += "[" + s + "], ";
                }
                merged_str = merged_str.substr(0, merged_str.size() - 2);
 
                if (has_merged_nets)
                {
                    master_net->set_data("parser_annotation", "merged_nets", "string", "[" + merged_str + "]");
                }
            }
        }
 
        // add global GND gate if required by any instance
        if (m_netlist->get_gnd_gates().empty())
        {
            if (m_zero_net->get_num_of_destinations() > 0)
            {
                GateType* gnd_type  = m_gnd_gate_types.begin()->second;
                GatePin* output_pin = gnd_type->get_output_pins().front();
                Gate* gnd           = m_netlist->create_gate(m_netlist->get_unique_gate_id(), gnd_type, "global_gnd");
 
                if (!m_netlist->mark_gnd_gate(gnd))
                {
                    return ERR("failed to mark GND gate");
                }
 
                if (m_zero_net->add_source(gnd, output_pin) == nullptr)
                {
                    return ERR("failed to add source to GND gate");
                }
            }
            else
            {
                m_netlist->delete_net(m_zero_net);
                m_zero_net = nullptr;
            }
        }
 
        // add global VCC gate if required by any instance
        if (m_netlist->get_vcc_gates().empty())
        {
            if (m_one_net->get_num_of_destinations() > 0)
            {
                GateType* vcc_type  = m_vcc_gate_types.begin()->second;
                GatePin* output_pin = vcc_type->get_output_pins().front();
                Gate* vcc           = m_netlist->create_gate(m_netlist->get_unique_gate_id(), vcc_type, "global_vcc");
 
                if (!m_netlist->mark_vcc_gate(vcc))
                {
                    return ERR("failed to mark VCC gate");
                }
 
                if (m_one_net->add_source(vcc, output_pin) == nullptr)
                {
                    return ERR("failed to add source to VCC gate");
                }
            }
            else
            {
                m_netlist->delete_net(m_one_net);
                m_one_net = nullptr;
            }
        }
 
        // update module nets, internal nets, input nets, and output nets
        for (Module* module : m_netlist->get_modules())
        {
            module->update_nets();
        }
 
        // assign module pins
        for (const auto& [module, ports] : m_module_ports)
        {
            std::unordered_set<Net*> input_nets  = module->get_input_nets();
            std::unordered_set<Net*> output_nets = module->get_output_nets();
 
            for (const auto& [port_name, port_net] : ports)
            {
                if (!module->is_input_net(port_net) && !module->is_output_net(port_net))
                {
                    continue;
                }
 
                if (auto res = module->create_pin(port_name, port_net); res.is_error())
                {
                    return ERR_APPEND(res.get_error(),
                                      "could not construct netlist: failed to create pin '" + port_name + "' at net '" + port_net->get_name() + "' with ID " + std::to_string(port_net->get_id())
                                          + " within module '" + module->get_name() + "' with ID " + std::to_string(module->get_id()));
                }
            }
        }
 
        m_netlist->enable_automatic_net_checks(true);
        return OK({});
    }
 
    Result<Module*> VerilogParser::instantiate_module(const std::string& instance_identifier,
                                                      VerilogModule* verilog_module,
                                                      Module* parent,
                                                      const std::unordered_map<std::string, std::string>& parent_module_assignments)
    {
        std::unordered_map<std::string, std::string> signal_alias;
        std::unordered_map<std::string, std::string> instance_alias;
 
        // TODO check parent module assignments for port aliases
 
        const std::string parent_name       = (parent == nullptr) ? "" : parent->get_name();
        instance_alias[instance_identifier] = get_unique_alias(parent_name, instance_identifier, m_instance_name_occurences);
 
        // create netlist module
        Module* module;
        if (parent == nullptr)
        {
            module = m_netlist->get_top_module();
            module->set_name(instance_alias.at(instance_identifier));
        }
        else
        {
            module = m_netlist->create_module(instance_alias.at(instance_identifier), parent);
        }
 
        std::string instance_type = verilog_module->m_name;
        if (module == nullptr)
        {
            return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to create module");
        }
        module->set_type(instance_type);
 
        // assign entity-level attributes
        for (const VerilogDataEntry& attribute : verilog_module->m_attributes)
        {
            if (!module->set_data("attribute", attribute.m_name, attribute.m_type, attribute.m_value))
            {
                log_warning("verilog_parser",
                            "could not set attribute '{} = {}' of type '{}' for instance '{}' type '{}'.",
                            attribute.m_name,
                            attribute.m_value,
                            attribute.m_type,
                            instance_identifier,
                            instance_type);
            }
        }
 
        // assign module port names
        for (const auto& port : verilog_module->m_ports)
        {
            for (const auto& expanded_port_identifier : port->m_expanded_identifiers)
            {
                if (const auto it = parent_module_assignments.find(expanded_port_identifier); it != parent_module_assignments.end())
                {
                    Net* port_net = m_net_by_name.at(it->second);
                    m_module_ports[module].push_back(std::make_tuple(expanded_port_identifier, port_net));
                    m_module_port_by_net[port_net].push_back(std::make_pair(module, m_module_ports[module].size() - 1));
                }
            }
        }
 
        // create internal signals
        for (const auto& signal : verilog_module->m_signals)
        {
            for (const auto& expanded_name : signal->m_expanded_names)
            {
                std::string unique_net_name = get_unique_alias(module->get_name(), expanded_name, m_net_name_occurences);
                if (unique_net_name != expanded_name)
                {
                    m_net_name_occurences[unique_net_name]++;
                }
                signal_alias[expanded_name] = unique_net_name;
 
                // create new net for the signal
                Net* signal_net = m_netlist->create_net(signal_alias.at(expanded_name));
                if (signal_net == nullptr)
                {
                    return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to create net '" + expanded_name + "'");
                }
 
                m_net_by_name[signal_alias.at(expanded_name)] = signal_net;
 
                // assign signal attributes
                for (const VerilogDataEntry& attribute : signal->m_attributes)
                {
                    if (!signal_net->set_data("attribute", attribute.m_name, "unknown", attribute.m_value))
                    {
                        log_warning("verilog_parser",
                                    "could not set attribute ({} = {}) for net '{}' of instance '{}' of type '{}'.",
                                    attribute.m_name,
                                    attribute.m_value,
                                    expanded_name,
                                    instance_identifier,
                                    instance_type);
                    }
                }
            }
        }
 
        // schedule assigned nets for merging
        for (const auto& [left_expanded_signal, right_expanded_signal] : verilog_module->m_expanded_assignments)
        {
            std::string a = left_expanded_signal;
            std::string b = right_expanded_signal;
 
            if (const auto alias_it = signal_alias.find(a); alias_it != signal_alias.end())
            {
                a = alias_it->second;
            }
            else
            {
                return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to find alias for net '" + a + "'");
            }
 
            if (const auto alias_it = signal_alias.find(b); alias_it != signal_alias.end())
            {
                b = alias_it->second;
            }
            else if (b == "'Z'" || b == "'X'")
            {
                continue;
            }
            else if (b != "'0'" && b != "'1'")
            {
                return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to find alias for net '" + b + "'");
            }
 
            m_nets_to_merge.push_back(std::make_pair(a, b));
        }
 
        // schedule assigned port nets for merging
        for (const auto& [port_identifier, net_name] : parent_module_assignments)
        {
            std::string signal_name;
            if (const auto expr_it = verilog_module->m_expanded_port_identifiers_to_expressions.find(port_identifier); expr_it == verilog_module->m_expanded_port_identifiers_to_expressions.end())
            {
                signal_name = port_identifier;
            }
            else
            {
                signal_name = expr_it->second;
            }
 
            // TODO handle identifier != expression
            if (const auto alias_it = signal_alias.find(signal_name); alias_it != signal_alias.end())
            {
                const bool swap = net_name.find("__GLOBAL_IO__") == std::string::npos;
                m_nets_to_merge.push_back(swap ? std::make_pair(net_name, alias_it->second) : std::make_pair(alias_it->second, net_name));
            }
            else
            {
                return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to find alias for net '" + signal_name + "'");
            }
        }
 
        // process instances i.e. gates or other entities
        for (const auto& instance : verilog_module->m_instances)
        {
            // will later hold either module or gate, so attributes can be assigned properly
            DataContainer* container = nullptr;
 
            // assign actual signal names to ports
            std::unordered_map<std::string, std::string> instance_assignments;
 
            // if the instance is another entity, recursively instantiate it
            if (auto module_it = m_modules_by_name.find(instance->m_type); module_it != m_modules_by_name.end())
            {
                // expand port assignments
                for (const auto& [port, assignment] : instance->m_expanded_port_assignments)
                {
                    if (const auto alias_it = signal_alias.find(assignment); alias_it != signal_alias.end())
                    {
                        instance_assignments[port] = alias_it->second;
                    }
                    else if (assignment == "'0'" || assignment == "'1'")
                    {
                        instance_assignments[port] = assignment;
                    }
                    else if (assignment == "'Z'" || assignment == "'X'" || assignment.empty())
                    {
                        continue;
                    }
                    else
                    {
                        return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': port assignment '" + port + " = " + assignment + "' is invalid");
                    }
                }
 
                if (auto res = instantiate_module(instance->m_name, module_it->second, module, instance_assignments); res.is_error())
                {
                    return ERR_APPEND(res.get_error(),
                                      "could not create instance '" + instance_identifier + "' of type '" + instance_type + "': unable to create instance '" + instance->m_name + "' of type '"
                                          + module_it->second->m_name + "'");
                }
                else
                {
                    container = res.get();
                }
            }
            // otherwise it has to be an element from the gate library
            else if (const auto gate_type_it = m_gate_types.find(instance->m_type); gate_type_it != m_gate_types.end())
            {
                // create the new gate
                instance_alias[instance->m_name] = get_unique_alias(module->get_name(), instance->m_name, m_instance_name_occurences);
                Gate* new_gate                   = m_netlist->create_gate(gate_type_it->second, instance_alias.at(instance->m_name));
                if (new_gate == nullptr)
                {
                    return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to create gate '" + instance->m_name + "'");
                }
 
                if (!module->is_top_module())
                {
                    module->assign_gate(new_gate);
                }
 
                container = new_gate;
 
                // if gate is of a GND or VCC gate type, mark it as such
                if (m_vcc_gate_types.find(instance->m_type) != m_vcc_gate_types.end() && !new_gate->mark_vcc_gate())
                {
                    return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to mark '" + instance->m_name + "' of type '" + instance->m_type
                               + "' as GND gate");
                }
                if (m_gnd_gate_types.find(instance->m_type) != m_gnd_gate_types.end() && !new_gate->mark_gnd_gate())
                {
                    return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to mark '" + instance->m_name + "' of type '" + instance->m_type
                               + "' as VCC gate");
                }
 
                // cache pin names
                std::unordered_map<std::string, GatePin*> pin_names_map;
                for (auto* pin : gate_type_it->second->get_pins())
                {
                    pin_names_map[pin->get_name()] = pin;
                }
 
                // expand pin assignments
                for (const auto& [pin, assignment] : instance->m_expanded_port_assignments)
                {
                    std::string signal;
 
                    if (const auto alias_it = signal_alias.find(assignment); alias_it != signal_alias.end())
                    {
                        signal = alias_it->second;
                    }
                    else if (assignment == "'0'" || assignment == "'1'")
                    {
                        signal = assignment;
                    }
                    else if (assignment == "'Z'" || assignment == "'X'")
                    {
                        continue;
                    }
                    else
                    {
                        return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to assign '" + assignment + "' to pin '" + pin + "' of gate '"
                                   + instance->m_name + "' of type '" + instance->m_type + "' as the assignment is invalid");
                    }
 
                    // get the respective net for the assignment
                    if (const auto net_it = m_net_by_name.find(signal); net_it == m_net_by_name.end())
                    {
                        return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to assign signal'" + signal + "' to pin '" + pin
                                   + "' as the signal has not been declared");
                    }
                    else
                    {
                        Net* current_net = net_it->second;
 
                        // add net src/dst by pin types
                        bool is_input  = false;
                        bool is_output = false;
 
                        if (const auto it = pin_names_map.find(pin); it != pin_names_map.end())
                        {
                            PinDirection direction = it->second->get_direction();
                            if (direction == PinDirection::input || direction == PinDirection::inout)
                            {
                                is_input = true;
                            }
 
                            if (direction == PinDirection::output || direction == PinDirection::inout)
                            {
                                is_output = true;
                            }
                        }
 
                        if (!is_input && !is_output)
                        {
                            return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to assign net '" + signal + "' to pin '" + pin
                                       + "' as it is not a pin of gate '" + new_gate->get_name() + "' of type '" + new_gate->get_type()->get_name() + "'");
                        }
 
                        if (is_output && !current_net->add_source(new_gate, pin))
                        {
                            return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to add net '" + signal + "' as a source to gate '"
                                       + new_gate->get_name() + "' via pin '" + pin + "'");
                        }
 
                        if (is_input && !current_net->add_destination(new_gate, pin))
                        {
                            return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to add net '" + signal + "' as a destination to gate '"
                                       + new_gate->get_name() + "' via pin '" + pin + "'");
                        }
                    }
                }
            }
            else
            {
                return ERR("could not create instance '" + instance_identifier + "' of type '" + instance_type + "': failed to find gate type '" + instance->m_type + "' in gate library '"
                           + m_netlist->get_gate_library()->get_name() + "'");
            }
 
            // assign instance attributes
            for (const auto& attribute : instance->m_attributes)
            {
                if (!container->set_data("attribute", attribute.m_name, attribute.m_type, attribute.m_value))
                {
                    log_warning("verilog_parser",
                                "could not set attribute '{} = {}' of type '{}' for instance '{}' of type '{}' within instance '{}' of type '{}'.",
                                attribute.m_name,
                                attribute.m_value,
                                attribute.m_type,
                                instance->m_name,
                                instance->m_type,
                                instance_identifier,
                                instance_type);
                }
            }
 
            // For gate instances, prefer the gate type's own parameter declaration over
            // the parser-inferred one — this is the only way Enum parameters can be set.
            const GateType* gt = nullptr;
            if (const Gate* g = dynamic_cast<const Gate*>(container))
            {
                gt = g->get_type();
            }
 
            for (const auto& parameter : instance->m_parameters)
            {
                if (!parameter.m_parameter.has_value())
                {
                    log_warning(
                        "verilog_parser", "could not set generic '{}' for instance '{}' of type '{}': no typed parameter declaration available.", parameter.m_name, instance->m_name, instance->m_type);
                    continue;
                }
                Parameter effective_param = parameter.m_parameter.value();
                if (gt != nullptr)
                {
                    if (auto decl = gt->get_parameter(parameter.m_name); decl.is_ok())
                    {
                        effective_param = decl.get();
                    }
                }
                if (auto res = container->set_parameter(effective_param, parameter.m_value); res.is_error())
                {
                    log_warning("verilog_parser",
                                "could not set parameter '{} = {}' for instance '{}' of type '{}' within instance '{}' of type '{}': {}",
                                parameter.m_name,
                                parameter.m_value,
                                instance->m_name,
                                instance->m_type,
                                instance_identifier,
                                instance_type,
                                res.get_error().get());
                }
            }
        }
 
        return OK(module);
    }
 
    // ###########################################################################
    // ###################          Helper Functions          ####################
    // ###########################################################################
 
    namespace
    {
        static const std::map<char, BooleanFunction::Value> bin_map = {{'0', BooleanFunction::Value::ZERO},
                                                                       {'1', BooleanFunction::Value::ONE},
                                                                       {'X', BooleanFunction::Value::X},
                                                                       {'Z', BooleanFunction::Value::Z}};
 
        static const std::map<char, std::vector<BooleanFunction::Value>> oct_map = {{'0', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO}},
                                                                                    {'1', {BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO}},
                                                                                    {'2', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO}},
                                                                                    {'3', {BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO}},
                                                                                    {'4', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE}},
                                                                                    {'5', {BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE}},
                                                                                    {'6', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE}},
                                                                                    {'7', {BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE}},
                                                                                    {'X', {BooleanFunction::Value::X, BooleanFunction::Value::X, BooleanFunction::Value::X}},
                                                                                    {'Z', {BooleanFunction::Value::Z, BooleanFunction::Value::Z, BooleanFunction::Value::Z}}};
 
        static const std::map<char, std::vector<BooleanFunction::Value>> hex_map = {
            {'0', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO}},
            {'1', {BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO}},
            {'2', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO}},
            {'3', {BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO}},
            {'4', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO}},
            {'5', {BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO}},
            {'6', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO}},
            {'7', {BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO}},
            {'8', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE}},
            {'9', {BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE}},
            {'A', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE}},
            {'B', {BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE}},
            {'C', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE}},
            {'D', {BooleanFunction::Value::ONE, BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE}},
            {'E', {BooleanFunction::Value::ZERO, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE}},
            {'F', {BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE, BooleanFunction::Value::ONE}},
            {'X', {BooleanFunction::Value::X, BooleanFunction::Value::X, BooleanFunction::Value::X, BooleanFunction::Value::X}},
            {'Z', {BooleanFunction::Value::Z, BooleanFunction::Value::Z, BooleanFunction::Value::Z, BooleanFunction::Value::Z}}};
    }    // namespace
 
    // generate a unique name for a gate/module instance
    std::string VerilogParser::get_unique_alias(const std::string& parent_name, const std::string& name, const std::unordered_map<std::string, u32>& name_occurences) const
    {
        std::string unique_alias = name;
 
        if (!parent_name.empty())
        {
            // if there is no other instance with that name, we omit the name prefix
 
            auto instance_name_it = name_occurences.find(name);
 
            int cnt = 0;
 
            // it is OK if base name (first loop cnt=0) is already in name_occurences once
            // unique_alias (cnt > 0) must not be in name_occurences
            while (instance_name_it != name_occurences.end() && (cnt || instance_name_it->second > 1))
            {
                std::string extension;
                if (cnt++)
                {
                    extension = "_u" + std::to_string(cnt);
                }
                unique_alias     = parent_name + instance_name_seperator + unique_alias + extension;
                instance_name_it = name_occurences.find(unique_alias);
            }
        }
 
        return unique_alias;
    }
 
    std::vector<u32> VerilogParser::parse_range(TokenStream<std::string>& stream) const
    {
        if (stream.remaining() == 1)
        {
            return {(u32)std::stoi(stream.consume().string)};
        }
 
        // MSB to LSB
        const int end = std::stoi(stream.consume().string);
        stream.consume(":", true);
        const int start = std::stoi(stream.consume().string);
 
        const int direction = (start <= end) ? 1 : -1;
 
        std::vector<u32> result;
        for (int i = start; i != end + direction; i += direction)
        {
            result.push_back((u32)i);
        }
        return result;
    }
 
    void VerilogParser::expand_ranges_recursively(std::vector<std::string>& expanded_names, const std::string& current_name, const std::vector<std::vector<u32>>& ranges, u32 dimension) const
    {
        // expand signal recursively
        if (ranges.size() > dimension)
        {
            for (const u32 index : ranges[dimension])
            {
                expand_ranges_recursively(expanded_names, current_name + "(" + std::to_string(index) + ")", ranges, dimension + 1);
            }
        }
        else
        {
            // last dimension
            expanded_names.push_back(current_name);
        }
    }
 
    std::vector<std::string> VerilogParser::expand_ranges(const std::string& name, const std::vector<std::vector<u32>>& ranges) const
    {
        std::vector<std::string> res;
 
        expand_ranges_recursively(res, name, ranges, 0);
 
        return res;
    }
 
    Result<std::vector<BooleanFunction::Value>> VerilogParser::get_binary_vector(std::string value) const
    {
        value = utils::to_upper(utils::replace(value, std::string("_"), std::string("")));
 
        i32 len = -1;
        std::string prefix;
        std::string number;
        std::vector<BooleanFunction::Value> result;
 
        // base specified?
        if (value.find('\'') == std::string::npos)
        {
            prefix = "D";
            number = value;
        }
        else
        {
            if (value.at(0) != '\'')
            {
                len = std::stoi(value.substr(0, value.find('\'')));
            }
            prefix = value.substr(value.find('\'') + 1, 1);
            number = value.substr(value.find('\'') + 2);
        }
 
        // select base
        switch (prefix.at(0))
        {
            case 'B': {
                for (auto it = number.rbegin(); it != number.rend(); it++)
                {
                    const char c = *it;
                    if (c == '0' || c == '1' || c == 'Z' || c == 'X')
                    {
                        result.push_back(bin_map.at(c));
                    }
                    else
                    {
                        return ERR("could not convert string to binary vector: invalid character within binary number literal '" + value + "'");
                    }
                }
                break;
            }
 
            case 'O':
                for (auto it = number.rbegin(); it != number.rend(); it++)
                {
                    const char c = *it;
                    if ((c >= '0' && c <= '7') || c == 'X' || c == 'Z')
                    {
                        const auto& bits = oct_map.at(c);
                        result.insert(result.end(), bits.begin(), bits.end());
                    }
                    else
                    {
                        return ERR("could not convert string to binary vector: invalid character within octal number literal '" + value + "'");
                    }
                }
                break;
 
            case 'D': {
                u64 tmp_val = 0;
 
                for (const char c : number)
                {
                    if ((c >= '0' && c <= '9'))
                    {
                        tmp_val = (tmp_val * 10) + (c - '0');
                    }
                    else
                    {
                        return ERR("could not convert string to binary vector: invalid character within decimal number literal '" + value + "'");
                    }
                }
 
                do
                {
                    result.push_back(((tmp_val & 1) == 1) ? BooleanFunction::Value::ONE : BooleanFunction::Value::ZERO);
                    tmp_val >>= 1;
                } while (tmp_val != 0);
                break;
            }
 
            case 'H': {
                for (auto it = number.rbegin(); it != number.rend(); it++)
                {
                    const char c = *it;
                    if ((c >= '0' && c <= '9') || (c >= 'A' && c <= 'F') || c == 'X' || c == 'Z')
                    {
                        const auto& bits = hex_map.at(c);
                        result.insert(result.end(), bits.begin(), bits.end());
                    }
                    else
                    {
                        return ERR("could not convert string to binary vector: invalid character within hexadecimal number literal '" + value + "'");
                    }
                }
                break;
            }
 
            default: {
                return ERR("could not convert string to binary vector: invalid base '" + prefix + "' within number literal '" + value + "'");
            }
        }
 
        if (len != -1)
        {
            i32 result_size = result.size();
 
            if (len > result_size)
            {
                // fill with '0'
                for (i32 i = 0; i < (len - result_size); i++)
                {
                    result.push_back(BooleanFunction::Value::ZERO);
                }
            }
            else
            {
                // drop trailing bits
                for (i32 i = 0; i < (result_size - len); i++)
                {
                    result.pop_back();
                }
            }
        }
 
        return OK(result);
    }
 
    Result<std::string> VerilogParser::get_hex_from_literal(const Token<std::string>& value_token) const
    {
        const u32 line_number   = value_token.number;
        const std::string value = utils::to_upper(utils::replace(value_token.string, std::string("_"), std::string("")));
 
        i32 len = -1;
        std::string prefix;
        std::string number;
        u32 base;
 
        // base specified?
        if (value.find('\'') == std::string::npos)
        {
            prefix = "D";
            number = value;
        }
        else
        {
            if (value.at(0) != '\'')
            {
                len = std::stoi(value.substr(0, value.find('\'')));
            }
            prefix = value.substr(value.find('\'') + 1, 1);
            number = value.substr(value.find('\'') + 2);
        }
 
        // select base
        switch (prefix.at(0))
        {
            case 'B': {
                if (!std::all_of(number.begin(), number.end(), [](const char& c) { return (c >= '0' && c <= '1'); }))
                {
                    return ERR("could not convert token to hexadecimal string: invalid character within binary number literal '" + value + "' (line " + std::to_string(line_number) + ")");
                }
 
                base = 2;
                break;
            }
 
            case 'O': {
                if (!std::all_of(number.begin(), number.end(), [](const char& c) { return (c >= '0' && c <= '7'); }))
                {
                    return ERR("could not convert token to hexadecimal string: invalid character within ocatl number literal '" + value + "' (line " + std::to_string(line_number) + ")");
                }
 
                base = 8;
                break;
            }
 
            case 'D': {
                if (!std::all_of(number.begin(), number.end(), [](const char& c) { return (c >= '0' && c <= '9'); }))
                {
                    return ERR("could not convert token to hexadecimal string: invalid character within decimal number literal '" + value + "' (line " + std::to_string(line_number) + ")");
                }
 
                base = 10;
                break;
            }
 
            case 'H': {
                std::string res;
 
                for (const char c : number)
                {
                    if ((c >= '0' && c <= '9') || (c >= 'A' && c <= 'F'))
                    {
                        res += c;
                    }
                    else
                    {
                        return ERR("could not convert token to hexadecimal string: invalid character within hexadecimal number literal '" + value + "' (line " + std::to_string(line_number) + ")");
                    }
                }
 
                return OK(res);
            }
 
            default: {
                return ERR("could not convert token to hexadecimal string: invalid base '" + prefix + "' within number literal '" + value + "' (line " + std::to_string(line_number) + ")");
            }
        }
 
        std::stringstream ss;
        if (len != -1)
        {
            // fill with '0'
            ss << std::uppercase << std::setfill('0') << std::setw((len + 3) / 4) << std::hex << stoull(number, 0, base);
        }
        else
        {
            ss << std::uppercase << std::hex << stoull(number, 0, base);
        }
        return OK(ss.str());
    }
 
    Result<std::pair<Parameter, std::string>> VerilogParser::parse_parameter_value(const std::string& name, const Token<std::string>& value_token) const
    {
        const std::string& raw    = value_token.string;
        const u32 line_number     = value_token.number;
        const std::string loc_str = " (line " + std::to_string(line_number) + ")";
 
        // integer (plain decimal, no Verilog base prefix)
        if (utils::is_integer(raw))
        {
            auto param_res = Parameter::Integer(name, "");
            if (param_res.is_error())
            {
                return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
            }
            return OK(std::make_pair(param_res.get(), raw));
        }
 
        // floating-point (double precision, full-consume)
        if (is_double_strict(raw))
        {
            auto param_res = Parameter::Float(name, "");
            if (param_res.is_error())
            {
                return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
            }
            return OK(std::make_pair(param_res.get(), raw));
        }
 
        // boolean: case-insensitive 'true' / 'false'
        {
            const std::string lower = utils::to_lower(raw);
            if (lower == "true" || lower == "false")
            {
                auto param_res = Parameter::Boolean(name, "");
                if (param_res.is_error())
                {
                    return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
                }
                return OK(std::make_pair(param_res.get(), lower));
            }
        }
 
        // time literal: <number><unit> with unit in {min, fs, ps, ns, us, ms, s, h}
        // longest units listed first to avoid partial suffix matches
        {
            static const std::vector<std::string> time_units = {"min", "fs", "ps", "ns", "us", "ms", "s", "h"};
            for (const auto& unit : time_units)
            {
                if (raw.size() <= unit.size() || !utils::ends_with(raw, unit))
                {
                    continue;
                }
                const std::string num_part = raw.substr(0, raw.size() - unit.size());
                if (!utils::is_integer(num_part) && !is_double_strict(num_part))
                {
                    continue;
                }
                auto param_res = Parameter::Time(name, "");
                if (param_res.is_error())
                {
                    return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
                }
                return OK(std::make_pair(param_res.get(), raw));
            }
        }
 
        // string literal: strip outer quotes, no escape processing
        if (raw.size() >= 2 && raw.front() == '"' && raw.back() == '"')
        {
            auto param_res = Parameter::String(name, "");
            if (param_res.is_error())
            {
                return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
            }
            return OK(std::make_pair(param_res.get(), raw.substr(1, raw.size() - 2)));
        }
 
        // bit/logic vector literal: [N]'[b|o|h|d][digits]
        if (!raw.empty() && (isdigit(static_cast<unsigned char>(raw[0])) || raw[0] == '\''))
        {
            const size_t tick_pos = raw.find('\'');
            if (tick_pos == std::string::npos)
            {
                return ERR("could not parse parameter value: no base prefix in literal '" + raw + "'" + loc_str);
            }
 
            // optional explicit width before the tick
            u16 explicit_width = 0;
            bool has_width     = false;
            if (tick_pos > 0)
            {
                try
                {
                    explicit_width = static_cast<u16>(std::stoul(raw.substr(0, tick_pos)));
                }
                catch (...)
                {
                    return ERR("could not parse parameter value: invalid width in literal '" + raw + "'" + loc_str);
                }
                has_width = true;
            }
 
            if (tick_pos + 1 >= raw.size())
            {
                return ERR("could not parse parameter value: missing base char in literal '" + raw + "'" + loc_str);
            }
            const char base_upper = static_cast<char>(std::toupper(static_cast<unsigned char>(raw[tick_pos + 1])));
 
            // resolve all base properties in one place; bits_per_digit == 0 flags decimal (needs conversion)
            std::string numeric_set;
            std::string out_prefix;
            int bits_per_digit = 0;
            bool allow_state   = true;
            switch (base_upper)
            {
                case 'B':
                    numeric_set    = "01";
                    out_prefix     = "0b";
                    bits_per_digit = 1;
                    break;
                case 'O':
                    numeric_set    = "01234567";
                    out_prefix     = "0o";
                    bits_per_digit = 3;
                    break;
                case 'H':
                    numeric_set    = "0123456789abcdef";
                    out_prefix     = "0x";
                    bits_per_digit = 4;
                    break;
                case 'D':
                    numeric_set    = "0123456789";
                    out_prefix     = "0x";
                    bits_per_digit = 0;
                    allow_state    = false;
                    break;
                default:
                    return ERR("could not parse parameter value: unsupported base '" + std::string(1, base_upper) + "' in literal '" + raw + "'" + loc_str);
            }
 
            // single pass: strip underscores, map '?' to '-', validate, detect state chars
            std::string digits;
            digits.reserve(raw.size());
            bool has_state = false;
            for (size_t i = tick_pos + 2; i < raw.size(); ++i)
            {
                const char c = raw[i];
                if (c == '_')
                {
                    continue;
                }
                const char mapped   = (c == '?') ? '-' : c;
                const char l        = (mapped == '-') ? '-' : static_cast<char>(std::tolower(static_cast<unsigned char>(mapped)));
                const bool is_num   = numeric_set.find(l) != std::string::npos;
                const bool is_state = (l == 'x' || l == 'z' || l == '-');
                if (!is_num && (!allow_state || !is_state))
                {
                    return ERR("could not parse parameter value: literal '" + raw + "' contains invalid digit '" + std::string(1, c) + "'" + loc_str);
                }
                if (is_state)
                {
                    has_state = true;
                }
                digits += mapped;
            }
 
            if (digits.empty())
            {
                return ERR("could not parse parameter value: no digits in literal '" + raw + "'" + loc_str);
            }
 
            // helper: build the right Parameter type and return
            const auto make_param = [&](u16 size, const std::string& value) -> Result<std::pair<Parameter, std::string>> {
                if (has_state)
                {
                    auto param_res = Parameter::LogicVector(name, size, "");
                    if (param_res.is_error())
                    {
                        return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
                    }
                    return OK(std::make_pair(param_res.get(), value));
                }
                else
                {
                    auto param_res = Parameter::BitVector(name, size, "");
                    if (param_res.is_error())
                    {
                        return ERR_APPEND(param_res.get_error(), "could not parse parameter value '" + raw + "'" + loc_str);
                    }
                    return OK(std::make_pair(param_res.get(), value));
                }
            };
 
            // decimal needs a stoull to hex conversion; all other bases use digits directly
            if (bits_per_digit == 0)
            {
                u64 num = 0;
                try
                {
                    num = std::stoull(digits);
                }
                catch (...)
                {
                    return ERR("could not parse parameter value: decimal literal '" + raw + "' overflows" + loc_str);
                }
                std::stringstream ss;
                ss << std::hex << num;
                const std::string hex_digits = ss.str();
                const u16 size               = has_width ? explicit_width : static_cast<u16>(hex_digits.size() * 4);
                return make_param(size, out_prefix + hex_digits);
            }
            const u16 size = (has_width && !has_state) ? explicit_width : static_cast<u16>(digits.size() * bits_per_digit);
            return make_param(size, out_prefix + digits);
        }
 
        return ERR("could not parse parameter value: failed to identify data type of '" + raw + "'" + loc_str);
    }
 
    Result<std::vector<VerilogParser::assignment_t>> VerilogParser::parse_assignment_expression(TokenStream<std::string>&& stream) const
    {
        std::vector<TokenStream<std::string>> parts;
 
        if (stream.size() == 0)
        {
            return OK({});
        }
 
        if (stream.peek() == "{")
        {
            stream.consume("{", true);
 
            TokenStream<std::string> assignment_list_str = stream.extract_until("}");
            stream.consume("}", true);
 
            do
            {
                parts.push_back(assignment_list_str.extract_until(","));
            } while (assignment_list_str.consume(",", false));
        }
        else
        {
            parts.push_back(stream);
        }
 
        std::vector<assignment_t> result;
        result.reserve(parts.size());
 
        for (auto it = parts.rbegin(); it != parts.rend(); it++)
        {
            TokenStream<std::string>& part_stream = *it;
 
            const Token<std::string> signal_name_token = part_stream.consume();
            std::string signal_name                    = signal_name_token.string;
 
            // (3) NUMBER
            if (isdigit(signal_name[0]) || signal_name[0] == '\'')
            {
                if (auto res = get_binary_vector(signal_name_token); res.is_error())
                {
                    return ERR_APPEND(res.get_error(), "could not parse assignment expression: unable to convert token to binary vector");
                }
                else
                {
                    result.push_back(std::move(res.get()));
                }
            }
            else
            {
                // any bounds specified?
                if (part_stream.consume("["))
                {
                    // (4) NAME[INDEX1][INDEX2]...
                    // (5) NAME[BEGIN_INDEX1:END_INDEX1][BEGIN_INDEX2:END_INDEX2]...
 
                    std::vector<std::vector<u32>> ranges;
                    do
                    {
                        TokenStream<std::string> range_str = part_stream.extract_until("]");
                        ranges.emplace_back(parse_range(range_str));
                        part_stream.consume("]", true);
                    } while (part_stream.consume("[", false));
 
                    result.push_back(ranged_identifier_t({std::move(signal_name), std::move(ranges)}));
                }
                else
                {
                    // (1) NAME *single-dimensional*
                    // (2) NAME *multi-dimensional*
                    result.push_back(std::move(signal_name));
                }
            }
        }
 
        return OK(result);
    }
 
    std::vector<std::string> VerilogParser::expand_assignment_expression(VerilogModule* verilog_module, const std::vector<assignment_t>& vars) const
    {
        std::vector<std::string> result;
        for (const auto& var : vars)
        {
            if (const identifier_t* identifier = std::get_if<identifier_t>(&var); identifier != nullptr)
            {
                std::vector<std::vector<u32>> ranges;
 
                if (const auto signal_it = verilog_module->m_signals_by_name.find(*identifier); signal_it != verilog_module->m_signals_by_name.end())
                {
                    ranges = signal_it->second->m_ranges;
                }
                else if (const auto port_it = verilog_module->m_ports_by_expression.find(*identifier); port_it != verilog_module->m_ports_by_expression.end())
                {
                    ranges = port_it->second->m_ranges;
                }
 
                std::vector<std::string> expanded = expand_ranges(*identifier, ranges);
                result.insert(result.end(), expanded.begin(), expanded.end());
            }
            else if (const ranged_identifier_t* ranged_identifier = std::get_if<ranged_identifier_t>(&var); ranged_identifier != nullptr)
            {
                std::vector<std::string> expanded = expand_ranges(ranged_identifier->first, ranged_identifier->second);
                result.insert(result.end(), expanded.begin(), expanded.end());
            }
            else if (const numeral_t* numeral = std::get_if<numeral_t>(&var); numeral != nullptr)
            {
                for (auto value : *numeral)
                {
                    result.push_back("'" + BooleanFunction::to_string(value) + "'");
                }
            }
        }
 
        return result;
    }
}    // namespace hal