examples/features/needs.blank

   1 /** This file is part of Shapes.
   2  **
   3  ** Shapes is free software: you can redistribute it and/or modify
   4  ** it under the terms of the GNU General Public License as published by
   5  ** the Free Software Foundation, either version 3 of the License, or
   6  ** any later version.
   7  **
   8  ** Shapes is distributed in the hope that it will be useful,
   9  ** but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  ** GNU General Public License for more details.
  12  **
  13  ** You should have received a copy of the GNU General Public License
  14  ** along with Shapes.  If not, see <http://www.gnu.org/licenses/>.
  15  **
  16  ** Copyright 2014 Henrik Tidefelt
  17  **/
  18
  19 /** This example is about how to organize extensions in view of the new namespace
  20  ** capabilities.
  21  **/
  22
  23 /** Different forms of ##needs:
  24  **
  25  ** 1) ##needs file-basename.shext
  26  **    This is the original form of ##needs, which simply locates file-basename.shext and loads it if it hasn't already been loaded in the same namespace.
  27  **
  28  ** 2) ##needs ..A..B..C
  29  **    This is a new form of ##needs, which is more oriented towards namespace based organization of extensions.  This locates A/B/C/Contents.shext on the search
  30  **    path, and Contents.shext will be evaluated in the namespace ..A..B..C .  The Contents.shext file should only contain ##need directives to load the
  31  **    files that define the entire content of the ..A..B..C namespace.
  32  **    It might be a good idea to evaluate Contents.shext.shext in a namespace encapsulation, but it is not obvious that it would be necessary.
  33  **    This extension should also be the only extension that puts bindings in ..A..B..C, so that loading this extension can never impose restrictions on
  34  **    what other extensions that may be loaded.
  35  **
  36  ** 3) ##needs ..A..B..C / file.shext
  37  **    Locates A/B/C/file.shext on the search path, and file.shext will be evaluated in the namespace ..A..B..C .  The file file.shext
  38  **    is not expected to define the entire content of the namespace, so this form is useful when loading the entire namespace would be excessive.
  39  **    Note that file.shext shall be loaded by A/B/C/Contents.shext, and that it would be reasonable to treat as an error if the namespace ..A..B..C has
  40  **    been loaded via the Contents.shext, but now it turns out that A/B/C/file.shext wasn't part of it.
  41  **
  42  ** 4) ##needs D..E
  43  **    ##needs D..E / file.shext
  44  **    Similar to cases 2 and 3, but D..E is relative to the current namespace, so if the current namespace is ..A..B, this is equivalent to
  45  **      ##needs ..A..B..D..E
  46  **      ##needs ..A..B..D..E / file.shext
  47  **    A special case is the empty relative path
  48  **      ##needs / file.shext
  49  **    which loads file.shext in the current namespace.  This form should be used in a Contents.shext to load the actual content of a namespace.
  50  **/
  51
  52 /** Since a file can be loaded both as part of a namespace, via Contents.shext, and as a separate file, it must be ensured that the namespace
  53  ** encapsulation is the same in both cases.  That is, it won't work to let Contents.shext introduce the namespace encapsulation, since this
  54  ** encapsulation would not be present when the file is loaded separately.
  55  ** One way to fix this would be to always load files through the Contents.shext.  That is,
  56  **   ##needs ..A..B..C / file.shext
  57  ** would not load file.shext directly, but rather read Contents.shext somehow that only takes out the file.shext part therein.  To support this
  58  ** idea, it would be nice if Content.shext was in a more specific format than a generic Shapex extension.  By only allowing ##needs and namespace
  59  ** encapsulation, this would be a simple matter of ignoring all ##needs except that for file.shext, and treat as an error if there was no
  60  **   ##needs / file.shext
  61  ** to be found.
  62  **
  63  ** However, the namespace encapsulation could also be introduced higher up in the namespace hierarchy, so one will have to scan every Contents.shext on
  64  ** the way down:
  65  **   A/Contents.shext
  66  **   A/B/Contents.shext
  67  **   A/B/C/Contents.shext
  68  ** That is, in A/Contents.shext, one would process any namespace encapsulation, and
  69  **   ##needs B
  70  ** and in B/Contents.shext, one would process any namespace encapsulation, and
  71  **   ##needs C
  72  ** and so forth.
  73  **
  74  ** Defining the behavior in terms of some form of restricted processing of Contents.shext files is not very clean.  It would probably be better
  75  ** if Contents.shext was replaced by a Shapes-Contents, with special syntax for defining namespace content and encapsulation, like this:
  76  **   |** This is a Shapes-Contents file.
  77  **   |** It may contain comments...
  78  **   ##encapsulated |** comment...
  79  **
  80  ** No, this is better:
  81  **
  82  ** - Shapes-Ignore is a list of files and subdirectories of the current directory that should be ignored.  All other Shapes extension files will
  83  **   be considered part of the namespace, and all other subdirectories are considered enclosed namespaces (there should be a warning if a subdirectory
  84  **   is not ignored, but does not contain any Shapes extension files).
  85  **
  86  ** - Shapes-Encapsulation is an empty file which just indicates that there is a namespace encapsulation wrapping the contents of the current directory.
  87  **
  88  ** - ##needs is not allowed inside a ##push/##pop ^^.  This ensures that a file is always loaded with the same encapsulation.
  89  **/
  90
  91 /** To make sure that extensions don't make use of the same namespace, each global namespaces should have an authority maintaining the list of
  92  ** reserved namespaces inside that global namespace.  A list of recognized global namespace authorities is published at
  93  **   lang-shapes.sourceforge.net/doc/namespace-authorities.html
  94  **
  95  ** For example, the Shapes project is the namespace authority responsible for ..Shapes, with a list or reserved namespaces published at
  96  **   lang-shapes.sourceforge.net/doc/namespace-Shapes.html.
  97  ** There, one will Graphics..Tag..find namsepaces such as
  98  **   ..Shapes..Core
  99  **   ..Shapes..2D
 100  **   ..Shapes..3D
 101  **   ..Shapes..Blockdraw
 102  **/