3. Expansion (Erweiterung)
Der Prozess der URI-Template-Expansion besteht darin, die Template-Zeichenkette von Anfang bis Ende zu scannen, literale Zeichen zu kopieren und jeden Ausdruck durch das Ergebnis der Anwendung des Operators des Ausdrucks auf den Wert jeder im Ausdruck genannten Variable zu ersetzen. Der Wert jeder Variable MUSS (MUST) vor der Template-Expansion gebildet werden.
Die Anforderungen an die Expansion für jeden Aspekt der URI-Template-Grammatik sind in diesem Abschnitt definiert. Ein nicht-normativer Algorithmus für den gesamten Expansionsprozess wird in Anhang A bereitgestellt.
Wenn ein Template-Prozessor auf eine Zeichenfolge außerhalb eines Ausdrucks trifft, die nicht mit der <URI-Template>-Grammatik übereinstimmt, dann SOLLTE (SHOULD) die Verarbeitung des Templates beendet werden, das URI-Referenz-Ergebnis SOLLTE (SHOULD) den expandierten Teil des Templates gefolgt vom nicht expandierten Rest enthalten, und die Position und Art des Fehlers SOLLTEN (SHOULD) der aufrufenden Anwendung angezeigt werden.
Wenn ein Fehler in einem Ausdruck auftritt, wie z. B. ein Operator oder Wert-Modifikator, den der Template-Prozessor nicht erkennt oder noch nicht unterstützt, oder wenn ein Zeichen gefunden wird, das von der <expression>-Grammatik nicht erlaubt ist, dann SOLLTEN (SHOULD) die nicht verarbeiteten Teile des Ausdrucks nicht expandiert in das Ergebnis kopiert werden, die Verarbeitung des Rests des Templates SOLLTE (SHOULD) fortgesetzt werden, und die Position und Art des Fehlers SOLLTEN (SHOULD) der aufrufenden Anwendung angezeigt werden.
Wenn ein Fehler auftritt, ist das zurückgegebene Ergebnis möglicherweise keine gültige URI-Referenz; es wird eine unvollständig expandierte Template-Zeichenkette sein, die nur für Diagnosezwecke vorgesehen ist.
3.1. Literal Expansion (Literale Expansion)
Wenn das literale Zeichen irgendwo in der URI-Syntax erlaubt ist (unreserved / reserved / pct-encoded), wird es direkt in die Ergebniszeichenkette kopiert. Andernfalls wird das prozentkodierte Äquivalent des literalen Zeichens in die Ergebniszeichenkette kopiert, indem das Zeichen zuerst als seine Oktettsequenz in UTF-8 kodiert und dann jedes solche Oktett als prozentkodiertes Triplet kodiert wird.
3.2. Expression Expansion (Ausdrucksexpansion)
Jeder Ausdruck wird durch ein öffnendes geschweiftes Klammerzeichen (") angezeigt und setzt sich bis zur nächsten schließenden geschweiften Klammer (") fort. Ausdrücke können nicht verschachtelt werden.
Ein Ausdruck wird expandiert, indem sein Ausdruckstyp bestimmt wird und dann für jedes kommagetrennte varspec im Ausdruck dem Expansionsprozess dieses Typs gefolgt wird. Level-1-Templates sind auf den Standardoperator (einfache Zeichenkettenwert-Expansion) und eine einzelne Variable pro Ausdruck beschränkt. Level-2-Templates sind auf ein einzelnes varspec pro Ausdruck beschränkt.
Der Ausdruckstyp wird bestimmt, indem das erste Zeichen nach der öffnenden Klammer betrachtet wird. Wenn das Zeichen ein Operator ist, wird der mit diesem Operator verbundene Ausdruckstyp für spätere Expansionsentscheidungen gespeichert und zum nächsten Zeichen für die Variablenliste gesprungen. Wenn das erste Zeichen kein Operator ist, ist der Ausdruckstyp einfache Zeichenkettenexpansion und das erste Zeichen ist der Beginn der Variablenliste.
Die Beispiele in den folgenden Unterabschnitten verwenden die folgenden Variablenwertdefinitionen:
count := ("one", "two", "three")
dom := ("example", "com")
dub := "me/too"
hello := "Hello World!"
half := "50%"
var := "value"
who := "fred"
base := "http://example.com/home/"
path := "/foo/bar"
list := ("red", "green", "blue")
keys := [("semi",";"),("dot","."),("comma",",")]
v := "6"
x := "1024"
y := "768"
empty := ""
empty_keys := []
undef := null
3.2.1. Variable Expansion (Variablenexpansion)
Eine Variable, die undefiniert ist (Abschnitt 2.3), hat keinen Wert und wird vom Expansionsprozess ignoriert. Wenn alle Variablen in einem Ausdruck undefiniert sind, ist die Expansion des Ausdrucks die leere Zeichenkette.
Die Variablenexpansion eines definierten, nicht leeren Werts ergibt eine Teilzeichenkette erlaubter URI-Zeichen. Wie in Abschnitt 1.6 beschrieben, ist der Expansionsprozess in Bezug auf Unicode-Codepunkte definiert, um sicherzustellen, dass Nicht-ASCII-Zeichen in der resultierenden URI-Referenz konsistent prozentkodiert werden. Eine Möglichkeit für einen Template-Prozessor, eine konsistente Expansion zu erhalten, besteht darin, die Wertzeichenkette in UTF-8 zu transkodieren (falls sie nicht bereits UTF-8 ist) und dann jedes Oktett, das nicht im erlaubten Satz ist, in das entsprechende prozentkodierte Triplet umzuwandeln.
Der erlaubte Satz für eine gegebene Expansion hängt vom Ausdruckstyp ab: Reservierte ("+") und Fragment ("#") Expansionen erlauben den Zeichensatz in der Vereinigung von (unreserved / reserved / pct-encoded) ohne Prozentkodierung durchzulassen, während alle anderen Ausdruckstypen nur nicht reservierte Zeichen ohne Prozentkodierung durchlassen. Beachten Sie, dass das Prozentzeichen ("%") nur als Teil eines prozentkodier ten Triplets und nur für reservierte/Fragment-Expansion erlaubt ist: in allen anderen Fällen MUSS (MUST) ein Wertzeichen "%" durch Variablenexpansion als "%25" prozentkodiert werden.
Wenn eine Variable mehr als einmal in einem Ausdruck oder innerhalb mehrerer Ausdrücke eines URI-Templates erscheint, MUSS (MUST) der Wert dieser Variable während des gesamten Expansionsprozesses statisch bleiben (d. h. die Variable muss für die Berechnung jeder Expansion denselben Wert haben). Wenn jedoch reservierte Zeichen oder prozentkodierte Triplets im Wert vorkommen, werden sie von einigen Ausdruckstypen prozentkodiert und von anderen nicht.
Für eine Variable, die einen einfachen Zeichenkettenwert hat, besteht die Expansion darin, den kodierten Wert an die Ergebniszeichenkette anzuhängen. Ein Explode-Modifikator hat keine Wirkung. Ein Präfix-Modifikator beschränkt die Expansion auf die ersten max-length Zeichen des dekodierten Werts. Wenn der Wert Mehroktett- oder prozentkodierte Zeichen enthält, muss darauf geachtet werden, den Wert nicht mitten in einem Zeichen aufzuteilen: zählen Sie jeden Unicode-Codepunkt als ein Zeichen.
Für eine Variable, die ein assoziatives Array ist, hängt die Expansion sowohl vom Ausdruckstyp als auch von der Anwesenheit eines Explode-Modifikators ab. Wenn es keinen Explode-Modifikator gibt, besteht die Expansion darin, eine kommagetrennte Verkettung jedes (name, value) Paares anzuhängen, das einen definierten Wert hat. Wenn es einen Explode-Modifikator gibt, besteht die Expansion darin, jedes Paar mit einem definierten Wert als "name=value" anzuhängen oder, wenn der Wert die leere Zeichenkette ist und der Ausdruckstyp keine Formular-Stil-Parameter anzeigt (d. h. kein "?" oder "&" Typ), einfach "name". Sowohl Name- als auch Wertzeichenketten werden auf die gleiche Weise wie einfache Zeichenkettenwerte kodiert. Eine Trennzeichenkette wird zwischen definierten Paaren gemäß dem Ausdruckstyp angehängt, wie in der folgenden Tabelle definiert:
Typ Trennzeichen
"," (Standard)
+ ","
# ","
. "."
/ "/"
; ";"
? "&"
& "&"
Für eine Variable mit einem Listenwert besteht die Expansion ohne Explode-Modifikator darin, eine kommagetrennte Verkettung jedes Listenmitgliedswerts mit einem definierten Wert als Wert eines einzelnen Namens für diese Variable anzuhängen. Wenn ein Explode-Modifikator vorhanden ist, besteht die Expansion darin, jeden Listenmitgliedswert mit einem definierten Wert als separaten Wert mit dem Namen dieser Variable anzuhängen oder, für Ausdruckstypen ohne benannte Variablen (kein ";", "?" oder "&"), einfach jeden Wert anzuhängen, getrennt durch das typspezifische Trennzeichen.
Ein Präfix-Modifikator auf einem Listenwert oder assoziativen Array-Wert hat keine Wirkung.
3.2.2. Simple String Expansion: {var} (Einfache Zeichenkettenexpansion)
Einfache Zeichenkettenexpansion ist der Standard-Ausdruckstyp, wenn kein Operator angegeben ist.
Für jede definierte Variable in der Variablenliste führen Sie Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im nicht reservierten Satz sind. Wenn mehr als eine Variable einen definierten Wert hat, hängen Sie ein Komma (",") als Trennzeichen zwischen Variablenexpansionen an die Ergebniszeichenkette an.
Beispiel-Template Expansion
```{var}``` value
{hello} Hello%20World%21
{half} 50%25
O{empty}X OX
O{undef}X OX
{x,y} 1024,768
{x,hello,y} 1024,Hello%20World%21,768
?{x,empty} ?1024,
?{x,undef} ?1024
?{undef,y} ?768
{var:3} val
{var:30} value
{list} red,green,blue
{list*} red,green,blue
{keys} semi,%3B,dot,.,comma,%2C
{keys*} semi=%3B,dot=.,comma=%2C
3.2.3. Reserved Expansion: {+var} (Reservierte Expansion)
Reservierte Expansion, angezeigt durch den Plus ("+") Operator für Level-2- und höhere Templates, ist identisch mit einfacher Zeichenkettenexpansion, außer dass die substituierten Werte auch prozentkodierte Triplets und Zeichen im reservierten Satz enthalten können.
Für jede definierte Variable in der Variablenliste führen Sie Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im Satz (unreserved / reserved / pct-encoded) sind. Wenn mehr als eine Variable einen definierten Wert hat, hängen Sie ein Komma (",") als Trennzeichen zwischen Variablenexpansionen an die Ergebniszeichenkette an.
Beispiel-Template Expansion
{+var} value
{+hello} Hello%20World!
{+half} 50%25
{base}index http%3A%2F%2Fexample.com%2Fhome%2Findex
{+base}index http://example.com/home/index
O{+empty}X OX
O{+undef}X OX
{+path}/here /foo/bar/here
here?ref={+path} here?ref=/foo/bar
{+x,hello,y} 1024,Hello%20World!,768
{+path,x}/here /foo/bar,1024/here
{+path:6}/here /foo/b,1024/here
{+list} red,green,blue
{+list*} red,green,blue
{+keys} semi,;,dot,.,comma,,
{+keys*} semi=;,dot=.,comma=,
3.2.4. Fragment Expansion: {#var} (Fragment-Expansion)
Fragment-Expansion, angezeigt durch den Raute ("#") Operator für Level-2- und höhere Templates, ist identisch mit reservierter Expansion, außer dass ein Rautezeichen (Fragment-Trennzeichen) zuerst an die Ergebniszeichenkette angehängt wird, wenn eine der Variablen definiert ist.
Beispiel-Template Expansion
{#var} #value
{#hello} #Hello%20World!
{#half} #50%25
foo{#empty} foo#
foo{#undef} foo
{#x,hello,y} #1024,Hello%20World!,768
{#path,x}/here #/foo/bar,1024/here
{#path:6}/here #/foo/b/here
{#list} #red,green,blue
{#list*} #red,green,blue
{#keys} #semi,;,dot,.,comma,,
{#keys*} #semi=;,dot=.,comma=,
3.2.5. Label Expansion with Dot-Prefix: {.var} (Label-Expansion mit Punkt-Präfix)
Label-Expansion, angezeigt durch den Punkt (".") Operator für Level-3- und höhere Templates, ist nützlich für die Beschreibung von URI-Räumen mit variierenden Domainnamen oder Pfadselektoren (z. B. Dateierweiterungen).
Für jede definierte Variable in der Variablenliste hängen Sie "." an die Ergebniszeichenkette an und führen dann Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im nicht reservierten Satz sind.
Da "." im nicht reservierten Satz ist, hat ein Wert, der einen "." enthält, den Effekt, mehrere Labels hinzuzufügen.
Beispiel-Template Expansion
{.who} .fred
{.who,who} .fred.fred
{.half,who} .50%25.fred
www{.dom*} www.example.com
X{.var} X.value
X{.empty} X.
X{.undef} X
X{.var:3} X.val
X{.list} X.red,green,blue
X{.list*} X.red.green.blue
X{.keys} X.semi,%3B,dot,.,comma,%2C
X{.keys*} X.semi=%3B.dot=..comma=%2C
X{.empty_keys} X
X{.empty_keys*} X
3.2.6. Path Segment Expansion: {/var} (Pfadsegment-Expansion)
Pfadsegment-Expansion, angezeigt durch den Schrägstrich ("/") Operator in Level-3- und höheren Templates, ist nützlich für die Beschreibung von URI-Pfadhierarchien.
Für jede definierte Variable in der Variablenliste hängen Sie "/" an die Ergebniszeichenkette an und führen dann Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im nicht reservierten Satz sind.
Beachten Sie, dass der Expansionsprozess für Pfadsegment-Expansion identisch mit dem der Label-Expansion ist, abgesehen von der Substitution von "/" anstelle von ".". Im Gegensatz zu "." ist "/" jedoch ein reserviertes Zeichen und wird prozentkodiert, wenn es in einem Wert gefunden wird.
Beispiel-Template Expansion
{/who} /fred
{/who,who} /fred/fred
{/half,who} /50%25/fred
{/who,dub} /fred/me%2Ftoo
{/var} /value
{/var,empty} /value/
{/var,undef} /value
{/var,x}/here /value/1024/here
{/var:1,var} /v/value
{/list} /red,green,blue
{/list*} /red/green/blue
{/list*,path:4} /red/green/blue/%2Ffoo
{/keys} /semi,%3B,dot,.,comma,%2C
{/keys*} /semi=%3B/dot=./comma=%2C
3.2.7. Path-Style Parameter Expansion: {;var} (Pfad-Stil-Parameter-Expansion)
Pfad-Stil-Parameter-Expansion, angezeigt durch den Semikolon (";") Operator in Level-3- und höheren Templates, ist nützlich für die Beschreibung von URI-Pfadparametern, wie "path;property" oder "path;name=value".
Für jede definierte Variable in der Variablenliste:
- hängen Sie ";" an die Ergebniszeichenkette an;
- wenn die Variable einen einfachen Zeichenkettenwert hat oder kein Explode-Modifikator angegeben ist, dann:
- hängen Sie den Variablennamen (kodiert, als wäre es eine literale Zeichenkette) an die Ergebniszeichenkette an;
- wenn der Wert der Variable nicht leer ist, hängen Sie "=" an die Ergebniszeichenkette an;
- führen Sie Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im nicht reservierten Satz sind.
Beispiel-Template Expansion
{;who} ;who=fred
{;half} ;half=50%25
{;empty} ;empty
{;v,empty,who} ;v=6;empty;who=fred
{;v,bar,who} ;v=6;who=fred
{;x,y} ;x=1024;y=768
{;x,y,empty} ;x=1024;y=768;empty
{;x,y,undef} ;x=1024;y=768
{;hello:5} ;hello=Hello
{;list} ;list=red,green,blue
{;list*} ;list=red;list=green;list=blue
{;keys} ;keys=semi,%3B,dot,.,comma,%2C
{;keys*} ;semi=%3B;dot=.;comma=%2C
3.2.8. Form-Style Query Expansion: {?var} (Formular-Stil-Abfrage-Expansion)
Formular-Stil-Abfrage-Expansion, angezeigt durch den Fragezeichen ("?") Operator in Level-3- und höheren Templates, ist nützlich für die Beschreibung einer gesamten optionalen Abfragekomponente.
Für jede definierte Variable in der Variablenliste:
- hängen Sie "?" an die Ergebniszeichenkette an, wenn dies der erste definierte Wert ist, oder hängen Sie danach "&" an;
- wenn die Variable einen einfachen Zeichenkettenwert hat oder kein Explode-Modifikator angegeben ist, hängen Sie den Variablennamen (kodiert, als wäre es eine literale Zeichenkette) und ein Gleichheitszeichen ("=") an die Ergebniszeichenkette an; und,
- führen Sie Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im nicht reservierten Satz sind.
Beispiel-Template Expansion
{?who} ?who=fred
{?half} ?half=50%25
{?x,y} ?x=1024&y=768
{?x,y,empty} ?x=1024&y=768&empty=
{?x,y,undef} ?x=1024&y=768
{?var:3} ?var=val
{?list} ?list=red,green,blue
{?list*} ?list=red&list=green&list=blue
{?keys} ?keys=semi,%3B,dot,.,comma,%2C
{?keys*} ?semi=%3B&dot=.&comma=%2C
3.2.9. Form-Style Query Continuation: {&var} (Formular-Stil-Abfrage-Fortsetzung)
Formular-Stil-Abfrage-Fortsetzung, angezeigt durch den Und-Zeichen ("&") Operator in Level-3- und höheren Templates, ist nützlich für die Beschreibung optionaler &name=value Paare in einem Template, das bereits eine literale Abfragekomponente mit festen Parametern enthält.
Für jede definierte Variable in der Variablenliste:
- hängen Sie "&" an die Ergebniszeichenkette an;
- wenn die Variable einen einfachen Zeichenkettenwert hat oder kein Explode-Modifikator angegeben ist, hängen Sie den Variablennamen (kodiert, als wäre es eine literale Zeichenkette) und ein Gleichheitszeichen ("=") an die Ergebniszeichenkette an; und,
- führen Sie Variablenexpansion durch, wie in Abschnitt 3.2.1 definiert, wobei die erlaubten Zeichen diejenigen im nicht reservierten Satz sind.
Beispiel-Template Expansion
{&who} &who=fred
{&half} &half=50%25
?fixed=yes{&x} ?fixed=yes&x=1024
{&x,y,empty} &x=1024&y=768&empty=
{&x,y,undef} &x=1024&y=768
{&var:3} &var=val
{&list} &list=red,green,blue
{&list*} &list=red&list=green&list=blue
{&keys} &keys=semi,%3B,dot,.,comma,%2C
{&keys*} &semi=%3B&dot=.&comma=%2C