Documentação do mp4h: Sintaxe e Funcionalidades, Manuais, Projetos, Pesquisas de Informática

Baixe Documentação do mp4h: Sintaxe e Funcionalidades e outras Manuais, Projetos, Pesquisas em PDF para Informática, somente na Docsity!

mp4h, version 1.2.

A macro processor for HTML documents Edition 1.2.4, Sat Mar 2 19:10:40 2002

by Denis Barbier

Copyright (^) ©c 2000-2001 Denis Barbier

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the con- ditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another lan- guage, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Chapter 2: Command line options 2

2 Command line options

Optional arguments are enclosed within square brackets. All option synonyms have a similar syntax, so when a long option accepts an argument, short option do too.

Syntax call is mp4h [options] [filename [filename] ...] Options are described below. If no filename is specified, or if its name is ‘-’, then characters are read on standard input.

2.1 Operation modes

‘--help’ display an help message and exit

‘--version’ output mp4h version information and exit

‘-E --fatal-warnings’ stop execution after first warning

‘-Q --quiet --silent’ suppress some warnings for builtins

‘-S --safety-level=‘NUMBER’’ disable risky functions; 0 means no filtering, 1 disable execute and 2 disable this one too plus all filesystem related functions: file-exists, real-path, get-file-properties, directory-contents and include.

2.2 Preprocessor features

‘-I --include=‘DIRECTORY’’ search this directory for includes and packages

‘-D --define=‘NAME‘[=VALUE]’’’ set variable NAME to VALUE, or empty

‘-U --undefine=‘COMMAND’’ delete builtin COMMAND

‘-s --synclines’ generate ‘#line NO "FILE"’ lines

2.3 Parser features

‘-c --caseless=‘NUMBER’’ set case sensitiveness according to the bits of ‘NUMBER’. A null bit means symbol is case sensitive, and bits are defined as followed: 0 for tags, 1 for variables and 2 for entities. Default value is 3, i.e. only entities are case sensitive.

‘-e --encoding=‘NAME’’ specify document encoding. Valid options are ‘8bit’ (default) or ‘utf8’.

Chapter 2: Command line options 3

‘-X --expansion=‘NUMBER’’ set parser behaviour according to the bits of ‘NUMBER’ NUMBER is a combination of

‘ 1 ’ do not parse unknown tags

‘ 2 ’ unknown tags are assumed being simple

‘ 4 ’ trailing star in tag name do not make this tag simple

‘ 8 ’ an unmatched end tag closes all previous unmatched begin tags

‘ 16 ’ interpret backslashes as printf

‘ 32 ’ remove trailing slash in tag attributes

‘ 64 ’ do not remove trailing star in tag name

‘ 128 ’ do not remove leading star in tag name

‘ 256 ’ do not add a space before trailing slash in tag attributes

‘ 1024 ’ suppress warnings about bad nested tags

‘ 2048 ’ suppress warnings about missing trailing slash

In version 1.2.4, default value is 3114=2+ 8 + 32 + 1024 +2048.

2.4 Limits control

‘-H --hashsize=‘PRIME’’ set symbol lookup hash table size (default 509)

‘-L -nesting-limit=‘NUMBER’’ change artificial nesting limit (default 250)

2.5 Debugging

‘-d --debug=‘FLAGS’’ set debug level (no FLAGS implies ‘aeq’)

‘-t --trace=‘NAME’’ trace NAME when it will be defined

‘-l --arglength=‘NUMBER’’ restrict macro tracing size

‘-o --error-output=‘FILE’’ redirect debug and trace output Flags are any of:

‘t’ trace for all macro calls, not only debugging-on’ed

‘a’ show actual arguments

‘e’ show expansion

3 Description

The mp4h software is a macro-processor, which means that keywords are replaced by other text. This chapter describes all primitives. As mp4h has been specially designed for HTML documents, its syntax is very similar to HTML, with tags and attributes. One important feature has no equivalent in HTML: comments until end of line. All text following three colons is discarded until end of line, like ;;; This is a comment

3.1 Function Macros

Note: All examples in this documentation are processed through mp4h with expansion flags set to zero (see a description of possible expansion flags at the end of document), it is why simple tags contain a trailing slash. But mp4h can output plain HTML files with other expansion flags.

The definition of new tags is the most common task provided by mp4h. As with HTML, macro names are case insensitive, unless ‘-c’ option is used to change this default behaviour. In this documentation, only lowercase letters are used. There are two kinds of tags: simple and complex. A simple tag has the following form:

whereas a complex tag looks like:

body

Since version 0.9.1, mp4h knows XHTML syntax too, so your input file may conform to HTML or XHTML syntax. In this manual, we adopt the latter, which is why simple tags have a trailing slash in attributes. If you want to produce HTML files with this input file, you may either choose an adequate ‘--expansion’ flag or use a post-processor like tidy http://www.w3.org/People/Raggett/tidy/.

When a simple tag is defined by mp4h, it can be parsed even if the trailing slash is omitted, because mp4h knows that this tag is simple. But it is a good practice to always append a trailing slash to simple tags.

In macro descriptions below, a slash indicates a simple tag, and a V letter that attributes are read verbatim (without expansion) (see the chapter on macro expansion for further details).

define-tag name [attributes=verbatim] [endtag=required] [whitespace=delete] This function lets you define your own tags. First argument is the command name. Replacement text is the function body.

Source code:

bar

Output:

bar Even if spaces have usually few incidence on HTML syntax, it is important to note that bar and

bar

are not equivalent, the latter form contains two newlines that were not present in the former.

• whitespace=delete Some spaces are suppressed in replacement text, in particular any leading or trailing spaces, and newlines not enclosed within angle brackets.

• endtag=required Define a complex tag Source code: bar

  Output: bar Source code: ;;; body is: %body Here it is Output: body is: Here it is

• attributes=verbatim By default attributes are expanded before text is replaced. If this attribute is used, attributes are inserted into replacement text without expansion. Source code: quux

   Body: %Ubody Attributes: %Uattributes Here we go 

  Output: Body: Here we go Attributes: txt=

provide-tag name [attributes=verbatim] [endtag=required] [whitespace=delete]

Print current hooks of a macro.

Source code:

Text inserted with position=before:! Text inserted with position=after:!

Output:

Text inserted with position=before: Before! Text inserted with position=after: After!

Simple

attributes-quote %attributes

Like %attributes, except that attr=value pairs are printed with double quotes sur- rounding attribute values, and a leading space is added if some text is printed.

Source code:

;;; %attributes />

Output:

id=logo src=logo.gif name=Logo alt=Our logo

Simple

attributes-extract name1 [,name2[,name3...]] %attributes

Extract from %attributes the attr=value pairs for names matching any of name1, name2....

Source code:

/>

Output:

Simple

attributes-remove name1 [,name2[,name3...]] %attributes

Remove from %attributes the attr=value pairs for names matching any of name1, name2....

Source code:

/> />

Output:

Note: The two previous functions are special, because unlike all other macros, their expansion do not form a group. This is necessary to parse the resulting list of attributes.

In those two functions, names of attributes may be regular expressions. Main goal of these primitives is to help writing macros accepting any kind of attributes without having to declare them. A canonical example is

Source code:

/> /> href="">

Output:

Welcome But we want now to add an image attribute. So we may write

Source code:

/> /> href="">

/> src="" alt="" border=0 />

/>

Output:

When there are subexpressions within regular expressions, they are printed instead of the whole expression. Note also that i put a colon before the prefix in order not to mix them with XML namespaces.

3.2 Entities

Entities are macros in the same way as tags, but they do not take any arguments. Whereas tags are normally used to mark up text, entities contain already marked up text. Also note that unlike tags, entities are by default case sensitive.

An entity has the following form: &entity;

define-entity name

This function lets you define your own entities. First argument is the entity name. Replacement text is the function body.

Source code:

bar &foo;

Output:

bar

3.3 Variables

Variables are a special case of simple tags, because they do not accept attributes. In fact their use is different, because variables contain text whereas macros act like operators. A nice feature concerning variables is their manipulation as arrays. Indeed variables can be considered like newline separated lists, which will allow powerful manipulation functions as we will see below.

Simple

set-var name[=value] [name[=value]] ...

This command sets variables.

Simple Verbatim

set-var-verbatim name[=value] [name[=value]] ...

As above but attributes are read verbatim.

set-var-x name=variable-name

This command assigns a variable the value of the body of the command. This is partic- ularly useful when variable values contain newlines and/or quotes.

Note that the variable can not be indexed with this command. Note also, that this command behaves as set-var-verbatim: The body is not expanded until the variable is shown with get-var.

Simple

get-var name [name] ...

Show variable contents. If a numeric value within square brackets is appended to a vari- able name, it represents the index of an array. The first index of arrays is 0 by convention.

Source code:

This is version Operating sytem is ""

Output:

This is version 0.10.

Operating sytem is "Linux 2.2. "

Source code:

Output:

200 1 2 3

Simple Verbatim

get-var-once name [name] ...

As above but attributes are not expanded.

Source code:

0.10.1 ;;; Here is version ;;; Here is version ;;; Here is version

Simple

increment name [by=value]

Increment the variable whose name is the first argument. Default increment is one.

• by=value Change increment amount.

Source code:

Output:

10 11 8

Simple

decrement name [by=value]

Decrement the variable whose name is the first argument. Default decrement is one.

• by=value Change decrement amount.

Source code:

Output:

10 9 6

Simple

copy-var src dest

Copy a variable into another.

Source code:

Output:

Simple

defvar name value

If this variable is not defined or is defined to an empty string, then it is set to the second argument.

Source code:

Output:

Title Title

Simple

symbol-info name

Show informations on symbols. If it is a variable name, the STRING word is printed as well as the number of lines contained within this variable.

If it is a macro name, one of the following messages is printed: PRIM COMPLEX, PRIM TAG, USER COMPLEX or USER TAG

Source code:

bar quux

Output:

STRING 5 PRIM TAG PRIM COMPLEX USER TAG USER COMPLEX

3.4 String Functions

Simple

string-length string

Prints the length of the string.

Source code:

4 /> 4 6 />

Output:

efghijk ef

Simple

string-eq string1 string2 [caseless=true]

Returns true if first two arguments are equal.

Source code:

1: 2:

Output:

1: 2:true

• caseless=true Comparison is case insensitive.

Source code:

1: 2:

Output:

1:true 2:true

Simple

string-neq string1 string2 [caseless=true]

Returns true if the first two arguments are not equal.

Source code:

1: 2:

Output:

1:true 2:

• caseless=true Comparison is case insensitive.

Source code:

1: 2:

Output:

Simple

string-compare string1 string2 [caseless=true]

Compares two strings and returns one of the values less, greater or equal depending on this comparison.

Source code:

1: 2:

Output:

1:less 2:equal

• caseless=true Comparison is case insensitive.

Source code:

1:

Output:

1:equal

Simple

char-offsets string character [caseless=true]

Prints an array containing indexes where the character appear in the string.

• caseless=true Comparison is case insensitive.

Source code:

1: 2:

Output:

1: 8 2: 4 8

3.5 Regular Expressions

Regular expression support is provided by the PCRE (Perl Compatible Regular Expressions) library package, which is open source software, copyright by the University of Cambridge. This is a very nice piece of software, latest versions are available at ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/.