NAME

Quiq::Url - URL Klasse

BASE CLASS

Quiq::Hash

DESCRIPTION

Ein Objekt der Klasse repräsentiert einen URL. Auf dessen Bestandteilen kann mit den Objektmethoden der Klasse operiert werden. Ferner enthält die Klasse allgemeine Methoden im Zusammenhang mit URLs, die als Klassenmethoden implementiert sind.

METHODS

Konstruktor

new() - Instantiiere Objekt

Synopsis

  $urlObj = $class->new;
  $urlObj = $class->new($url);
  $urlObj = $class->new(@keyVal);

Description

Instantiiere ein Objekt der Klasse und liefere eine Referenz auf dieses Objekt zurück.

Objektmethoden

queryString() - liefere Querystring des URL-Objekts

Synopsis

  $query = $urlObj->queryString;

Returns

(String) Querystring

Description

Erzeuge den Querystring des URL-Objekts und liefere diesen zurück.

setQuery() - Setze Querystring-Parameter des URL-Objekts

Synopsis

  $urlObj->setQuery(@keyVal);

Arguments

@keyVal

Liste von Schlüssel-Wert-Paaren

Description

Setze die angegebenen Querystring-Parameter auf den jeweils angegebenen Wert. Existiert ein Parameter bereits, wird sein Wert überschrieben. Tritt derselbe Parameter mehrfach auf, werden die einzelnen Werte zu einem Array zusammengefasst. Ist der Wert eine Arrayreferenz, werden alle Werte des Arrays dem Parameter hinzugefügt.

url() - URL als Zeichenkette

Synopsis

  $url = $urlObj->url;

Returns

(String) URL als Zeichenkette

Description

Erzeuge eine externe Repräsentation des URL-Objekts und liefere diese zurück.

Klassenmethoden

encode() - Kodiere Zeichenkette

Synopsis

  $encStr = $this->encode($str);
  $encStr = $this->encode($str,$encoding);

Arguments

$str

Die Zeichenkette, die kodiert wird.

$encoding (Default: 'utf-8')

Das Encoding, in dem die Zeichenkette encodiert werden soll.

Returns

String

Description

Kodiere die Zeichenkette $str nach MIME-Type "application/x-www-form-urlencoded" und liefere die resultierende Zeichenkette zurück.

In der Zeichenkette werden alle Zeichen außer

  * - . _ 0-9 A-Z a-z

durch eine Folge von

  %xx

ersetzt, wobei die xx dem Hexadezimalwert des betreffenden Bytes im Encoding des Zeichens entspricht.

decode() - Dekodiere Zeichenkette

Synopsis

  $str = $this->decode($encStr);
  $str = $this->decode($encStr,$encoding);

Arguments

$str

Die Zeichenkette, die dekodiert wird.

$encoding (Default: 'utf-8')

Das Encoding, in dem die Zeichenkette encodiert ist.

Returns

String

Description

Dekodiere die "application/x-www-form-urlencoded" codierte Zeichenkette $encStr und liefere die resultierende Zeichenkette zurück.

queryEncode() - Kodiere Querystring

Synopsis

  $queryStr = $this->queryEncode(@opt,@keyVal);
  $queryStr = $this->queryEncode($initialChar,@opt,@keyVal);

Alias

qE()

Arguments

@keyVal

Liste der Schlüssel/Wert-Paare, die URL-kodiert werden sollen.

$initialChar

Zeichen, das der URL-Kodierten Zeichenkette vorangestellt werden soll. Dies ist, wenn bentigt, typischweise ein Fragezeichen (?).

Options

-encoding => $encoding (Default: 'utf-8')

Das Encoding, in dem die Zeichenkette encodiert werden soll.

-null => $bool (Default: 0)

Kodiere auch Schlüssel/Wert-Paare mit leerem Wert (undef oder ''). Per Default werden diese weggelassen.

-separator => $char (Default: '&')

Verwende $char als Trennzeichen zwischen den Schlüssel/Wert-Paaren. Mögliche Werte sind '&' und ';'.

Returns

String

Description

Kodiere die Schlüssel/Wert-Paare in @keyVal gemäß MIME-Type "application/x-www-form-urlencoded" und füge sie zu einem Query String zusammen.

Examples

Querystring mit Kaufmanns-Und als Trennzeichen:

  $url = Quiq::Url->queryEncode(a=>1,b=>2,c=>3);
  =>
  a=1&b=2&c=3

Querystring mit Semikolon als Trennzeichen:

  $url = Quiq::Url->queryEncode(-separator=>';',d=>4,e=>5);
  =>
  d=4;e=5

Querystring mit einleitendem Fragezeichen:

  $url = Quiq::Url->queryEncode('?',a=>1,b=>2,c=>3);
  =>
  ?a=1&b=2&c=3

Details

Als Trennzeichen zwischen den Paaren wird per Default ein Kaufmanns-Und (&) verwendet:

  key1=val1&key2=val2&...&keyN=valN

Ist der erste Parameter ein Fragezeichen (?), wird dieses dem Query String vorangestellt:

  ?key1=val1&key2=val2&...&keyN=valN

Das Fragezeichen ist für die URL-Generierung nützlich, das Semikolon und das Kaufmanns-Und für die Konkatenation von Querystrings.

Ist der Wert eines Schlüssels eine Arrayreferenz, wird für jedes Arrayelement ein eigenes Schlüssel/Wert-Paar erzeugt:

  a => [1,2,3]

wird zu

  a=1&a=2&a=3

queryDecode() - Dekodiere Querystring

Synopsis

  @arr | $arr = $this->queryDecode($queryStr);
  @arr | $arr = $this->queryDecode($queryStr,$encoding);

Arguments

$queryStr

Querystring, der dekodiert werden soll.

$encoding (Default: 'utf-8')

Das Encoding, in dem der Querystring encodiert ist.

Returns

Liste der dekodierten Schüssel/Wert-Paare. Im Skalarkontext eine Referenz auf die Liste.

Description

Dekodiere den Querystring $queryStr und liefere die resultierende Liste von Schlüssel/Wert-Paaren zurück. Im Skalarkontext liefere eine Referenz auf die Liste.

Die Schlüssel/Wert-Paare können per & oder ; getrennt sein.

split() - Zerlege URL in seine Bestandteile

Synopsis

  ($schema,$user,$passw,$host,$port,$path,$query,$fragment,@opt) =
      $this->split($url);

Options

-defaultSchema => $schema (Default: undef)

Füge Defaultschema hinzu, falls keins angegeben ist. Beispiel: -defaultSchema=>'http://'

-debug => $bool (Default: 0)

Gib die Zerlegung auf STDOUT aus.

Description

Zerlege den URL $url in seine Komponenten und liefere diese zurück. Für eine Komponente, die nicht im URL enthalten ist, wird ein Leerstring ('') geliefert.

Ein vollständiger URL hat die Form:

  schema://[user[:password]@]host[:port]/[path][?query][#fragment]
  ------    ----  --------   ----  ----   ----   -----   --------
  1         2     3          4     5      6      7       8
  
  1 = Schema (http, ftp, ...)
  2 = Benutzername
  3 = Passwort
  4 = Hostname (kann auch IP-Adresse sein)
  5 = Port
  6 = Pfad (Gesamtpfad, evtl. einschließlich Pathinfo)
  7 = Querystring
  8 = Searchstring (wird nicht an den Server übermittelt)

Die Funktion akzeptiert auch unvollständige HTTP URLs:

  http://host.domain
  
  http://host.domain:port/
  
  http://host.domain:port/this/is/a/path
  
  /this/is/a/path?arg1=val1&arg2=val2&arg3=val3#text
  
  is/a/path?arg1=val1&arg2=val2&arg3=val3
  
  path?arg1=val1&arg2=val2&arg3=val3
  
  ?arg1=val1&arg2=val2&arg3=val3

Der Querystring ist alles nach '?' und ggf. bis '#', falls angegeben. Der konkrete Aufbau des Querystring, wie Trennzeichen usw., spielt keine Rolle.

VERSION

1.207

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2023 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Quiq

perl -MCPAN -e shell
install Quiq