Changes between Version 5 and Version 6 of InterfaceLayers

Timestamp:

Mar 19, 2012, 11:02:56 PM (13 years ago)

Author:

manualwiki

Comment:

InterfaceLayers page improved

InterfaceLayers

@@ -1 +1 @@
 = Interface layers =
 
-Interface layers and additional relations can be defined and afterwards it can be checked whether in this architecture there are function calls, that insult the layer hierarchy or not.
+In large program systems, groups of compilation units (in the case of Erlang, modules) usually form logical layers. A desired property of such systems is that code in one layer should only use the layer immediately below it, and conversely, provide functionality only for the layer immediately above it. This page shows how you can define such layers and find functions that access layers that they are not supposed to.
 
-== Define interface layers ==
+== Defining interface layers ==
 
-We can define the hierarchy of the interface layers with a list. The first element of the list is at the bottom of the layer hierarchy and the last element of the list is at the top of it. This means, that '''by default every layer can call functions from its own layer and the layer immediately below'''. The list contains tuples. Every tuple defines an interface layer: the first element of the tuple is a label with the name of the layer; the second element is a list, that contains the modules, which from the layer is built. There are four ways to specify this list with:
+We use a list to represent the hierarchy of the interface layers, starting with the lowest layer. Layers are described with tuples {{{{Name, ModSpecs} :: {atom(), [modspec()]}}}}, where {{{Name}}} is the name of the layer, and {{{ModSpecs}}} is a list that can contain any of the following.
 
-* name of the modules: {{{[{il1,[one1,one2]},{il2,[two1]}]}}}, 
-* module nodes: {{{[{il1,[{'gn',module,2},{'gn',module,4}]},{il2,[{'gn',module,6}]}]}}}, 
-* list of regexps: {{{[{il1,["^(/home/user)/[a-zA-Z0-9_/]+(/layer1)$"]},{il2,["(/layer2)$","^(/home/user/layer2/src)$"]}]}}}, 
-* file, that contain regexps: {{{[{il1,["layer1"]}, {il2,["layer2"]}]}}}. In this example ''layer1'' and ''layer2'' are files, which contain regexps.
-
-We can mix the ways of specifications.
+||Erlang term||Description||Example||Example description||
+||{{{atom()}}}||the name of a loaded module||{{{one1}}}||the module {{{one1}}}||
+||{'gn',module,!ModIdx}||the identifier of a module node||{'gn',module,2}||module !#2 in the graph representation||
+||{{{string()}}} containing a regexp||a regular expression for module names||{{{"^(/home/user)/[a-zA-Z0-9_/]+(/layer1)$"}}}||files from a layer1 directory under /home/user||
+||{{{string()}}}||name of a file that contains regexps||{{{"layer1_regexps.txt"}}}||regexps inside layer1_regexps.txt||
 
 == Define additional relations ==
 
-Between two layers we can define a relation, which allows function calls from the first to the second layer. The definition of these additional relations available with a list, that contains this pairs in tuples. We can refer to interface layers with their names. Suppose, that we want to allow function calls from ''il1'' to ''il2'' as well as from ''il2'' to ''il4'' layer: {{{[{il1,il2},{il2,il4}]}}}.
+Sometimes, it is desirable to allow calls between layers that do not conform to the above. For that purpose, we use a list of {{{{AllowFrom, AllowTo} :: {atom(), atom()}}}} pairs, where {{{AllowFrom}}} and {{{AllowTo}}} are layer names.
+
+== Interface functions ==
+
+We currently have two interface functions in the {{{ri}}} module: {{{check_layered_arch/2}}} and {{{show_layered_arch/2}}}. Both take two parameters, {{{{Name, ModSpecs}}}} and {{{{AllowFrom, AllowTo}}}} as described above. The function {{{ri:check_layered_arch/2}}} outputs the functions that violate the layer access restrictions, while {{{ri:show_layered_arch/2}}} visualises the layers in a graph with the layer violations highlighted.
 
 == Examples ==
+
 {{{
-ri:check_layered_arch([ {il1,["^(/home/user/layers/layer1)$"]},
-{il2,["^(/home/user/layers/layer2)$"]}, {il3,["regexp3"]}],[]).
+ri:check_layered_arch(
+    [ {il1,["^(/home/user/layers/layer1)$"]},
+      {il2,["^(/home/user/layers/layer2)$"]},
+      {il3,["regexp3"]}],
+    []).
 }}}
+
 {{{
-ri:show_layered_arch([ {il1,["^(/home/user/layers/layer1)$"]},
-{il2,["^(/home/user/layers/layer2)$"]}, {il3,["regexp3"]}],[]).
+ri:show_layered_arch(
+    [ {il1,["^(/home/user/layers/layer1)$"]},
+      {il2,["^(/home/user/layers/layer2)$"]},
+      {il3,["regexp3"]}],
+    []).
 }}}
+
 {{{
-ri:show_layered_arch([ {il1,["^(/home/user/layers/layer1)$"]},
-{il2,["^(/home/user/layers/layer2)$"]}, {il3,["regexp3"]}],
-[{il1,il3}]).
+ri:show_layered_arch(
+    [ {il1,["^(/home/user/layers/layer1)$"]},
+      {il2,["^(/home/user/layers/layer2)$"]},
+      {il3,["regexp3"]}],
+    [{il1,il3}]).
 }}}