microcad_lang/resolve/symbol/
mod.rs

1// Copyright © 2025 The µcad authors <info@ucad.xyz>
2// SPDX-License-Identifier: AGPL-3.0-or-later
3
4mod symbol_definition;
5mod symbol_inner;
6mod symbol_map;
7mod symbols;
8
9pub use symbol_definition::*;
10pub(crate) use symbol_map::*;
11pub(crate) use symbols::*;
12
13use symbol_inner::*;
14
15use crate::{builtin::*, rc::*, resolve::*, src_ref::*, syntax::*, ty::*, value::*};
16
17/// Symbol
18///
19/// Every `Symbol` has a [`SymbolDefinition`], a *parent* and *children*.
20/// So `Symbol` is meant as a tree which is used by [`SymbolTable`] to store
21/// the resolved symbols by it's original structure in the source code and by it's *id*.
22///
23/// `Symbol` can be shared as mutable.
24#[derive(Clone)]
25pub struct Symbol {
26    visibility: std::cell::Cell<Visibility>,
27    inner: RcMut<SymbolInner>,
28}
29
30// creation
31impl Symbol {
32    /// Create new symbol without children.
33    /// # Arguments
34    /// - `visibility`: Visibility of the symbol
35    /// - `def`: Symbol definition
36    /// - `parent`: Symbol's parent symbol or none for root
37    pub fn new(def: SymbolDefinition, parent: Option<Symbol>) -> Self {
38        Symbol {
39            visibility: std::cell::Cell::new(def.visibility()),
40            inner: RcMut::new(SymbolInner {
41                def,
42                parent,
43                ..Default::default()
44            }),
45        }
46    }
47
48    /// Create new symbol without children.
49    /// # Arguments
50    /// - `visibility`: Visibility of the symbol
51    /// - `def`: Symbol definition
52    /// - `parent`: Symbol's parent symbol or none for root
53    pub(super) fn new_with_visibility(
54        visibility: Visibility,
55        def: SymbolDefinition,
56        parent: Option<Symbol>,
57    ) -> Self {
58        Symbol {
59            visibility: std::cell::Cell::new(visibility),
60            inner: RcMut::new(SymbolInner {
61                def,
62                parent,
63                ..Default::default()
64            }),
65        }
66    }
67
68    /// Create a symbol node for a built-in.
69    /// # Arguments
70    /// - `id`: Name of the symbol
71    /// - `parameters`: Optional parameter list
72    /// - `f`: The builtin function
73    pub fn new_builtin(
74        id: Identifier,
75        parameters: Option<ParameterValueList>,
76        f: &'static BuiltinFn,
77    ) -> Symbol {
78        Symbol::new(
79            SymbolDefinition::Builtin(Rc::new(Builtin { id, parameters, f })),
80            None,
81        )
82    }
83}
84
85// tree structure
86impl Symbol {
87    /// Get any child with the given `id`.
88    /// # Arguments
89    /// - `id`: Anticipated *id* of the possible child.
90    fn get_child(&self, id: &Identifier) -> Option<Symbol> {
91        self.inner.borrow().children.get(id).cloned()
92    }
93
94    /// Insert child and change parent of child to new parent.
95    /// # Arguments
96    /// - `parent`: New parent symbol (will be changed in child!).
97    /// - `child`: Child to insert
98    pub(crate) fn add_child(parent: &Symbol, child: Symbol) {
99        child.inner.borrow_mut().parent = Some(parent.clone());
100        let id = child.id();
101        parent.inner.borrow_mut().children.insert(id, child);
102    }
103
104    /// Insert new child
105    ///
106    /// The parent of `new_child` wont be changed!
107    pub(crate) fn insert_child(&self, id: Identifier, new_child: Symbol) {
108        if self
109            .inner
110            .borrow_mut()
111            .children
112            .insert(id, new_child)
113            .is_some()
114        {
115            todo!("symbol already existing");
116        }
117    }
118
119    /// Initially set children.
120    ///
121    /// Panics if children already exist.
122    pub(super) fn set_children(&self, new_children: SymbolMap) {
123        assert!(self.inner.borrow().children.is_empty());
124        self.inner.borrow_mut().children = new_children;
125    }
126
127    pub(crate) fn with_children<E: std::error::Error>(
128        &self,
129        f: impl FnMut((&Identifier, &Symbol)) -> Result<(), E>,
130    ) -> Result<(), E> {
131        self.inner.borrow().children.iter().try_for_each(f)
132    }
133
134    /// Create a vector of cloned children.
135    fn public_children(&self, visibility: Visibility) -> SymbolMap {
136        let inner = self.inner.borrow();
137
138        inner
139            .children
140            .values()
141            .filter(|symbol| {
142                if symbol.is_public() {
143                    true
144                } else {
145                    log::trace!("Skipping private symbol:\n{symbol:?}");
146                    false
147                }
148            })
149            .map(|symbol| symbol.clone_with_visibility(visibility))
150            .map(|symbol| (symbol.id(), symbol))
151            .collect()
152    }
153
154    /// True if symbol has any children
155    pub(crate) fn is_empty(&self) -> bool {
156        self.inner.borrow().children.is_empty()
157    }
158
159    /// Get parent symbol.
160    pub(crate) fn get_parent(&self) -> Option<Symbol> {
161        self.inner.borrow().parent.clone()
162    }
163
164    /// Set new parent.
165    pub(super) fn set_parent(&mut self, parent: Symbol) {
166        self.inner.borrow_mut().parent = Some(parent);
167    }
168}
169
170// visibility
171impl Symbol {
172    /// Return `true` if symbol's visibility is private
173    fn visibility(&self) -> Visibility {
174        self.visibility.get()
175    }
176
177    /// Set symbol's visibility.
178    pub(crate) fn set_visibility(&mut self, visibility: Visibility) {
179        self.visibility.set(visibility)
180    }
181
182    /// Return `true` if symbol's visibility set to is public.
183    fn is_public(&self) -> bool {
184        matches!(self.visibility(), Visibility::Public)
185    }
186
187    pub(super) fn is_deleted(&self) -> bool {
188        self.visibility.get() == Visibility::Deleted
189    }
190
191    /// Clone this symbol but give the clone another visibility.
192    pub(crate) fn clone_with_visibility(&self, visibility: Visibility) -> Self {
193        let cloned = self.clone();
194        cloned.visibility.set(visibility);
195        cloned
196    }
197}
198
199// definition dependent
200impl Symbol {
201    /// Return the internal *id* of this symbol.
202    pub(crate) fn id(&self) -> Identifier {
203        self.inner.borrow().def.id()
204    }
205
206    /// check if a private symbol may be declared within this symbol
207    pub(super) fn can_const(&self) -> bool {
208        matches!(
209            self.inner.borrow().def,
210            SymbolDefinition::Module(..) | SymbolDefinition::SourceFile(..)
211        )
212    }
213
214    /// check if a value on the stack may be declared within this symbol
215    pub(super) fn can_value(&self) -> bool {
216        matches!(
217            self.inner.borrow().def,
218            SymbolDefinition::Function(..)
219                | SymbolDefinition::Workbench(..)
220                | SymbolDefinition::SourceFile(..)
221        )
222    }
223
224    /// check if a property may be declared within this symbol
225    pub(super) fn can_prop(&self) -> bool {
226        matches!(self.inner.borrow().def, SymbolDefinition::Workbench(..))
227    }
228
229    pub(crate) fn is_module(&self) -> bool {
230        matches!(
231            self.inner.borrow().def,
232            SymbolDefinition::SourceFile(..) | SymbolDefinition::Module(..)
233        )
234    }
235
236    pub(crate) fn is_workbench(&self) -> bool {
237        matches!(self.inner.borrow().def, SymbolDefinition::Workbench(..))
238    }
239
240    /// Overwrite any value in this symbol
241    pub(crate) fn set_value(&self, new_value: Value) -> ResolveResult<()> {
242        let is_a_value = match &mut self.inner.borrow_mut().def {
243            SymbolDefinition::Constant(.., value) => {
244                *value = new_value;
245                true
246            }
247            _ => false,
248        };
249        match is_a_value {
250            true => Ok(()),
251            false => Err(ResolveError::NotAValue(self.full_name())),
252        }
253    }
254
255    /// Return file path of top level parent source file.
256    pub(super) fn source_path(&self) -> Option<std::path::PathBuf> {
257        if let SymbolDefinition::SourceFile(source_file) = &self.inner.borrow().def {
258            return source_file
259                .filename()
260                .parent()
261                .map(|path| path.to_path_buf());
262        }
263        self.get_parent().and_then(|parent| parent.source_path())
264    }
265
266    pub(super) fn is_resolvable(&self) -> bool {
267        matches!(
268            self.inner.borrow().def,
269            SymbolDefinition::SourceFile(..)
270                | SymbolDefinition::Module(..)
271                | SymbolDefinition::UseAll(..)
272                | SymbolDefinition::Alias(..)
273        ) && !self.is_deleted()
274    }
275
276    pub(super) fn is_link(&self) -> bool {
277        matches!(
278            self.inner.borrow().def,
279            SymbolDefinition::UseAll(..) | SymbolDefinition::Alias(..)
280        )
281    }
282
283    pub(super) fn is_alias(&self) -> bool {
284        matches!(self.inner.borrow().def, SymbolDefinition::Alias(..))
285    }
286
287    pub(super) fn has_links(&self) -> bool {
288        if self.is_link() {
289            true
290        } else {
291            self.inner
292                .borrow()
293                .children
294                .values()
295                .any(|symbol| symbol.has_links())
296        }
297    }
298
299    /// Work with the symbol definition.
300    pub(crate) fn with_def<T>(&self, mut f: impl FnMut(&SymbolDefinition) -> T) -> T {
301        f(&self.inner.borrow().def)
302    }
303
304    /// Work with the mutable symbol definition.
305    pub(crate) fn with_def_mut<T>(&self, mut f: impl FnMut(&mut SymbolDefinition) -> T) -> T {
306        f(&mut self.inner.borrow_mut().def)
307    }
308}
309
310// check
311impl Symbol {
312    /// Mark this symbol as *checked*.
313    pub(super) fn set_check(&self) {
314        let _ = self.inner.borrow().checked.set(());
315    }
316
317    fn is_checked(&self) -> bool {
318        self.inner.borrow().checked.get().is_some()
319    }
320
321    pub(super) fn unchecked(&self, unchecked: &mut Symbols) {
322        let inner = self.inner.borrow();
323        if inner.checked.get().is_none() {
324            unchecked.push(self.clone())
325        }
326        inner
327            .children
328            .iter()
329            .for_each(|(_, child)| child.unchecked(unchecked));
330    }
331
332    /// check names in symbol definition
333    pub(super) fn check(
334        &self,
335        context: &mut ResolveContext,
336        exclude_ids: &IdentifierSet,
337    ) -> ResolveResult<()> {
338        if !matches!(self.visibility.get(), Visibility::Deleted) {
339            let names = match &self.inner.borrow().def {
340                SymbolDefinition::SourceFile(sf) => sf.names(),
341                SymbolDefinition::Module(m) => m.names(),
342                SymbolDefinition::Workbench(wb) => wb.names(),
343                SymbolDefinition::Function(f) => f.names(),
344                SymbolDefinition::Alias(..) | SymbolDefinition::UseAll(..) => {
345                    log::error!("Resolve Context:\n{context:?}");
346                    return Err(ResolveError::ResolveCheckFailed);
347                }
348                _ => Default::default(),
349            };
350
351            let prefix = self.module_name().clone();
352
353            if !names.is_empty() {
354                log::debug!("checking symbols: {names}");
355
356                names
357                    .iter()
358                    .filter(|name| {
359                        exclude_ids.contains(name.last().expect("symbol with empty name"))
360                    })
361                    .try_for_each(|name| match context.symbol_table.lookup(name) {
362                        Ok(_) => Ok::<_, ResolveError>(()),
363                        Err(err) => {
364                            if context
365                                .symbol_table
366                                .lookup(&name.with_prefix(&prefix))
367                                .is_err()
368                            {
369                                context.error(name, err)?;
370                            }
371                            Ok(())
372                        }
373                    })?;
374            }
375
376            // check children
377            let children = self.inner.borrow().children.clone();
378            children
379                .values()
380                .try_for_each(|symbol| symbol.check(context, exclude_ids))
381        } else {
382            Ok(())
383        }
384    }
385
386    fn module_name(&self) -> QualifiedName {
387        match self.is_module() {
388            true => {
389                if let Some(parent) = &self.get_parent() {
390                    parent.module_name().with_suffix(&self.id())
391                } else {
392                    QualifiedName::from_id(self.id())
393                }
394            }
395            false => {
396                if let Some(parent) = &self.get_parent() {
397                    parent.module_name()
398                } else {
399                    unreachable!("root must be source file")
400                }
401            }
402        }
403    }
404
405    pub(crate) fn kind(&self) -> String {
406        self.inner.borrow().def.kind()
407    }
408}
409
410impl Symbol {
411    /// Mark this symbol as *used*.
412    pub(crate) fn set_used(&self) {
413        let _ = self.inner.borrow().used.set(());
414    }
415
416    pub(super) fn unused(&self, unused: &mut Symbols) {
417        let inner = self.inner.borrow();
418        if inner.used.get().is_none() {
419            unused.push(self.clone())
420        }
421
422        inner
423            .children
424            .iter()
425            .for_each(|(_, child)| child.unused(unused));
426    }
427
428    /// Resolve aliases and use statements in this symbol.
429    pub(super) fn resolve(&self, context: &mut ResolveContext) -> ResolveResult<SymbolMap> {
430        log::trace!("resolving: {self}");
431
432        // retrieve symbols from any use statements
433        let mut from_self = {
434            let inner = self.inner.borrow();
435            match &inner.def {
436                SymbolDefinition::Alias(visibility, id, name) => {
437                    log::trace!("resolving use (as): {self} => {visibility}{id} ({name})");
438                    let symbol = context
439                        .symbol_table
440                        .lookup_within_opt(name, &inner.parent)?
441                        .clone_with_visibility(*visibility);
442                    self.visibility.set(Visibility::Deleted);
443                    [(id.clone(), symbol)].into_iter().collect()
444                }
445                SymbolDefinition::UseAll(visibility, name) => {
446                    log::trace!("resolving use all: {self} => {visibility}{name}");
447                    let symbols = context
448                        .symbol_table
449                        .lookup_within_opt(name, &inner.parent)?
450                        .public_children(*visibility);
451                    if !symbols.is_empty() {
452                        self.visibility.set(Visibility::Deleted);
453                    }
454                    symbols
455                }
456                // skip others
457                _ => SymbolMap::default(),
458            }
459        };
460
461        let resolved = from_self.resolve_all(context)?;
462        from_self.extend(resolved.iter().map(|(k, v)| (k.clone(), v.clone())));
463        // collect symbols resolved from children
464        let from_children = self.inner.borrow().children.resolve_all(context)?;
465        self.inner
466            .borrow_mut()
467            .children
468            .extend(from_children.iter().map(|(k, v)| (k.clone(), v.clone())));
469        // return symbols collected from self
470        Ok(from_self)
471    }
472
473    /// Returns `true` if builtin symbol uses parameter of type Name
474    ///
475    /// (for assert_valid() and assert_invalid())
476    pub(crate) fn is_target_mode(&self) -> bool {
477        self.with_def(|def| match def {
478            SymbolDefinition::Builtin(builtin) => {
479                if let Some(parameters) = &builtin.parameters {
480                    parameters.values().any(|param| param.ty() == Type::Target)
481                } else {
482                    false
483                }
484            }
485            _ => false,
486        })
487    }
488
489    pub(super) fn search_target_mode_ids(&self, ids: &mut IdentifierSet) -> ResolveResult<()> {
490        if self.is_target_mode() {
491            ids.insert(self.id());
492        }
493        self.with_children(|(_, child)| child.search_target_mode_ids(ids))
494    }
495
496    /// Search down the symbol tree for a qualified name.
497    /// # Arguments
498    /// - `name`: Name to search for.
499    pub(crate) fn search(&self, name: &QualifiedName, respect: bool) -> ResolveResult<Symbol> {
500        log::trace!("Searching {name} in {:?}", self.full_name());
501        if let Some(id) = name.first() {
502            if id.is_super() {
503                if let Some(parent) = self.get_parent() {
504                    return parent.search(&name[1..].iter().cloned().collect(), respect);
505                }
506            }
507        }
508        self.search_inner(name, true, respect)
509    }
510
511    fn search_inner(
512        &self,
513        name: &QualifiedName,
514        top_level: bool,
515        respect: bool,
516    ) -> ResolveResult<Symbol> {
517        if let Some(first) = name.first() {
518            if let Some(child) = self.get_child(first) {
519                if respect && !top_level && !child.is_public() {
520                    log::trace!("Symbol {:?} is private", child.full_name());
521                    Err(ResolveError::SymbolIsPrivate(child.full_name().clone()))
522                } else if name.is_single_identifier() && !child.is_deleted() {
523                    log::trace!("Found {name:?} in {:?}", self.full_name());
524                    Ok(child.clone())
525                } else {
526                    let name = &name.remove_first();
527                    child.search_inner(name, false, respect)
528                }
529            } else {
530                log::trace!("No child in {:?} while searching for {name:?}", self.id());
531                Err(ResolveError::SymbolNotFound(name.clone()))
532            }
533        } else {
534            log::warn!("Cannot search for an anonymous name");
535            Err(ResolveError::SymbolNotFound(name.clone()))
536        }
537    }
538
539    /// Print out symbols from that point.
540    /// # Arguments
541    /// - `f`: Output formatter
542    /// - `id`: Overwrite symbol's internal `id` with this one if given (e.g. when using in a map).
543    /// - `depth`: Indention depth to use
544    pub(super) fn print_symbol(
545        &self,
546        f: &mut impl std::fmt::Write,
547        id: Option<&Identifier>,
548        depth: usize,
549        debug: bool,
550        children: bool,
551    ) -> std::fmt::Result {
552        let self_id = &self.id();
553        let id = id.unwrap_or(self_id);
554        let def = &self.inner.borrow().def;
555        let full_name = self.full_name();
556        let visibility = self.visibility();
557        if debug && cfg!(feature = "ansi-color") && self.inner.borrow().used.get().is_none() {
558            let checked = if self.is_checked() { " ✓" } else { "" };
559            color_print::cwrite!(
560                f,
561                "{:depth$}<#606060>{visibility:?}{id:?} {def:?} [{full_name:?}]</>{checked}",
562                "",
563            )?;
564        } else {
565            write!(f, "{:depth$}{id} {def} [{full_name}]", "",)?;
566        }
567        if children {
568            writeln!(f)?;
569            let indent = 4;
570
571            self.with_children(|(id, child)| {
572                child.print_symbol(f, Some(id), depth + indent, debug, true)
573            })?;
574        }
575        Ok(())
576    }
577}
578
579impl FullyQualify for Symbol {
580    /// Get fully qualified name.
581    fn full_name(&self) -> QualifiedName {
582        let id = self.id();
583        match &self.get_parent() {
584            Some(parent) => {
585                let mut name = parent.full_name();
586                name.push(id);
587                name
588            }
589
590            None => {
591                let src_ref = id.src_ref();
592                QualifiedName::new(vec![id], src_ref)
593            }
594        }
595    }
596}
597
598impl Default for Symbol {
599    fn default() -> Self {
600        Self {
601            visibility: std::cell::Cell::new(Visibility::default()),
602            inner: RcMut::new(Default::default()),
603        }
604    }
605}
606
607impl PartialEq for Symbol {
608    fn eq(&self, other: &Self) -> bool {
609        // just compare the pointers - not the content
610        self.inner.as_ptr() == other.inner.as_ptr()
611    }
612}
613
614impl std::fmt::Display for Symbol {
615    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
616        self.print_symbol(f, None, 0, false, false)
617    }
618}
619
620impl std::fmt::Debug for Symbol {
621    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
622        self.print_symbol(f, None, 0, true, false)
623    }
624}
625
626#[test]
627fn test_symbol_resolve() {
628    let root = SourceFile::load_from_str(
629        "root",
630        "
631        use my; 
632        x = my::target;
633
634        use my::target; 
635        x = target;
636        ",
637    )
638    .expect("parse error");
639
640    let my = SourceFile::load_from_str(
641        "my",
642        "
643        pub const target = 1;
644        ",
645    )
646    .expect("parse error");
647
648    let mut context =
649        ResolveContext::test_create(root, ResolveMode::Symbolized).expect("resolve error");
650    context.test_add_file(my);
651    log::trace!("{context:?}");
652    context.resolve().expect("resolve error");
653}
microcad_lang/resolve/symbol/mod.rs

microcad_lang/resolve/symbol/
mod.rs
