!extend can now be used instead of !ref.

docs/changelog.md

@@ -7,6 +7,7 @@
 - Fixes https:/structurizr/dsl/issues/324 (Groups with no curly braces breaks diagrams).
 - Adds a way to set the character encoding used by the DSL parser (see https:/structurizr/dsl/issues/338).
 - Fixes https:/structurizr/dsl/issues/336 (Dynamic View does not allow !script tag).
+- `!extend` can now be used instead of `!ref`.
 
 ## 1.32.0 (28th July 2023)
 

src/main/java/com/structurizr/dsl/RefParser.java

@@ -1,24 +1,23 @@
 package com.structurizr.dsl;
 
-import com.structurizr.model.Element;
 import com.structurizr.model.ModelItem;
 import com.structurizr.model.StaticStructureElement;
 
 final class RefParser extends AbstractParser {
 
- private static final String GRAMMAR = "!ref <identifier|canonical name>";
+ private static final String GRAMMAR = "%s <identifier|canonical name>";
 
  private final static int IDENTIFIER_INDEX = 1;
 
  ModelItem parse(DslContext context, Tokens tokens) {
  // !ref <identifier|canonical name>
 
  if (tokens.hasMoreThan(IDENTIFIER_INDEX)) {
- throw new RuntimeException("Too many tokens, expected: " + GRAMMAR);
+ throw new RuntimeException("Too many tokens, expected: " + String.format(GRAMMAR, tokens.get(0)));
  }
 
  if (!tokens.includes(IDENTIFIER_INDEX)) {
- throw new RuntimeException("Expected: " + GRAMMAR);
+ throw new RuntimeException("Expected: " + String.format(GRAMMAR, tokens.get(0)));
  }
 
  String s = tokens.get(IDENTIFIER_INDEX);
@@ -36,7 +35,7 @@ ModelItem parse(DslContext context, Tokens tokens) {
  }
 
  if (modelItem == null) {
- throw new RuntimeException("An element/relationship referenced by \"" + s + "\" could not be found");
+ throw new RuntimeException("An element/relationship identified by \"" + s + "\" could not be found");
  }
 
  if (context instanceof GroupableDslContext && modelItem instanceof StaticStructureElement) {

src/main/java/com/structurizr/dsl/StructurizrDslParser.java

@@ -323,7 +323,7 @@ void parse(List<String> lines, File dslFile) throws StructurizrDslParserExceptio
 
  registerIdentifier(identifier, relationship);
 
- } else if (REF_TOKEN.equalsIgnoreCase(firstToken) && (inContext(ModelDslContext.class))) {
+ } else if ((REF_TOKEN.equalsIgnoreCase(firstToken) || EXTEND_TOKEN.equalsIgnoreCase(firstToken)) && (inContext(ModelDslContext.class))) {
  ModelItem modelItem = new RefParser().parse(getContext(), tokens.withoutContextStartToken());
 
  if (shouldStartContext(tokens)) {

src/main/java/com/structurizr/dsl/StructurizrDslTokens.java

@@ -101,6 +101,7 @@ class StructurizrDslTokens {
  static final String IDENTIFIERS_TOKEN = "!identifiers";
  static final String IMPLIED_RELATIONSHIPS_TOKEN = "!impliedRelationships";
  static final String REF_TOKEN = "!ref";
+ static final String EXTEND_TOKEN = "!extend";
  static final String PLUGIN_TOKEN = "!plugin";
  static final String SCRIPT_TOKEN = "!script";
 

src/test/dsl/extend/extend-workspace-from-json-file.dsl

@@ -1,13 +1,13 @@
 workspace extends workspace.json {
 
  model {
- // !ref with DSL identifier
- !ref softwareSystem1 {
+ // !extend with DSL identifier
+ !extend softwareSystem1 {
  webapp1 = container "Web Application 1"
  }
 
- // !ref with canonical name
- !ref "SoftwareSystem://Software System 1" {
+ // !extend with canonical name
+ !extend "SoftwareSystem://Software System 1" {
  webapp2 = container "Web Application 2"
  }
 

src/test/dsl/extend/extend-workspace-from-json-url.dsl

@@ -1,13 +1,13 @@
 workspace extends https://raw.githubusercontent.com/structurizr/dsl/master/src/test/dsl/extend/workspace.json {
 
  model {
- // !ref with DSL identifier
- !ref softwareSystem1 {
+ // !extend with DSL identifier
+ !extend softwareSystem1 {
  webapp1 = container "Web Application 1"
  }
 
- // !ref with canonical name
- !ref "SoftwareSystem://Software System 1" {
+ // !extend with canonical name
+ !extend "SoftwareSystem://Software System 1" {
  webapp2 = container "Web Application 2"
  }
 

src/test/java/com/structurizr/dsl/RefParserTests.java

@@ -1,6 +1,5 @@
 package com.structurizr.dsl;
 
-import com.structurizr.model.Element;
 import com.structurizr.model.ModelItem;
 import com.structurizr.model.Person;
 import com.structurizr.model.Relationship;
@@ -15,7 +14,7 @@ class RefParserTests extends AbstractTests {
  @Test
  void test_parse_ThrowsAnException_WhenThereAreTooManyTokens() {
  try {
- parser.parse(context(), tokens("ref", "name", "tokens"));
+ parser.parse(context(), tokens("!ref", "name", "tokens"));
  fail();
  } catch (Exception e) {
  assertEquals("Too many tokens, expected: !ref <identifier|canonical name>", e.getMessage());
@@ -25,27 +24,27 @@ void test_parse_ThrowsAnException_WhenThereAreTooManyTokens() {
  @Test
  void test_parse_ThrowsAnException_WhenTheIdentifierOrCanonicalNameIsNotSpecified() {
  try {
- parser.parse(context(), tokens("ref"));
+ parser.parse(context(), tokens("!extend"));
  fail();
  } catch (Exception e) {
- assertEquals("Expected: !ref <identifier|canonical name>", e.getMessage());
+ assertEquals("Expected: !extend <identifier|canonical name>", e.getMessage());
  }
  }
 
  @Test
  void test_parse_ThrowsAnException_WhenTheReferencedElementCannotBeFound() {
  try {
- parser.parse(context(), tokens("ref", "Person://User"));
+ parser.parse(context(), tokens("!ref", "Person://User"));
  fail();
  } catch (Exception e) {
- assertEquals("An element/relationship referenced by \"Person://User\" could not be found", e.getMessage());
+ assertEquals("An element/relationship identified by \"Person://User\" could not be found", e.getMessage());
  }
  }
 
  @Test
  void test_parse_FindsAnElementByCanonicalName() {
  Person user = workspace.getModel().addPerson("User");
- ModelItem element = parser.parse(context(), tokens("ref", "Person://User"));
+ ModelItem element = parser.parse(context(), tokens("!ref", "Person://User"));
 
  assertSame(user, element);
  }
@@ -59,7 +58,7 @@ void test_parse_FindsAnElementByIdentifier() {
  register.register("user", user);
  context.setIdentifierRegister(register);
 
- ModelItem modelItem = parser.parse(context, tokens("ref", "user"));
+ ModelItem modelItem = parser.parse(context, tokens("!ref", "user"));
  assertSame(modelItem, user);
  }
 
@@ -73,7 +72,7 @@ void test_parse_FindsARelationshipByIdentifier() {
  register.register("rel", relationship);
  context.setIdentifierRegister(register);
 
- ModelItem modelItem = parser.parse(context, tokens("ref", "rel"));
+ ModelItem modelItem = parser.parse(context, tokens("!ref", "rel"));
  assertSame(modelItem, relationship);
  }