Passa al contenuto principale

3. Expansion (Espansione)

Il processo di espansione del modello URI consiste nel scansionare la stringa del modello dall'inizio alla fine, copiando i caratteri letterali e sostituendo ogni espressione con il risultato dell'applicazione dell'operatore dell'espressione al valore di ogni variabile nominata nell'espressione. Il valore di ogni variabile DEVE (MUST) essere formato prima dell'espansione del modello.

Questa sezione definisce i requisiti di espansione per ogni aspetto della grammatica del modello URI. Un algoritmo non normativo per il processo di espansione nel suo insieme è fornito nell'Appendice A.

Se un processore di modelli incontra una sequenza di caratteri al di fuori di un'espressione che non corrisponde alla grammatica <URI-Template>, allora l'elaborazione del modello DOVREBBE (SHOULD) cessare, il risultato del riferimento URI DOVREBBE (SHOULD) contenere la parte espansa del modello seguita dal resto non espanso, e la posizione e il tipo di errore DOVREBBERO (SHOULD) essere indicati all'applicazione chiamante.

Se viene rilevato un errore in un'espressione, come un operatore o un modificatore di valore che il processore di modelli non riconosce o non supporta ancora, o se viene trovato un carattere non consentito dalla grammatica <expression>, allora le parti non elaborate dell'espressione DOVREBBERO (SHOULD) essere copiate nel risultato non espanse, l'elaborazione del resto del modello DOVREBBE (SHOULD) continuare, e la posizione e il tipo di errore DOVREBBERO (SHOULD) essere indicati all'applicazione chiamante.

Se si verifica un errore, il risultato restituito potrebbe non essere un riferimento URI valido; sarà una stringa di modello incompletamente espansa destinata solo a scopi diagnostici.

3.1. Literal Expansion (Espansione letterale)​

Se il carattere letterale è consentito ovunque nella sintassi URI (unreserved / reserved / pct-encoded), viene copiato direttamente nella stringa di risultato. Altrimenti, l'equivalente codificato in percentuale del carattere letterale viene copiato nella stringa di risultato codificando prima il carattere come la sua sequenza di ottetti in UTF-8 e poi codificando ogni ottetto come un tripletto codificato in percentuale.

3.2. Expression Expansion (Espansione di espressione)​

Ogni espressione è indicata da un carattere di parentesi graffa aperta (") e continua fino alla successiva parentesi graffa chiusa ("). Le espressioni non possono essere annidate.

Un'espressione viene espansa determinando il suo tipo di espressione e quindi seguendo il processo di espansione di quel tipo per ogni varspec separato da virgola nell'espressione. I modelli di Livello 1 sono limitati all'operatore predefinito (espansione di valore di stringa semplice) e una singola variabile per espressione. I modelli di Livello 2 sono limitati a un singolo varspec per espressione.

Il tipo di espressione è determinato osservando il primo carattere dopo la parentesi graffa aperta. Se il carattere è un operatore, si memorizza il tipo di espressione associato a quell'operatore per decisioni di espansione successive e si passa al carattere successivo per l'elenco delle variabili. Se il primo carattere non è un operatore, il tipo di espressione è l'espansione di stringa semplice e il primo carattere è l'inizio dell'elenco delle variabili.

Gli esempi nelle sottosezioni seguenti utilizzano le seguenti definizioni di valori di variabili:

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 (Espansione di variabile)​

Una variabile indefinita (Sezione 2.3) non ha valore ed è ignorata dal processo di espansione. Se tutte le variabili in un'espressione sono indefinite, l'espansione dell'espressione è la stringa vuota.

L'espansione di variabile di un valore definito e non vuoto risulta in una sottostringa di caratteri URI consentiti. Come descritto nella Sezione 1.6, il processo di espansione è definito in termini di punti di codice Unicode al fine di garantire che i caratteri non ASCII siano codificati in percentuale in modo coerente nel riferimento URI risultante. Un modo per un processore di modelli di ottenere un'espansione coerente è transcodificare la stringa del valore in UTF-8 (se non è già UTF-8) e quindi trasformare ogni ottetto che non è nell'insieme consentito nel tripletto codificato in percentuale corrispondente.

L'insieme consentito per una data espansione dipende dal tipo di espressione: le espansioni riservate ("+") e di frammento ("#") consentono all'insieme di caratteri nell'unione di (unreserved / reserved / pct-encoded) di passare senza codifica percentuale, mentre tutti gli altri tipi di espressione consentono solo ai caratteri non riservati di passare senza codifica percentuale. Si noti che il carattere percentuale ("%") è consentito solo come parte di un tripletto codificato in percentuale e solo per l'espansione riservata/frammento: in tutti gli altri casi, un carattere di valore "%" DEVE (MUST) essere codificato in percentuale come "%25" dall'espansione di variabile.

Se una variabile appare più di una volta in un'espressione o all'interno di più espressioni di un modello URI, il valore di quella variabile DEVE (MUST) rimanere statico durante l'intero processo di espansione (cioè, la variabile deve avere lo stesso valore ai fini del calcolo di ogni espansione). Tuttavia, se caratteri riservati o tripletti codificati in percentuale appaiono nel valore, saranno codificati in percentuale da alcuni tipi di espressione e non da altri.

Per una variabile che è un valore di stringa semplice, l'espansione consiste nell'aggiungere il valore codificato alla stringa di risultato. Un modificatore di esplosione non ha effetto. Un modificatore di prefisso limita l'espansione ai primi max-length caratteri del valore decodificato. Se il valore contiene caratteri multi-ottetto o codificati in percentuale, è necessario prestare attenzione a evitare di dividere il valore a metà carattere: contare ogni punto di codice Unicode come un carattere.

Per una variabile che è un array associativo, l'espansione dipende sia dal tipo di espressione che dalla presenza di un modificatore di esplosione. Se non c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere una concatenazione separata da virgole di ogni coppia (name, value) che ha un valore definito. Se c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere ogni coppia che ha un valore definito come "name=value" o, se il valore è la stringa vuota e il tipo di espressione non indica parametri in stile modulo (cioè, non un tipo "?" o "&"), semplicemente "name". Entrambe le stringhe name e value sono codificate nello stesso modo dei valori di stringa semplici. Una stringa di separatore viene aggiunta tra le coppie definite secondo il tipo di espressione, come definito dalla seguente tabella:

Tipo    Separatore
       ","     (predefinito)
  +     ","
  #     ","
  .     "."
  /     "/"
  ;     ";"
  ?     "&"
  &     "&"

Per una variabile che è un valore di lista, se non c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere una concatenazione separata da virgole di ogni valore membro della lista che ha un valore definito, come valore di un singolo nome per quella variabile. Se c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere ogni valore membro della lista che ha un valore definito come valore separato con il nome di quella variabile, o, per i tipi di espressione che non hanno variabili nominate (nessun ";", "?" o "&"), semplicemente aggiungere ogni valore separato dal separatore specifico del tipo.

Un modificatore di prefisso su un valore di lista o valore di array associativo non ha effetto.

3.2.2. Simple String Expansion: {var} (Espansione di stringa semplice)​

L'espansione di stringa semplice è il tipo di espressione predefinito quando non viene fornito alcun operatore.

Per ogni variabile definita nell'elenco delle variabili, eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato. Se più di una variabile ha un valore definito, aggiungere una virgola (",") alla stringa di risultato come separatore tra le espansioni di variabili.

Modello di esempio    Espansione

  `{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} (Espansione riservata)​

L'espansione riservata, indicata dall'operatore più ("+") per i modelli di Livello 2 e superiori, è identica all'espansione di stringa semplice tranne che i valori sostituiti possono anche contenere tripletti codificati in percentuale e caratteri nell'insieme riservato.

Per ogni variabile definita nell'elenco delle variabili, eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme (unreserved / reserved / pct-encoded). Se più di una variabile ha un valore definito, aggiungere una virgola (",") alla stringa di risultato come separatore tra le espansioni di variabili.

Modello di esempio         Espansione

  {+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} (Espansione di frammento)​

L'espansione di frammento, indicata dall'operatore cancelletto ("#") per i modelli di Livello 2 e superiori, è identica all'espansione riservata tranne che un carattere cancelletto (delimitatore di frammento) viene prima aggiunto alla stringa di risultato se una qualsiasi delle variabili è definita.

Modello di esempio    Espansione

  {#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} (Espansione di etichetta con prefisso punto)​

L'espansione di etichetta, indicata dall'operatore punto (".") per i modelli di Livello 3 e superiori, è utile per descrivere spazi URI con nomi di dominio variabili o selettori di percorso (ad esempio, estensioni di file).

Per ogni variabile definita nell'elenco delle variabili, aggiungere "." alla stringa di risultato e quindi eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.

Poiché "." è nell'insieme non riservato, un valore che contiene un "." ha l'effetto di aggiungere più etichette.

Modello di esempio    Espansione

  {.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} (Espansione di segmento di percorso)​

L'espansione di segmento di percorso, indicata dall'operatore barra ("/") nei modelli di Livello 3 e superiori, è utile per descrivere gerarchie di percorsi URI.

Per ogni variabile definita nell'elenco delle variabili, aggiungere "/" alla stringa di risultato e quindi eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.

Si noti che il processo di espansione per l'espansione di segmento di percorso è identico a quello dell'espansione di etichetta a parte la sostituzione di "/" invece di ".". Tuttavia, a differenza di ".", un "/" è un carattere riservato e sarà codificato in percentuale se trovato in un valore.

Modello di esempio    Espansione

  {/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} (Espansione di parametro in stile percorso)​

L'espansione di parametro in stile percorso, indicata dall'operatore punto e virgola (";") nei modelli di Livello 3 e superiori, è utile per descrivere parametri di percorso URI, come "path;property" o "path;name=value".

Per ogni variabile definita nell'elenco delle variabili:

  • aggiungere ";" alla stringa di risultato;
  • se la variabile ha un valore di stringa semplice o non viene fornito alcun modificatore di esplosione, allora:
    • aggiungere il nome della variabile (codificato come se fosse una stringa letterale) alla stringa di risultato;
    • se il valore della variabile non è vuoto, aggiungere "=" alla stringa di risultato;
  • eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.
Modello di esempio    Espansione

  {;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} (Espansione di query in stile modulo)​

L'espansione di query in stile modulo, indicata dall'operatore punto interrogativo ("?") nei modelli di Livello 3 e superiori, è utile per descrivere un intero componente di query opzionale.

Per ogni variabile definita nell'elenco delle variabili:

  • aggiungere "?" alla stringa di risultato se questo è il primo valore definito o aggiungere "&" successivamente;
  • se la variabile ha un valore di stringa semplice o non viene fornito alcun modificatore di esplosione, aggiungere il nome della variabile (codificato come se fosse una stringa letterale) e un carattere uguale ("=") alla stringa di risultato; e,
  • eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.
Modello di esempio    Espansione

  {?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} (Continuazione di query in stile modulo)​

La continuazione di query in stile modulo, indicata dall'operatore ampersand ("&") nei modelli di Livello 3 e superiori, è utile per descrivere coppie opzionali &name=value in un modello che contiene già un componente di query letterale con parametri fissi.

Per ogni variabile definita nell'elenco delle variabili:

  • aggiungere "&" alla stringa di risultato;
  • se la variabile ha un valore di stringa semplice o non viene fornito alcun modificatore di esplosione, aggiungere il nome della variabile (codificato come se fosse una stringa letterale) e un carattere uguale ("=") alla stringa di risultato; e,
  • eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.
Modello di esempio    Espansione

  {&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
Ultimo aggiornamento il