find-symbol

find-symbol Function

Syntax:

find-symbol string &optional package → symbol, status

Arguments and Values:

string—a string.

package—a package designator . The default is the current package.

symbol—a symbol accessible in the package, or nil.

status—one of :inherited, :external, :internal, or nil.

find-symbol

Description:

find-symbol locates a symbol whose name is string in a package. If a symbol named string is found in package, directly or by inheritance, the symbol found is returned as the first value; the second value is as follows:

:internal

If the symbol is present in package as an internal symbol.

:external

If the symbol is present in package as an external symbol.

:inherited

If the symbol is inherited by package through use-package, but is not present in package. If no such symbol is accessible in package, both values are nil.

Examples:

(find-symbol "NEVER-BEFORE-USED") → NIL, NIL 
(find-symbol "NEVER-BEFORE-USED") → NIL, NIL 
(intern "NEVER-BEFORE-USED") → NEVER-BEFORE-USED, NIL 
(intern "NEVER-BEFORE-USED") → NEVER-BEFORE-USED, :INTERNAL 
(find-symbol "NEVER-BEFORE-USED") → NEVER-BEFORE-USED, :INTERNAL 
(find-symbol "never-before-used") → NIL, NIL 
(find-symbol "CAR" ’common-lisp-user) → CAR, :INHERITED 
(find-symbol "CAR" ’common-lisp) → CAR, :EXTERNAL 
(find-symbol "NIL" ’common-lisp-user) → NIL, :INHERITED 
(find-symbol "NIL" ’common-lisp) → NIL, :EXTERNAL 
(find-symbol "NIL" (prog1 (make-package "JUST-TESTING" :use ’()) 
		     (intern "NIL" "JUST-TESTING"))) 
→ JUST-TESTING::NIL, :INTERNAL 
(export ’just-testing::nil ’just-testing) 
(find-symbol "NIL" ’just-testing) → JUST-TESTING:NIL, :EXTERNAL 
(find-symbol "NIL" "KEYWORD") 
→ NIL, NIL 
<i><sup>or</sup>→</i> :NIL, :EXTERNAL 
(find-symbol (symbol-name :nil) "KEYWORD") → :NIL, :EXTERNAL 

Affected By:

intern, import, export, use-package, unintern, unexport, unuse-package

See Also:

intern, find-all-symbols

Notes:

find-symbol is operationally equivalent to intern, except that it never creates a new symbol.

Expanded Reference: find-symbol

Basic Usage: Looking Up a Symbol by Name

find-symbol searches for a symbol by name in a package. Unlike intern, it never creates a new symbol.

(find-symbol "CAR" "COMMON-LISP")
=> CAR
=> :EXTERNAL

(find-symbol "CAR" "COMMON-LISP-USER")
=> CAR
=> :INHERITED

When No Symbol is Found

Both return values are NIL when the symbol does not exist.

(find-symbol "XYZZY-NONEXISTENT" "COMMON-LISP-USER")
=> NIL
=> NIL

Status Values Explained

The second value indicates the symbol's accessibility in the specified package.

;; :EXTERNAL - present and exported
(find-symbol "CONS" "COMMON-LISP")
=> CONS
=> :EXTERNAL

;; :INHERITED - accessible via use-package, not directly present
(find-symbol "CONS" "COMMON-LISP-USER")
=> CONS
=> :INHERITED

;; :INTERNAL - present but not exported
(make-package "FS-DEMO" :use '())
(intern "SECRET" "FS-DEMO")
(find-symbol "SECRET" "FS-DEMO")
;; => FS-DEMO::SECRET
;; => :INTERNAL

Case Sensitivity

find-symbol is case-sensitive. Standard CL symbols are uppercase.

(find-symbol "car" "COMMON-LISP")
=> NIL
=> NIL

(find-symbol "CAR" "COMMON-LISP")
=> CAR
=> :EXTERNAL

Finding NIL in Different Packages

The symbol NIL can be tricky because it is also the boolean false.

(find-symbol "NIL" "COMMON-LISP")
=> NIL
=> :EXTERNAL
;; The first value is the symbol NIL, the second is :EXTERNAL

(find-symbol "NIL" "COMMON-LISP-USER")
=> NIL
=> :INHERITED

Using find-symbol to Check Before Acting

find-symbol is useful when you want to check whether a symbol exists without creating one as a side effect.

(make-package "CHECK-FIRST" :use '())

;; Does "MAYBE" exist? No.
(find-symbol "MAYBE" "CHECK-FIRST")
=> NIL
=> NIL

;; Now create it with intern
(intern "MAYBE" "CHECK-FIRST")
;; => CHECK-FIRST::MAYBE
;; => NIL

;; Now find-symbol can find it
(find-symbol "MAYBE" "CHECK-FIRST")
;; => CHECK-FIRST::MAYBE
;; => :INTERNAL