17


Stream
Propriétés
canRead : Boolean
Vrai (true) si des caractères sont disponibles dans le buffer dʼentrée ou si la fin du flux (stream) mémoire nʼest pas atteinte.
canWrite : Boolean
True si le flux permet lʼécriture.
eof : Boolean
Est-ce que la fin du flux est atteinte ? Pour les flux COM, précise si le flux a été fermé. Les flux réseau (htpp://, net://) peuvent seulement détecter sʼils ont été fermés après quʼun appel à read() ou write() retourne 0. Eof peut détecter des conditions dʼerreur sur le socket mais cela arrive très rarement. Malheureusement, il nʼy a pas de méthode fiable pour déterminer si un socket est fermé ou non sans une opération de lecture ou dʼécriture.
hasChildren : Boolean
Voir readTag()
header : Object
L'entête HTTP des flux http://. Utilisez stream["Content-type"] pour extraire les valeurs.

hostAddress : String
Adresse de lʼhôte (flux réseau seulement)
hostName : String
Nom de lʼhôte (flux réseau seulement)
name : String
Nom du fichier ou URL
pos : Number
Voir position().
position : Number
Position courante en octet depuis le début. Cette propriété est inexploitable pour les flux http et COM.
size : Number
Nombre total dʼoctets du fichier ou du flux mémoire.
status : Number
Message de réponse du serveur Web tel que 200.
statusText : String
Message de réponse du serveur Web tel que 'HTTP/1.1 200 OK'.
stderr : Stream
Capture le flux stderr de exec://
tagText : String
Voir readTag()
Méthodes
Stream( name String, mode String, header Record|Object) => Stream
name : fichier, URL, Nombre dʼoctet pour un flux mémoire. Les URL adoptent
la forme :
http://www.jsdb.org/
file://c:/test.txt
net://server.com:port
com1://56000 (or com2, com3, ...)
text://number_of_bytes
temp://number_of_bytes
exec://command line
mode : précise le mode dʼouverture pour les fichiers (rwactb+). Un + indique un flux non bufferisé et b signale le mode binaire. Le mode par défaut est 'rt' (lecture dʼun fichier texte).
Mode : Description (Utilisable avec)
a : Ajout à un fichier en écriture seule. Positionnement dans le flux et lecture impossible (+tb).
rw : Création dʼun nouveau fichier ou ouverture dʼun fichier existant en lecture et écriture (+tb).
w : Création ou remplacement dʼun fichier avec accès en lecture et écriture (+tbr).
r : Ouverture dʼun fichier existant en lecture (+tbw)
t : Mode texte, \r est omis en lecture et \n est converti en \r\n lors de lʼécriture sur disque. seek et pos sont opérationnels (arw+).
b : Mode binaire, aucune gestion de CRLF (arw+)
+ : Pas de buffer : nʼutilise pas la lecture anticipée, ni le cache dʼécriture (arwtb).
d : Pipes seulement : crée un process détaché avec sa propre fenêtre console (aucune).

Pour les flux http://, mode détermine comment se connecter et les données à récupérer.
0 : Le flux est une connection en mode raw. La récupération du contenu d'une page Web, s'effectue sous la forme :  status=stream.readLine(); header=stream.readMIME();  data=stream.read(header.get("Content-Length'));
1 : Le flux commence avec les champs d'entête HTTP. L'entête est stockée dans la propriété header. La connexion utilise la configuration proxy dʼInternet Explorer et décode les transmissions "Transfer-encoding: Chunked" (souvent créé par les CGI Apache).
(autre valeur) : En version 1.7.2.3 et antérieure, même résultat qu'avec 1. En version 1.7.2.4 et supérieure, le flux ne contient que les données du fichier. Utilisez les propriétés status, statusText et header pour récupérer les informations de connexion. La connexion utilise la configuration proxy dʼInternet Explorer et décode les transmissions "Transfer-encoding: Chunked".

Pour les flux net://, mode détermine les paramètres de la socket.
i : Mode immédiat, n'utilise pas l'algorithme Nagle (TCP_NODELAY). Avant la version 1.7.3.6, la valeur 0 était utilisée à la place de "i". Aucun changement de code n'est requis, la valeur 0 fonctionne toujours.
(autre valeur) :  Utilise l'algorithme Nagle pour regrouper les appels en écritures write() pour limiter le nombre des paquets générés.

header : permet de communiquer les lignes d'entête additionnelles au serveur pour les flux http://.

Si name est une chaîne, jsdb va dʼabord essayer de lʼouvrir comme un URL. Pour récupérer le contenu dʼune page Web en utilisant GET et les en-têtes standards, utilisez Stream('http://server.com/'). La propriété de statut est initialisée avec la première ligne de réponse du serveur. Pour simplement ouvrir un socket et envoyer vos propres en-têtes, utilisez a = new Stream('net://server.com:80/'); a.writeln('POST /file.cgi/ HTTP/1.1\r\n'). Le numéro de port par défaut (si omis) est 80.
Un URL de type file:// est toujours ouvert en mode binaire et en lecture seule. Si name ne sʼapparente pas à un URL (absence de // ), jsdb essaie dʼouvrir un fichier. Les caractères slash ( / ) sont convertis en backslash ( \ ) sous Windows.
Si name prend pour valeur fifo:// alors un buffer FIFO est créé en mémoire.
Si name est omis ou sʼil sʼagit dʼun nombre, un flux mémoire est créé ayant pour la taille initiale celle indiquée (par name).
Si name débute avec "exec://", le flux renvoyé est un pipe vers le process fils. Essayez ceci:
p = new Stream("exec://jsdb.exe","d")
p.writeln("writeln('hello world');")
writeln(p.readln())
p.writeln("quit");
append( data Stream, length Number) => String
data : Flux à ajouter
length : Nombre maximum dʼoctets à lire
-
Ajoute des octets à partir de data tant que sa fin nʼest pas atteinte. Pensez à reculer la position courante dans le flux data avant lʼappel à append().
appendText( data Stream, length Number) => String
data : flux à ajouter
length : nombre maximum dʼoctets à lire
-
Comme append() avec convertion de \n' en \r\n'. Autorise la préparation dʼun texte pour un contrôle edit de Windows.
clear( ) => Boolean
Réinitialise un flux mémoire. La taille est mise à zéro et la position courante remise au début mais la mémoire nʼest pas libérée.
eatChars( skip String) => String
skip : caractères à passer
-
Lit le flux octet par octet. Si lʼoctet lu nʼest pas dans la chaîne de ceux à éviter, renvoie cet octet lu sous la forme dʼune chaîne. Un caractère null interrompt lʼanalyse.
Exemple : var lastchar = file.eatChars(' \t\r\n')
flush( )
Pour les flux fichiers, vide le buffer de 64k (en écrivant les données sur disque). Pour créé un flux non bufferisé, ouvrez le avec lʼoption "+".
format( source Stream|String, values Record, start_delimiter String, end_delimiter String)
Lit le flux source en rempaçant toutes les expressions de type {expression} par la valeur associée à expression dans lʼenregistrement indiqué (record). Les séparateurs standards (accolades) peuvent être remplacés par les chaînes indiquées (start_delimiter, end_delimiter). Si end_delimiter est null et start_delimiter non null alors end_delimiter = start_delimiter.
Exemple :
var Str=new Stream();
var Dta=new Record('name=Shanti,home=California');
Str.format('{name} lives in {home}\n',Dta);
Str.rewind();
writeln(Str.readln());
Str.close();
get( ) => String
Lit un octet à partir du flux et avance la position courante (dʼun octet).
goBack( offset Number) => String
Recule la position courante du nombre dʼoctets indiqué (offset).
goForward( offset Number) => String
Avance la position courante du nombre dʼoctets indiqué (offset).
peek( ) => String
Renvoie le prochain octet dans du flux mémoire ou fichier sans déplacer la position courante. Les flux HTTP et COM nʼétant pas bufferisés, vous devez éviter dʼutiliser cette méthode sans vous assurez préalablement de lʼorigine du flux.
put( ) => String
Ecrit un octet dans le flux et avance la position courante.
putBack( offset Number) => String
Recule la position courante du nombre dʼoctets indiqué (offset).
read( count Number, dest Stream) => String
count : nombre dʼoctets
dest : flux destination (optionnel)
-
Lit le nombre dʼoctets indiqués (au plus) à partir dʼun fichier et les renvoie sous forme dʼune chaîne. Si dest est précisé la méthode readFile() est appelée (à la place de read()).
IMPORTANT
La méthode read adopte un comportement particulier afin de faciliter le téléchargement de donnés à partir de flux HTTP. Le code pour lire le contenu dʼune page Web est :
var s = new Stream('http://www.jsdb.org/')
Les entêtes de réponse, le code de statut et le texte associé sont respectivement stockés dans les propriétés header, status et statusText de lʼobjet Stream. La réponse du serveur est automatiquement décodée et la propriété header modifiée en conséquence. Si vous préférez gérer les entêtes vous-même (comme initialement proposé en version 17.2.3 et antérieures), utilisez la syntaxe ci-après :
var s = new Stream('http://www.jsdb.org/',1)
Dans les rares occasions où vous devrez envoyer des entêtes spécifiques au serveur, utilisez :
var s = new Stream('http://www.jsdb.org/', {header-field: "header-value", ...})
Si vous souhaitez envoyer des entêtes spécifiques et analyser intégralement la réponse HTTP (code de statut inclus), utilisez :
var s = new Stream('http://www.jsdb.org/',0, {header-field: "header-value", ...})
readByte( ) => Number
Voir readUInt8()
readFile( size Number, dest Stream) => String|Number
size : nombre maximal dʼoctets
dest : emplacement de stockage des données
-
Lit le flux en mode binaire et délivre la chaîne résultante. size et dest peuvent être renseignés dans nʼimporte quel ordre. Si dest est précisé, la valeur renvoyée est le nombre dʼoctets copiés à partir du flux vers le flux de destination (dest). Le flux est lu en mode binaire, la chaîne peut contenir des caractères null.
readInt( network Boolean) => Number
network : BigEndian
-
Lit un entier binaire de 32 bits signé. (JavaScript utilise des entiers de 31 bits en interne). Mettre BigEndian à vrai (true) pour utiliser lʼordre natif des octets pour Sun et Mac. Exemple :
var Str=new Stream();
Str.writeByte(1);
Str.writeByte(0);
Str.writeByte(0);
Str.writeByte(0);
Str.rewind();
writeln(Str.readInt()); // false est facultatif
writeln(Str.readInt(true));
Str.close();
Affiche 1 (LittleEndian) puis 8614456 (BigEndian)
readInt16( network Boolean) => Number
network : BigEndian
-
Lit un entier binaire de 16 bits signé.
readInt32( network Boolean) => Number
-
network : BigEndian
Voir readInt().
readInt8( ) => Number
Lit un entier binaire 8 bits signé.
readLine( ) => String
Voir readln().
readList( data Record, delimiter String, equals String) => Number
Data : données à lire
delimiter : séparateur de paires ("\n" par défaut - sans garantie - )
equals : séparateur Nom/valeur ("=" par défaut)
-
Lit une liste de paires. Les séparateurs (de paires et de Nom/valeur) doivent être des caractères. Remarque : les séquences "\r\n" sont converties en "\n" lors de la mise en mémoire. La valeur renvoyée correspond au nombre de paires lues.
Exemple :
var Dta=new Record();
var Str=new Stream();
var Fld;
Str.write('a=b\nc=d');
Str.rewind();
Str.readList(Dta);
Str.close();
writeln(Dta.get('a'),Dta.get('c'));
Affiche : bd
readListB( data Record) => String
Lit des données à partir dʼun enregistrement au format binaire.
readMIME( data Record) => Number
Data Données à lire
Lit une liste de paire nom-valeur au format MIME. Reads a name-value list in MIME format. Les espaces après les deux-points sont significatifs et présument que toute ligne non vide commençant par un espace continue la ligne précédente. Renvoie le nombre de paires lues.
readTag( data Record, allowed String) => String
data : champs étiquette
allowed : liste des champs autorisés (séparés par une virgule, sensibles à la casse)
-
Méthode Utilisée pour lʼanalyse des fichiers XML. Cette méthode analyse le fichier à la recherche de la prochaine balise. Si la liste des champs autorisés (allowed) est précisée, seulement les balises (dʼouverture de fermeture)acceptées stoppent la recherche. En son absence, tout caractère < interrompt lʼanalyse. Le texte parcouru est stocké dans le paramètre tagText du stream. Lorsquʼune balise est atteinte ses paramètres sont stockés dans lʼenregistrement data. Les séquences dʼéchappement XML < > & et " sont automatiquement décodées dans les paramètres mais pas dans les sections CDATA. Si la balise a un marqueur de fin (ex: <tag field=value />), le paramètre de flux hasChildren est mis à faux (false) à vrai (true) dans les autres cas. Le nom de la balise est renvoyé. Si la fin du fichier est atteinte, la valeur renvoyée est une chaîne vide. Si la balise est "![CDATA[", readTag() recherche "]]>" et ajoute le texte intermédiaire à tagText. Le module "xml.js" illustre lʼusage de cette méthode.
var params = new Record; var name = stream.readTag(params,allowed);
readText( ) => String
Lit entièrement le flux, convertit tous les "\n" en "\r\n" et renvoie la chaîne résultante.
readUInt16( network Boolean) => Number
network : BigEndian
Lit un entier binaire de 16 bits non signé.
readUInt8( ) => Number
Lit un entier binaire de 16 bits non signé.
readUntil( search String, skipped Stream) => Boolean
search : chaîne recherchée (qui interrompt la lecture)
skipped : flux cible des données lues jusquʼà la rencontre de la chaîne recherchée
-
Renvoie true si la chaîne recherchée a été trouvée. readUntil() est sensible à la casse. Pour une recherche binaire, utilisez readUntilBytes(). Si search est une chaîne unicode, elle sera convertie en UTF-8.
Exemple :
var memory = new Stream(); var file = new Stream('test.txt'); file.readUntil('</file>',memory) ; writeln(memory);
readUntilBytes( search String, skipped Stream) => Boolean
search : motif recherché (suite dʼoctets qui stoppe la lecture)
skipped : flux cible des données lues jusquʼà la rencontre de la chaîne recherchée
-
Version binaire de readUntil(), readUntilBytes() peut rechercher des motif comprenant des caractères null.
readln( delimiter String) => String
delimiter : caractère de fin de ligne ("\n" par défaut)
-
Renvoie la prochaine ligne de texte dans le fichier (une chaîne vide lorsque la fin du fichier est atteinte).
resize( size Number) => String
size : spécifie la taille du nouveau buffer
-
Redimensionne un flux mémoire. Si la taille du flux diminue, les données sont tronquées à partir de la fin. Si la position courante se retrouve en dehors du flux, elle est déplacée à la fin du flux résultant. Si la taille est augmentée, de la mémoire est allouée par contre aucune donnée nʼest ajoutée.
rewind( ) => String
Pour un fichier ou un flux mémoire, déplace la position courante au début du flux.
Exemple :
temp = new Stream();
temp.write('hello, world');
temp.rewind();
file = new Stream('test.txt','at');
file.append(temp)
seek( location Number) => String
Déplace la position courante à celle indiquée (calculée à partir du début du flux).
setEndOfFile( length Number) => Boolean
length : nouvelle taille maximale du fichier Change la taille dʼun fichier ou dʼun flux mémoire. Les flux mémoire peuvent être tronqués ? Les flux fichiers peuvent être tronqués ou étendus.
toString( ) => String
Pour un fichier, un flux COM ou http, renvoie le nom du fichier. Pour un flux mémoire renvoie le buffer en intégralité.
write( data... String) => Number
data... Objets à écrire dans le flux
Exemple :
stream.write('hello', '4', 5)
Si les arguments de cette méthode ne sont pas des chaînes, la méthode toString() de chaque entité sera appelée. Renvoie le nombre dʼoctets écrits.
writeByte( value Number) => Number
Voir writeUInt8()
writeInt( value Number, network Boolean) => Number
network : BigEndian
Ecrit un entier binaire sur 32 bits au format Intel (LittleEnfian ou BigEndian si à true).
writeInt16( value Number, network Boolean) => Number
network : BigEndian
Ecrit un entier binaire sur 16 bits au format Intel (LittleEndian ou BigEndian si à true).
writeInt32( value Number, network Boolean) => Number
network : BigEndian
-
Voir writeInt()
writeInt8(value Number) => Number
Ecrit un entier binaire sur 8 bits au format Intel (LittleEndian ou BigEndian si à true).
writeLine( ) returns String
Voir writeln()
writeList( data Record, delimiter String, equals String) => Number
data : données à écrire
delimiter : séparateur de paires à utiliser ("/" par défaut - sans garantie - )
equals : séparateur Nom/valeur ("=" par défaut)
-
Ecrit une liste de paires nom-valeur délimitée (par le séparateur de paires). Vous pouvez utiliser nʼimporte quelle chaîne comme séparateur (de paires ou de nom-valeur). La sortie par défaut est name=value/name1=value1/name2=value2/...
Renvoie le nombre de paires écrites.
writeListB( data Record) => String
Ecrit des données à partie dʼun enregistrement au format binaire. Lʼéquivalent C++ est :
for (int i=0; i< data.count; i++) {
  fwrite(data[i].name,1,strlen(data[i].name) + 1, file);
  fwrite(data[i].value,1,strlen(data[i].value) + 1, file);
}
fwrite("",1,1,file);
writeMIME( data Record) => Number
data : données à écrire
-
Ecrit une liste de paires nom-valeur au format MIME. Cʼest lʼéquivalent de writeList(data,': ','\n'). Une ligne vide termine la liste.
Renvoie le nombre de paires écrites.
writeUInt16( value Number, network Boolean) => Number
network : BigEndian
-
Ecrit un entier binaire non signé sur 16 bits au format Intel (LittleEndian ou BigEndian si à true).
writeUInt8( value Number) => Number
Ecrit un entier binaire non signé sur 8 bits au format Intel (LittleEndian ou BigEndian si à true).
writeln( ) => String
Comme write mais ajoute un retour chariot (\n pour les flux mémoire, \r\n pour les flux fichier). Le système dʼentrée sortie sʼassure que pour les fichiers en mode texte, les retours chariot \n en memoire soient correctement convertis en \r\n sur disque. Vous pouvez utilisez pos() et seek() pour déplacer la position courante au sein des fichiers texte, mais ne vous basez pas dessus pour compter les octets dans les opérations de lecture écriture effectuées avec read() et write().