Deprecates !constant, adds !const and !var (see #253).

structurizr · Feb 26, 2024 · 5186fc4 · 5186fc4
1 parent d32faa9
commit 5186fc4
Show file tree

Hide file tree

Showing 15 changed files with 229 additions and 132 deletions.
diff --git a/changelog.md b/changelog.md
@@ -4,6 +4,7 @@
 
 - structurizr-core: `ViewSet.isEmpty()` was missing a check for image views.
 - structurizr-dsl: Fixes https://github.com/structurizr/java/issues/252 (DSL parser does not seem to handle curly brackets balance).
+- structurizr-dsl: Deprecates `!constant`, adds `!const` and `!var` (see https://github.com/structurizr/java/issues/253).
 
 ## 2.0.0 (22nd February 2024)
 

diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/Constant.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/Constant.java
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/ConstantParser.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/ConstantParser.java
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/NameValuePair.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/NameValuePair.java
@@ -0,0 +1,37 @@
+package com.structurizr.dsl;
+
+class NameValuePair {
+
+    private NameValueType type;
+    private final String name;
+    private final String value;
+
+    NameValuePair(String name, String value) {
+        this.name = name;
+        this.value = value;
+    }
+
+    NameValueType getType() {
+        return type;
+    }
+
+    void setType(NameValueType type) {
+        this.type = type;
+    }
+
+    String getName() {
+        return name;
+    }
+
+    String getValue() {
+        return value;
+    }
+
+}
+
+enum NameValueType {
+
+    Constant,
+    Variable
+
+}
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/NameValueParser.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/NameValueParser.java
@@ -0,0 +1,49 @@
+package com.structurizr.dsl;
+
+final class NameValueParser extends AbstractParser {
+
+    private static final String GRAMMAR = "%s <name> <value>";
+
+    private static final int KEYWORD_INDEX = 0;
+    private static final int NAME_INDEX = 1;
+    private static final int VALUE_INDEX = 2;
+
+    private static final String NAME_REGEX = "[a-zA-Z0-9-_.]+";
+
+    NameValuePair parseConstant(Tokens tokens) {
+        NameValuePair nvp = parse(tokens);
+        nvp.setType(NameValueType.Constant);
+
+        return nvp;
+    }
+
+    NameValuePair parseVariable(Tokens tokens) {
+        NameValuePair nvp = parse(tokens);
+        nvp.setType(NameValueType.Variable);
+
+        return nvp;
+    }
+
+    private NameValuePair parse(Tokens tokens) {
+        // !const name value
+        // !var name value
+
+        if (tokens.hasMoreThan(VALUE_INDEX)) {
+            throw new RuntimeException("Too many tokens, expected: " + String.format(GRAMMAR, tokens.get(KEYWORD_INDEX)));
+        }
+
+        if (!tokens.includes(VALUE_INDEX)) {
+            throw new RuntimeException("Expected: " + String.format(GRAMMAR, tokens.get(KEYWORD_INDEX)));
+        }
+
+        String name = tokens.get(NAME_INDEX);
+        String value = tokens.get(VALUE_INDEX);
+
+        if (!name.matches(NAME_REGEX)) {
+            throw new RuntimeException("Constant/variable names must only contain the following characters: a-zA-Z0-9-_.");
+        }
+
+        return new NameValuePair(name, value);
+    }
+
+}
diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslParser.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslParser.java
@@ -42,7 +42,7 @@ public final class StructurizrDslParser extends StructurizrDslTokens {
     private final Stack<DslContext> contextStack;
     private final Set<String> parsedTokens = new HashSet<>();
     private final IdentifiersRegister identifiersRegister;
-    private final Map<String, Constant> constants;
+    private final Map<String, NameValuePair> constantsAndVariables;
 
     private final List<String> dslSourceLines = new ArrayList<>();
     private Workspace workspace;
@@ -56,7 +56,7 @@ public final class StructurizrDslParser extends StructurizrDslTokens {
     public StructurizrDslParser() {
         contextStack = new Stack<>();
         identifiersRegister = new IdentifiersRegister();
-        constants = new HashMap<>();
+        constantsAndVariables = new HashMap<>();
     }
 
     /**
@@ -872,11 +872,29 @@ void parse(List<String> lines, File dslFile, boolean include) throws Structurizr
                         }
 
                     } else if (CONSTANT_TOKEN.equalsIgnoreCase(firstToken)) {
-                        Constant constant = new ConstantParser().parse(getContext(), tokens);
-                        if (constants.containsKey(constant.getName())) {
-                            log.warn("A constant named " + constant.getName() + " already exists");
+                        log.warn("!constant has been deprecated and will be removed in a future release - please use !const or !var instead");
+                        NameValuePair nameValuePair = new NameValueParser().parseConstant(tokens);
+
+                        if (constantsAndVariables.containsKey(nameValuePair.getName())) {
+                            log.warn("A constant \"" + nameValuePair.getName() + "\" already exists");
+                        }
+                        constantsAndVariables.put(nameValuePair.getName(), nameValuePair);
+
+                    } else if (CONST_TOKEN.equalsIgnoreCase(firstToken)) {
+                        NameValuePair nameValuePair = new NameValueParser().parseConstant(tokens);
+
+                        if (constantsAndVariables.containsKey(nameValuePair.getName())) {
+                            throw new StructurizrDslParserException("A constant/variable \"" + nameValuePair.getName() + "\" already exists");
+                        }
+                        constantsAndVariables.put(nameValuePair.getName(), nameValuePair);
+
+                    } else if (VAR_TOKEN.equalsIgnoreCase(firstToken)) {
+                        NameValuePair nameValuePair = new NameValueParser().parseVariable(tokens);
+
+                        if (constantsAndVariables.containsKey(nameValuePair.getName()) && constantsAndVariables.get(nameValuePair.getName()).getType() == NameValueType.Constant) {
+                            throw new StructurizrDslParserException("A constant \"" + nameValuePair.getName() + "\" already exists");
                         }
-                        constants.put(constant.getName(), constant);
+                        constantsAndVariables.put(nameValuePair.getName(), nameValuePair);
 
                     } else if (IDENTIFIERS_TOKEN.equalsIgnoreCase(firstToken) && (inContext(WorkspaceDslContext.class) || inContext(ModelDslContext.class))) {
                         setIdentifierScope(new IdentifierScopeParser().parse(getContext(), tokens));
@@ -963,8 +981,8 @@ private String substituteStrings(String token) {
             String before = m.group(0);
             String after = null;
             String name = before.substring(2, before.length()-1);
-            if (constants.containsKey(name)) {
-                after = constants.get(name).getValue();
+            if (constantsAndVariables.containsKey(name)) {
+                after = constantsAndVariables.get(name).getValue();
             } else {
                 if (!restricted) {
                     String environmentVariable = System.getenv().get(name);

diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslParserException.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslParserException.java
@@ -23,7 +23,7 @@ public final class StructurizrDslParserException extends Exception {
     }
 
     StructurizrDslParserException(String message, File dslFile, int lineNumber, String line) {
-        super((message.endsWith(".") ? message.substring(0, message.length()-1) : message) + " at line " + lineNumber + (dslFile != null ? " of " + dslFile.getAbsolutePath() : "") + ": " + line.trim());
+        super((message.endsWith(".") ? message.substring(0, message.length()-1) : message) + " at line " + lineNumber + (dslFile != null && dslFile.isFile() ? " of " + dslFile.getAbsolutePath() : "") + ": " + line.trim());
         this.lineNumber = lineNumber;
         this.line = line;
     }

diff --git a/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslTokens.java b/structurizr-dsl/src/main/java/com/structurizr/dsl/StructurizrDslTokens.java
@@ -100,6 +100,8 @@ class StructurizrDslTokens {
     static final String ADRS_TOKEN = "!adrs";
     static final String DECISIONS_TOKEN = "!decisions";
     static final String CONSTANT_TOKEN = "!constant";
+    static final String CONST_TOKEN = "!const";
+    static final String VAR_TOKEN = "!var";
     static final String IDENTIFIERS_TOKEN = "!identifiers";
     static final String IMPLIED_RELATIONSHIPS_TOKEN = "!impliedRelationships";
     static final String REF_TOKEN = "!ref";

diff --git a/structurizr-dsl/src/test/java/com/structurizr/dsl/ConstantParserTests.java b/structurizr-dsl/src/test/java/com/structurizr/dsl/ConstantParserTests.java
diff --git a/structurizr-dsl/src/test/java/com/structurizr/dsl/DslTests.java b/structurizr-dsl/src/test/java/com/structurizr/dsl/DslTests.java
@@ -364,17 +364,17 @@ void test_includeLocalDirectory() throws Exception {
         assertEquals("workspace {\n" +
                 "\n" +
                 "    model {\n" +
-                "        !constant SOFTWARE_SYSTEM_NAME \"Software System 1\"\n" +
+                "        !var SOFTWARE_SYSTEM_NAME \"Software System 1\"\n" +
                 "        softwareSystem \"${SOFTWARE_SYSTEM_NAME}\" {\n" +
                 "            !docs ../../docs\n" +
                 "        }\n" +
                 "\n" +
-                "        !constant SOFTWARE_SYSTEM_NAME \"Software System 2\"\n" +
+                "        !var SOFTWARE_SYSTEM_NAME \"Software System 2\"\n" +
                 "        softwareSystem \"${SOFTWARE_SYSTEM_NAME}\" {\n" +
                 "            !docs ../../docs\n" +
                 "        }\n" +
                 "\n" +
-                "        !constant SOFTWARE_SYSTEM_NAME \"Software System 3\"\n" +
+                "        !var SOFTWARE_SYSTEM_NAME \"Software System 3\"\n" +
                 "        softwareSystem \"${SOFTWARE_SYSTEM_NAME}\" {\n" +
                 "            !docs ../../docs\n" +
                 "        }\n" +
@@ -1076,4 +1076,36 @@ void test_UnbalancedCurlyBraces() {
         }
     }
 
+    @Test
+    void test_Const() {
+        try {
+            StructurizrDslParser parser = new StructurizrDslParser();
+            parser.parse("""
+                    workspace {
+                        !const name value1
+                        !const name value2
+                    }
+                    """);
+            fail();
+        } catch (StructurizrDslParserException e) {
+            assertEquals("A constant/variable \"name\" already exists at line 3: !const name value2", e.getMessage());
+        }
+    }
+
+    @Test
+    void test_Var_CannotOverrideConst() {
+        try {
+            StructurizrDslParser parser = new StructurizrDslParser();
+            parser.parse("""
+                    workspace {
+                        !const name value1
+                        !var name value2
+                    }
+                    """);
+            fail();
+        } catch (StructurizrDslParserException e) {
+            assertEquals("A constant \"name\" already exists at line 3: !var name value2", e.getMessage());
+        }
+    }
+
 }