**//Package and symbol operations//**

Functions that deal with symbols alone or in the context of packages. Here we just describe the functions in terms of input and output. Further explanation will be in different section.

''SYMBOL-VALUE'' and ''SYMBOL-FUNCTION''

Return the symbol's value resp. function object bound in global context. Both accept one argument that must be symbol.

<code lisp>
>(symbol-value 'pi)       ; PI is global variable
3.14159

>(symbol-function 'cons)  ; CONS is standard function
#<function CONS>
</code>

''SYMBOL-NAME''

Expects one argument that must be symbol. Returns the symbol's name as string.

<code lisp>
>(symbol-name 'pi)       ; PI is global variable
"PI"
</code>

''FIND-SYMBOL''

Finds symbol by name in a package. Expects one string argument - the symbol name - and optional argument which is a package designator. Package designator can be string or symbol or package object itself. If the package name is not supplied, dynamic current package is used. Returns the symbol if it is found, otherwise ''NIL''. If it is found, also prints the symbol's relation to the package. As in Common LISP, this function returns two values, the second is a keyword which characterizes the relation.

<code lisp>
>(find-symbol "PI")            ; USER package will be searched
PI
:INHERITED                     ; it is inherited from base package LABLISP

>(find-symbol "PI" "LABLISP")  ; now we search in LABLISP package
PI
:EXTERNAL                      ; there the symbol is external
</code>

It is prefered to call the packages by string names, when we explicitly know it. It is also possible to use a symbol, with the name same as the name of the package. But it is important to know that the package is not bound to the symbol.

<code lisp>
(find-symbol "PI" 'user)      ; USER package will be searched as above
:INHERITED
</code>

The name of the symbol ''USER'' names existing package, but as a byproduct, we created a new symbol ''USER'' and interned it in "USER" package. Using symbols as package designators might lead to confussion as to where the symbol is actually interned (see below ''INTERN'') 

<code lisp>
(find-symbol "PI" *PACKAGE*)  ; *PACKAGE* is global variable 
:INHERITED
</code>

Here the symbol ''*PACKAGE*'' is evaluated to the dynamic current package. So the last example is identical to call the function without the optional package argument. 
  
''MAKE-SYMBOL''

Creates new symbol with given name, outside of any package (homeless). Expects one string argument.

<code lisp>
>(make-symbol "BLA")       
#:BLA                      ; the prefix means that the symbol is homeless 
</code>

The example above creates the symbol, it is returned, but then it is discrded, because it has no owner and no binding.

''INTERN''

Like ''FIND-SYMBOL'', looks up symbol by name in a package, and returns it the same way as ''FIND-SYMBOL''. But  when it is not present, it makes a new symbol with the package as owner. Expects one string argument - the symbol name - and optional argument which is a package designator. Returns two values, like ''FIND-SYMBOL''.

<code lisp>
>(intern "BLA")       ; without the package designator give, will use USER package
BLA
NIL                   ; NIL means that it is a new symbol

>(intern "BLA")       ; we can call it again, for USER package
BLA
:INTERNAL             ; now it is already present as internal symbol
</code>

''SYMBOL-PACKAGE''

Expects single argument that must be symbol. Returns the symbol's home package - the package where the symbol was interned.

<code lisp>
>(symbol-package 'pi)
#<The LABLISP package>
</code>

''PACKAGE-NAME''

Expects single argument that must be package object. Returns the name as string.

<code lisp>
>(package-name *package*)
"USER"
</code>

''FIND-PACKAGE''

Expects one argument that must be package designator. Package designator can be string or symbol or package object itself. Returns the package object, if it exists.

<code lisp>
>(find-package "USER")
#<The USER package>
</code>

''MAKE-PACKAGE''

Expects single argument that must be string. Creates and returns new package with that name, unless it already exists - in that case complains and returns ''NIL''. New package always uses the LabLisp base package ''LABLISP'', see below: ''USE-PACKAGE''.

<code lisp>
>(make-package "P1")
#<The P1 package>
</code>

''IN-PACKAGE''

Expects single argument that must be string. Switches the current package (dynamic variable ''*PACKAGE*'') to the package named by the string - if it exists - and returns the package.

<code lisp>
>(in-package "P1")    ; assuming we made the P1 package in previous example
#<The P1 package>
</code>

''USE-PACKAGE''

''UNUSE-PACKAGE''

''IMPORT''

''EXPORT''

''UNINTERN''

''UNEXPORT''

''LIST-ALL-PACKAGES''

''PACKAGE-USE-LIST''

''PACKAGE-USED-BY-LIST''

''PACKAGE-INTERNAL-SYMBOLS''

''PACKAGE-EXTERNAL-SYMBOLS''