.TH HTML 2.SH NAMEparsehtml,printitems,validitems,freeitems,freedocinfo,dimenkind,dimenspec,targetid,targetname,fromStr,toStr\- HTML parser.SH SYNOPSIS.nf.PP.ft L#include <u.h>#include <libc.h>#include <html.h>.ft P.PP.ta \w'\fLToken* 'u.BItem* parsehtml(uchar* data, int datalen, Rune* src, int mtype,.B int chset, Docinfo** pdi).PP.Bvoid printitems(Item* items, char* msg).PP.Bint validitems(Item* items).PP.Bvoid freeitems(Item* items).PP.Bvoid freedocinfo(Docinfo* d).PP.Bint dimenkind(Dimen d).PP.Bint dimenspec(Dimen d).PP.Bint targetid(Rune* s).PP.BRune* targetname(int targid).PP.Buchar* fromStr(Rune* buf, int n, int chset).PP.BRune* toStr(uchar* buf, int n, int chset).SH DESCRIPTION.PPThis library implements a parser for HTML 4.0 documents.The parsed HTML is converted into an intermediate representation thatdescribes how the formatted HTML should be laid out..PP.I Parsehtmlparses an entire HTML document contained in the buffer.I dataand having length.IR datalen .The URL of the document should be passed in as.IR src ..I Mtypeis the media type of the document, which should be either.B TextHtmlor.BR TextPlain .The character set of the document is described in.IR chset ,which can be one of.BR US_Ascii ,.BR ISO_8859_1 ,.B UTF_8or.BR Unicode .The return value is a linked list of.B Itemstructures, described in detail below.As a side effect, .BI * pdiis set to point to a newly created.B Docinfostructure, containing information pertaining to the entire document..PPThe library expects two allocation routines to be provided by thecaller,.B emallocand.BR erealloc .These routines are analogous to the standard malloc and realloc routines,except that they should not return if the memory allocation fails.In addition,.B emallocis required to zero the memory..PPFor debugging purposes,.I printitemsmay be called to display the contents of an item list; individual items maybe printed using the.B %Iprint verb, installed on the first call to.IR parsehtml ..I validitemstraverses the item list, checking that all of the pointers are valid.It returns.B 1is everything is ok, and.B 0if an error was found.Normally, one would not call these routines directly.Instead, one sets the global variable.I dbgbuildand the library calls them automatically.One can also set.IR warn ,to cause the library to print a warning whenever it finds a problem with theinput document, and.IR dbglex ,to print debugging information in the lexer..PPWhen an item list is finished with, it should be freed with.IR freeitems .Then,.I freedocinfoshould be called on the pointer returned in.BI * pdi\f1..PP.I Dimenkindand.I dimenspecare provided to interpret the.B Dimentype, as described in the section.IR "Dimension Specifications" ..PPFrame target names are mapped to integer ids via a global, permanent mapping.To find the value for a given name, call.IR targetid ,which allocates a new id if the name hasn't been seen before.The name of a given, known id may be retrieved using.IR targetname .The library predefines.BR FTtop ,.BR FTself ,.B FTparentand.BR FTblank ..PPThe library handles all text as Unicode strings (type.BR Rune* ).Character set conversion is provided by.I fromStrand.IR toStr ..I FromStrtakes.I nUnicode characters from.I bufand converts them to the character set described by.IR chset ..I ToStrtakes.I nbytes from.IR buf ,interpretted as belonging to character set.IR chset ,and converts them to a Unicode string.Both routines null-terminate the result, and use.B emallocto allocate space for it..SS ItemsThe return value of.I parsehtmlis a linked list of variant structures,with the generic portion described by the following definition:.PP.EX.ta 6n +\w'Genattr* 'utypedef struct Item Item;struct Item{ Item* next; int width; int height; int ascent; int anchorid; int state; Genattr* genattr; int tag;};.EE.PPThe field.B nextpoints to the successor in the linked list of items, while.BR width ,.BR height ,and.B ascentare intended for use by the caller as part of the layout process..BR Anchorid ,if non-zero, gives the integer id assigned by the parser to the anchor thatthis item is in (see section.IR Anchors )..B Stateis a collection of flags and values described as follows:.PP.EX.ta 6n +\w'IFindentshift = 'uenum{ IFbrk = 0x80000000, IFbrksp = 0x40000000, IFnobrk = 0x20000000, IFcleft = 0x10000000, IFcright = 0x08000000, IFwrap = 0x04000000, IFhang = 0x02000000, IFrjust = 0x01000000, IFcjust = 0x00800000, IFsmap = 0x00400000, IFindentshift = 8, IFindentmask = (255<<IFindentshift), IFhangmask = 255};.EE.PP.B IFbrkis set if a break is to be forced before placing this item..B IFbrkspis set if a 1 line space should be added to the break (in which case.B IFbrkis also set)..B IFnobrkis set if a break is not permitted before the item..B IFcleftis set if left floats should be cleared (that is, if the list of pending left floats should be placed)before this item is placed, and.B IFcrightis set for right floats.In both cases, IFbrk is also set..B IFwrapis set if the line containing this item is allowed to wrap..B IFhangis set if this item hangs into the left indent..B IFrjustis set if the line containing this item should be right justified,and.B IFcjustis set for center justified lines..B IFsmapis used to indicate that an image is a server-side map.The low 8 bits, represented by.BR IFhangmask ,indicate the current hang into left indent, in tenths of a tabstop.The next 8 bits, represented by.B IFindentmaskand.BR IFindentshift ,indicate the current indent in tab stops..PPThe field.B genattris an optional pointer to an auxiliary structure, described in the section.IR "Generic Attributes" ..PPFinally,.B tagdescribes which variant type this item has.It can have one of the values.BR Itexttag ,.BR Iruletag ,.BR Iimagetag ,.BR Iformfieldtag ,.BR Itabletag ,.B Ifloattagor.BR Ispacertag .For each of these values, there is an additional structure defined, whichincludes Item as an unnamed initial substructure, and then defines additionalfields..PPItems of type.B Itexttagrepresent a piece of text, using the following structure:.PP.EX.ta 6n +\w'Rune* 'ustruct Itext{ Item; Rune* s; int fnt; int fg; uchar voff; uchar ul;};.EE.PPHere.B sis a null-terminated Unicode string of the actual characters making up this text item,.B fntis the font number (described in the section.IR "Font Numbers" ),and.B fgis the RGB encoded color for the text..B Voffmeasures the vertical offset from the baseline; subtract.B Voffbiasto get the actual value (negative values represent a displacement down the page).The field.B ulis the underline style:.B ULnoneif no underline,.B ULunderfor conventional underline, and.B ULmidfor strike-through..PPItems of type.B Iruletagrepresent a horizontal rule, as follows:.PP.EX.ta 6n +\w'Dimen 'ustruct Irule{ Item; uchar align; uchar noshade; int size; Dimen wspec;};.EE.PPHere.B alignis the alignment specification (described in the corresponding section),.B noshadeis set if the rule should not be shaded,.B sizeis the height of the rule (as set by the size attribute),and.B wspecis the desired width (see section.IR "Dimension Specifications" )..PPItems of type.B Iimagetagdescribe embedded images, for which the following structure is defined:.PP.EX.ta 6n +\w'Iimage* 'ustruct Iimage{ Item; Rune* imsrc; int imwidth; int imheight; Rune* altrep; Map* map; int ctlid; uchar align; uchar hspace; uchar vspace; uchar border; Iimage* nextimage;};.EE.PPHere.B imsrcis the URL of the image source,.B imwidthand.BR imheight ,if non-zero, contain the specified width and height for the image,and.B altrepis the text to use as an alternative to the image, if the image is not displayed..BR Map ,if set, points to a structure describing an associated client-side image map..B Ctlidis reserved for use by the application, for handling animated images..B Alignencodes the alignment specification of the image..B Hspacecontains the number of pixels to pad the image with on either side, and.B Vspacethe padding above and below..B Borderis the width of the border to draw around the image..B Nextimagepoints to the next image in the document (the head of this list is.BR Docinfo.images )..PPFor items of type.BR Iformfieldtag ,the following structure is defined:.PP.EX.ta 6n +\w'Formfield* 'ustruct Iformfield{ Item; Formfield* formfield;};.EE.PPThis adds a single field,.BR formfield ,which points to a structure describing a field in a form, described in section.IR Forms ..PPFor items of type.BR Itabletag ,the following structure is defined:.PP.EX.ta 6n +\w'Table* 'ustruct Itable{ Item; Table* table;};.EE.PP.B Tablepoints to a structure describing the table, described in the section.IR Tables ..PPFor items of type.BR Ifloattag ,the following structure is defined:.PP.EX.ta 6n +\w'Ifloat* 'ustruct Ifloat{ Item; Item* item; int x; int y; uchar side; uchar infloats; Ifloat* nextfloat;};.EE.PPThe.B itempoints to a single item (either a table or an image) that floats (the text of thedocument flows around it), and.B sideindicates the margin that this float sticks to; it is either.B ALleftor.BR ALright ..B Xand.B yare reserved for use by the caller; these are typically used for the coordinatesof the top of the float..B Infloatsis used by the caller to keep track of whether it has placed the float..B Nextfloatis used by the caller to link together all of the floats that it has placed..PPFor items of type.BR Ispacertag ,the following structure is defined:.PP.EX.ta 6n +\w'Item; 'ustruct Ispacer{ Item; int spkind;};.EE.PP.B Spkindencodes the kind of spacer, and may be one of.B ISPnull(zero height and width),.B ISPvlineLines 1–500 of 1420. Load more
.TH HTML 2 .SH NAME parsehtml, printitems, validitems, freeitems, freedocinfo, dimenkind, dimenspec, targetid, targetname, fromStr, toStr \- HTML parser .SH SYNOPSIS .nf .PP .ft L #include <u.h> #include <libc.h> #include <html.h> .ft P .PP .ta \w'\fLToken* 'u .B Item* parsehtml(uchar* data, int datalen, Rune* src, int mtype, .B int chset, Docinfo** pdi) .PP .B void printitems(Item* items, char* msg) .PP .B int validitems(Item* items) .PP .B void freeitems(Item* items) .PP .B void freedocinfo(Docinfo* d) .PP .B int dimenkind(Dimen d) .PP .B int dimenspec(Dimen d) .PP .B int targetid(Rune* s) .PP .B Rune* targetname(int targid) .PP .B uchar* fromStr(Rune* buf, int n, int chset) .PP .B Rune* toStr(uchar* buf, int n, int chset) .SH DESCRIPTION .PP This library implements a parser for HTML 4.0 documents. The parsed HTML is converted into an intermediate representation that describes how the formatted HTML should be laid out. .PP .I Parsehtml parses an entire HTML document contained in the buffer .I data and having length .IR datalen . The URL of the document should be passed in as .IR src . .I Mtype is the media type of the document, which should be either .B TextHtml or .BR TextPlain . The character set of the document is described in .IR chset , which can be one of .BR US_Ascii , .BR ISO_8859_1 , .B UTF_8 or .BR Unicode . The return value is a linked list of .B Item structures, described in detail below. As a side effect, .BI * pdi is set to point to a newly created .B Docinfo structure, containing information pertaining to the entire document. .PP The library expects two allocation routines to be provided by the caller, .B emalloc and .BR erealloc . These routines are analogous to the standard malloc and realloc routines, except that they should not return if the memory allocation fails. In addition, .B emalloc is required to zero the memory. .PP For debugging purposes, .I printitems may be called to display the contents of an item list; individual items may be printed using the .B %I print verb, installed on the first call to .IR parsehtml . .I validitems traverses the item list, checking that all of the pointers are valid. It returns .B 1 is everything is ok, and .B 0 if an error was found. Normally, one would not call these routines directly. Instead, one sets the global variable .I dbgbuild and the library calls them automatically. One can also set .IR warn , to cause the library to print a warning whenever it finds a problem with the input document, and .IR dbglex , to print debugging information in the lexer. .PP When an item list is finished with, it should be freed with .IR freeitems . Then, .I freedocinfo should be called on the pointer returned in .BI * pdi\f1. .PP .I Dimenkind and .I dimenspec are provided to interpret the .B Dimen type, as described in the section .IR "Dimension Specifications" . .PP Frame target names are mapped to integer ids via a global, permanent mapping. To find the value for a given name, call .IR targetid , which allocates a new id if the name hasn't been seen before. The name of a given, known id may be retrieved using .IR targetname . The library predefines .BR FTtop , .BR FTself , .B FTparent and .BR FTblank . .PP The library handles all text as Unicode strings (type .BR Rune* ). Character set conversion is provided by .I fromStr and .IR toStr . .I FromStr takes .I n Unicode characters from .I buf and converts them to the character set described by .IR chset . .I ToStr takes .I n bytes from .IR buf , interpretted as belonging to character set .IR chset , and converts them to a Unicode string. Both routines null-terminate the result, and use .B emalloc to allocate space for it. .SS Items The return value of .I parsehtml is a linked list of variant structures, with the generic portion described by the following definition: .PP .EX .ta 6n +\w'Genattr* 'u typedef struct Item Item; struct Item { Item* next; int width; int height; int ascent; int anchorid; int state; Genattr* genattr; int tag; }; .EE .PP The field .B next points to the successor in the linked list of items, while .BR width , .BR height , and .B ascent are intended for use by the caller as part of the layout process. .BR Anchorid , if non-zero, gives the integer id assigned by the parser to the anchor that this item is in (see section .IR Anchors ). .B State is a collection of flags and values described as follows: .PP .EX .ta 6n +\w'IFindentshift = 'u enum { IFbrk = 0x80000000, IFbrksp = 0x40000000, IFnobrk = 0x20000000, IFcleft = 0x10000000, IFcright = 0x08000000, IFwrap = 0x04000000, IFhang = 0x02000000, IFrjust = 0x01000000, IFcjust = 0x00800000, IFsmap = 0x00400000, IFindentshift = 8, IFindentmask = (255<<IFindentshift), IFhangmask = 255 }; .EE .PP .B IFbrk is set if a break is to be forced before placing this item. .B IFbrksp is set if a 1 line space should be added to the break (in which case .B IFbrk is also set). .B IFnobrk is set if a break is not permitted before the item. .B IFcleft is set if left floats should be cleared (that is, if the list of pending left floats should be placed) before this item is placed, and .B IFcright is set for right floats. In both cases, IFbrk is also set. .B IFwrap is set if the line containing this item is allowed to wrap. .B IFhang is set if this item hangs into the left indent. .B IFrjust is set if the line containing this item should be right justified, and .B IFcjust is set for center justified lines. .B IFsmap is used to indicate that an image is a server-side map. The low 8 bits, represented by .BR IFhangmask , indicate the current hang into left indent, in tenths of a tabstop. The next 8 bits, represented by .B IFindentmask and .BR IFindentshift , indicate the current indent in tab stops. .PP The field .B genattr is an optional pointer to an auxiliary structure, described in the section .IR "Generic Attributes" . .PP Finally, .B tag describes which variant type this item has. It can have one of the values .BR Itexttag , .BR Iruletag , .BR Iimagetag , .BR Iformfieldtag , .BR Itabletag , .B Ifloattag or .BR Ispacertag . For each of these values, there is an additional structure defined, which includes Item as an unnamed initial substructure, and then defines additional fields. .PP Items of type .B Itexttag represent a piece of text, using the following structure: .PP .EX .ta 6n +\w'Rune* 'u struct Itext { Item; Rune* s; int fnt; int fg; uchar voff; uchar ul; }; .EE .PP Here .B s is a null-terminated Unicode string of the actual characters making up this text item, .B fnt is the font number (described in the section .IR "Font Numbers" ), and .B fg is the RGB encoded color for the text. .B Voff measures the vertical offset from the baseline; subtract .B Voffbias to get the actual value (negative values represent a displacement down the page). The field .B ul is the underline style: .B ULnone if no underline, .B ULunder for conventional underline, and .B ULmid for strike-through. .PP Items of type .B Iruletag represent a horizontal rule, as follows: .PP .EX .ta 6n +\w'Dimen 'u struct Irule { Item; uchar align; uchar noshade; int size; Dimen wspec; }; .EE .PP Here .B align is the alignment specification (described in the corresponding section), .B noshade is set if the rule should not be shaded, .B size is the height of the rule (as set by the size attribute), and .B wspec is the desired width (see section .IR "Dimension Specifications" ). .PP Items of type .B Iimagetag describe embedded images, for which the following structure is defined: .PP .EX .ta 6n +\w'Iimage* 'u struct Iimage { Item; Rune* imsrc; int imwidth; int imheight; Rune* altrep; Map* map; int ctlid; uchar align; uchar hspace; uchar vspace; uchar border; Iimage* nextimage; }; .EE .PP Here .B imsrc is the URL of the image source, .B imwidth and .BR imheight , if non-zero, contain the specified width and height for the image, and .B altrep is the text to use as an alternative to the image, if the image is not displayed. .BR Map , if set, points to a structure describing an associated client-side image map. .B Ctlid is reserved for use by the application, for handling animated images. .B Align encodes the alignment specification of the image. .B Hspace contains the number of pixels to pad the image with on either side, and .B Vspace the padding above and below. .B Border is the width of the border to draw around the image. .B Nextimage points to the next image in the document (the head of this list is .BR Docinfo.images ). .PP For items of type .BR Iformfieldtag , the following structure is defined: .PP .EX .ta 6n +\w'Formfield* 'u struct Iformfield { Item; Formfield* formfield; }; .EE .PP This adds a single field, .BR formfield , which points to a structure describing a field in a form, described in section .IR Forms . .PP For items of type .BR Itabletag , the following structure is defined: .PP .EX .ta 6n +\w'Table* 'u struct Itable { Item; Table* table; }; .EE .PP .B Table points to a structure describing the table, described in the section .IR Tables . .PP For items of type .BR Ifloattag , the following structure is defined: .PP .EX .ta 6n +\w'Ifloat* 'u struct Ifloat { Item; Item* item; int x; int y; uchar side; uchar infloats; Ifloat* nextfloat; }; .EE .PP The .B item points to a single item (either a table or an image) that floats (the text of the document flows around it), and .B side indicates the margin that this float sticks to; it is either .B ALleft or .BR ALright . .B X and .B y are reserved for use by the caller; these are typically used for the coordinates of the top of the float. .B Infloats is used by the caller to keep track of whether it has placed the float. .B Nextfloat is used by the caller to link together all of the floats that it has placed. .PP For items of type .BR Ispacertag , the following structure is defined: .PP .EX .ta 6n +\w'Item; 'u struct Ispacer { Item; int spkind; }; .EE .PP .B Spkind encodes the kind of spacer, and may be one of .B ISPnull (zero height and width), .B ISPvline