887 |
;;; |
;;; |
888 |
;;; These are the low level data structures for modules. |
;;; These are the low level data structures for modules. |
889 |
;;; |
;;; |
890 |
|
;;; Every module object is of the type 'module-type', which is a record |
891 |
|
;;; consisting of the following members: |
892 |
|
;;; |
893 |
|
;;; - eval-closure: the function that defines for its module the strategy that |
894 |
|
;;; shall be followed when looking up symbols in the module. |
895 |
|
;;; |
896 |
|
;;; An eval-closure is a function taking two arguments: the symbol to be |
897 |
|
;;; looked up and a boolean value telling whether a binding for the symbol |
898 |
|
;;; should be created if it does not exist yet. If the symbol lookup |
899 |
|
;;; succeeded (either because an existing binding was found or because a new |
900 |
|
;;; binding was created), a variable object representing the binding is |
901 |
|
;;; returned. Otherwise, the value #f is returned. Note that the eval |
902 |
|
;;; closure does not take the module to be searched as an argument: During |
903 |
|
;;; construction of the eval-closure, the eval-closure has to store the |
904 |
|
;;; module it belongs to in its environment. This means, that any |
905 |
|
;;; eval-closure can belong to only one module. |
906 |
|
;;; |
907 |
|
;;; The eval-closure of a module can be defined arbitrarily. However, three |
908 |
|
;;; special cases of eval-closures are to be distinguished: During startup |
909 |
|
;;; the module system is not yet activated. In this phase, no modules are |
910 |
|
;;; defined and all bindings are automatically stored by the system in the |
911 |
|
;;; pre-modules-obarray. Since no eval-closures exist at this time, the |
912 |
|
;;; functions which require an eval-closure as their argument need to be |
913 |
|
;;; passed the value #f. |
914 |
|
;;; |
915 |
|
;;; The other two special cases of eval-closures are the |
916 |
|
;;; standard-eval-closure and the standard-interface-eval-closure. Both |
917 |
|
;;; behave equally for the case that no new binding is to be created. The |
918 |
|
;;; difference between the two comes in, when the boolean argument to the |
919 |
|
;;; eval-closure indicates that a new binding shall be created if it is not |
920 |
|
;;; found. |
921 |
|
;;; |
922 |
|
;;; Given that no new binding shall be created, both standard eval-closures |
923 |
|
;;; define the following standard strategy of searching bindings in the |
924 |
|
;;; module: First, the module's obarray is searched for the symbol. Second, |
925 |
|
;;; if no binding for the symbol was found in the module's obarray, the |
926 |
|
;;; module's binder procedure is exececuted. If this procedure did not |
927 |
|
;;; return a binding for the symbol, the modules referenced in the module's |
928 |
|
;;; uses list are recursively searched for a binding of the symbol. If the |
929 |
|
;;; binding can not be found in these modules also, the symbol lookup has |
930 |
|
;;; failed. |
931 |
|
;;; |
932 |
|
;;; If a new binding shall be created, the standard-interface-eval-closure |
933 |
|
;;; immediately returns indicating failure. That is, it does not even try |
934 |
|
;;; to look up the symbol. In contrast, the standard-eval-closure would |
935 |
|
;;; first search the obarray, and if no binding was found there, would |
936 |
|
;;; create a new binding in the obarray, therefore not calling the binder |
937 |
|
;;; procedure or searching the modules in the uses list. |
938 |
|
;;; |
939 |
|
;;; The explanation of the following members obarray, binder and uses |
940 |
|
;;; assumes that the symbol lookup follows the strategy that is defined in |
941 |
|
;;; the standard-eval-closure and the standard-interface-eval-closure. |
942 |
|
;;; |
943 |
|
;;; - obarray: a hash table that maps symbols to variable objects. In this |
944 |
|
;;; hash table, the definitions are found that are local to the module (that |
945 |
|
;;; is, not imported from other modules). When looking up bindings in the |
946 |
|
;;; module, this hash table is searched first. |
947 |
|
;;; |
948 |
|
;;; - binder: either #f or a function taking a module and a symbol argument. |
949 |
|
;;; If it is a function it is called after the obarray has been |
950 |
|
;;; unsuccessfully searched for a binding. It then can provide bindings |
951 |
|
;;; that would otherwise not be found locally in the module. |
952 |
|
;;; |
953 |
|
;;; - uses: a list of modules from which non-local bindings can be inherited. |
954 |
|
;;; These modules are the third place queried for bindings after the obarray |
955 |
|
;;; has been unsuccessfully searched and the binder function did not deliver |
956 |
|
;;; a result either. |
957 |
|
;;; |
958 |
|
;;; - transformer: either #f or a function taking a scheme expression as |
959 |
|
;;; delivered by read. If it is a function, it will be called to perform |
960 |
|
;;; syntax transformations (e. g. makro expansion) on the given scheme |
961 |
|
;;; expression. The output of the transformer function will then be passed |
962 |
|
;;; to Guile's internal memoizer. This means that the output must be valid |
963 |
|
;;; scheme code. The only exception is, that the output may make use of the |
964 |
|
;;; syntax extensions provided to identify the modules that a binding |
965 |
|
;;; belongs to. |
966 |
|
;;; |
967 |
|
;;; - name: the name of the module. This is used for all kinds of printing |
968 |
|
;;; outputs. In certain places the module name also serves as a way of |
969 |
|
;;; identification. When adding a module to the uses list of another |
970 |
|
;;; module, it is made sure that the new uses list will not contain two |
971 |
|
;;; modules of the same name. |
972 |
|
;;; |
973 |
|
;;; - kind: classification of the kind of module. The value is (currently?) |
974 |
|
;;; only used for printing. It has no influence on how a module is treated. |
975 |
|
;;; Currently the following values are used when setting the module kind: |
976 |
|
;;; 'module, 'directory, 'interface, 'custom-interface. If no explicit kind |
977 |
|
;;; is set, it defaults to 'module. |
978 |
|
;;; |
979 |
|
;;; - duplicates-handlers |
980 |
|
;;; |
981 |
|
;;; - duplicates-interface |
982 |
|
;;; |
983 |
|
;;; - observers |
984 |
|
;;; |
985 |
|
;;; - weak-observers |
986 |
|
;;; |
987 |
|
;;; - observer-id |
988 |
|
;;; |
989 |
|
;;; In addition, the module may (must?) contain a binding for |
990 |
|
;;; %module-public-interface... More explanations here... |
991 |
|
;;; |
992 |
;;; !!! warning: The interface to lazy binder procedures is going |
;;; !!! warning: The interface to lazy binder procedures is going |
993 |
;;; to be changed in an incompatible way to permit all the basic |
;;; to be changed in an incompatible way to permit all the basic |
994 |
;;; module ops to be virtualized. |
;;; module ops to be virtualized. |