Skip to content

Latest commit

 

History

History
393 lines (286 loc) · 12.2 KB

API.md

File metadata and controls

393 lines (286 loc) · 12.2 KB
Raw

API of the libtidy package for node

General usage:

var libtidy = require("libtidy");

tidyBuffer(input, [opts], [cb])

Asynchronous function. Suggested entry point for most applications.

  • input – anything except a buffer will be converted to String and then turned into a buffer.
  • opts – a dictionary of libtidy options.
  • cb – callback following the callback convention, i.e. with signature function(exception, {output, errlog}) or omitted to return a promise.

The function applies the following libtidy options by default:

  • newline = LF

TidyDoc()

Constructor. Main entry point for low-level access to the library. Contruction wraps tidyCreateWithAllocator, while garbage collection triggers tidyRelease.

TidyDoc.cleanAndRepair([cb])

Asynchronous method binding tidyCleanAndRepair.

  • cb – callback following the callback convention, i.e. with signature function(exception, {errlog}) or omitted to return a promise.

TidyDoc.cleanAndRepairSync()

Synchronous method binding tidyCleanAndRepair. Returns any diagnostics encountered during operation, as a string.

TidyDoc.getOption(key)

Retrieve the TidyOption object for the key in question.

  • key – can be a string (hyphen-separated, underscore_separated or camelCase), a numeric id (not portable) or a TidyOption object (rather pointless here).

Wraps tidyGetOptionByName and tidyGetOption.

TidyDoc.getOptionList()

Retrieve the list of all known options, as an array of TidyOption objects.

Wraps tidyGetOptionList and tidyGetNextOption.

TidyDoc.optGet(key)

Get the current value of the option in question.

For enumerated options, the result will return the current pick value as a string. Otherwise, optGet returns the option value based on its type, i.e. call tidyOptGetBool, tidyOptGetInt or tidyOptGetValue. Empty strings will be returned as null like libtidy does.

  • key – can be a string (hyphen-separated, underscore_separated or camelCase), a numeric id (not portable) or a TidyOption object.

TidyDoc.optGetCurrPick(key)

Get a string representation of the current value for a given option. The option must have a pick list associated. It applies to enumerated options (which internally are of type int) and to boolean options.

For most applications, optGet should be more suitable.

  • key – can be a string (hyphen-separated, underscore_separated or camelCase), a numeric id (not portable) or a TidyOption object.

Wraps tidyOptGetCurrPick.

TidyDoc.optGetDoc(key)

Describe the named option. The description is a HTML snippet, returned as a string.

  • key – can be a string (hyphen-separated, underscore_separated or camelCase), a numeric id (not portable) or a TidyOption object.

Wraps tidyOptGetDoc.

TidyDoc.optGetDocLinksList(key)

Identify related options. The result is a (possibly empty) array of TidyOption objects.

  • key – can be a string (hyphen-separated, underscore_separated or camelCase), a numeric id (not portable) or a TidyOption object.

Wraps tidyOptGetDocLinksList and tidyOptGetNextDocLinks.

TidyDoc.optSet(key, value)

Set the value for the option in question.

  • key – can be a string (hyphen-separated, underscore_separated or camelCase), a numeric id (not portable) or a TidyOption object.
  • value – new value of the option.

The interpretation of the value depends on the type of the option:

  • If the type of the option is integer and the provided value is a number, the method will call tidyOptSetInt.
  • If the type of the option is boolean and the provided value is boolean, the method will call tidyOptSetBool.
  • If the value is null, tidyOptSetValue will be called with an empty string.
  • In all other cases, it calls tidyOptSetValue, which in turn uses the libtidy option parser. This in particular allows parsing enumerated options. The passed value is the result of JavaScript conversion to string. One effect of this is that it is possible to pass a boolean value to an AutoBool option and obtain the expected result.

Note that tidyOptSetValue may not reject all values you'd expect it would. For example, boolean options are judged by their first non-whitespace letter, and accept the auto keyword just like options of type AutoBool.

TidyDoc.options

Getter and setter pair.

The getter will build a configuration dictionary of all options. Each element of the dictionary corresponds to one option, with the key given in underscore_separated format. Reading that element implies a call to optGet, while writing it corresponds to calling optSet.

The setter will take the assigned value and merge its elements into the configuration one at a time. This merging goes through optSet, so keys can use any of the allowed option naming schemes.

TidyDoc.parseBuffer(buf, [cb])

Asynchronous method binding tidyParseBuffer. Callback follows the callback convention, i.e. have signature function(exception, {errlog})

  • buf – must be a buffer, other input will be rejected.
  • cb – callback following the callback convention, i.e. with signature function(exception, {errlog}) or omitted to return a promise.

It is suggested to use this method for strings as well, since JavaScript strings come with a length information and may contain \0 characters while C strings are null-terminated. Make sure to leave the input-encoding option at its default of UTF8 if the input is Buffer(str).

TidyDoc.parseBufferSync(buf)

Synchronous method binding tidyParseBuffer. Returns any diagnostics encountered during operation, as a string.

  • buf – must be a buffer, other input will be rejected.

It is suggested to use this method for strings as well, since JavaScript strings come with a length information and may contain \0 characters while C strings are null-terminated. Make sure to leave the input-encoding option at its default of UTF8 if the input is Buffer(str).

TidyDoc.runDiagnostics([cb])

Asynchronous method binding tidyRunDiagnostics. Callback follows the callback convention, i.e. have signature function(exception, {errlog}) or is omitted to return a promise.

TidyDoc.runDiagnosticsSync()

Synchronous method binding tidyRunDiagnostics. Returns any diagnostics encountered during operation, as a string.

TidyDoc.saveBuffer([cb])

Asynchronous method binding tidySaveBuffer.

  • cb – callback following the callback convention, i.e. with signature function(exception, {errlog, output}) where output is a buffer, or omitted to return a promise.

TidyDoc.saveBufferSync()

Synchronous method binding tidySaveBuffer. Returns the resulting buffer as a string.

TidyDoc.tidyBuffer(buf, [cb])

Asynchronous method performing the four basic steps in a row:

  1. tidyParseBuffer
  2. tidyCleanAndRepair
  3. tidyRunDiagnostics
  4. tidySaveBuffer
  • buf – must be a buffer, other input will be rejected.
  • cb – callback following the callback convention, i.e. with signature function(exception, {errlog, output}) where output is a buffer, or omitted to return a promise.

TidyOption()

Although part of the public interface, this constructor is not meant to be called from JavaScript. Its prototype is open to extension, though.

One can obtain objects of this class from TidyDoc.getOption, TidyDoc.getOptionList or TidyDoc.optGetDocLinksList.

The properties of this type are implemented as getters, so actually retrieving these values may incur some performance cost, and retrieving the same property twice may lead to different but equivalent objects.

TidyOption.category

The category of the option, as a string. Will be one of "Markup", "Diagnostics", "PrettyPrint", "Encoding" or "Miscellaneous".

Wraps tidyOptGetCategory.

TidyOption.default

The default value of the option. The returned type depends on the type of the option. Contrary to optGet, the default will be a number for enumerated types, not a string, since tidyOptGetCurrPick has no matching tidyOptGetDefaultPick or similar.

Wraps tidyOptGetDefaultBool, tidyOptGetDefaultInt or tidyOptGetDefault.

TidyOption.id

The numeric identifier identifying this option. The returned number is not portable across different versions, different builds and perhaps even different machines. So be careful using this, preferably only within a single process. In general, the name is preferable.

Wraps tidyOptGetId.

TidyOption.name

The name of the option, in its hyphen-separated default form.

Wraps tidyOptGetName.

TidyOption.pickList

List of possible values for enumerated properties, as an array of strings. Otherwise the list will be empty.

Wraps tidyOptGetPickList and tidyOptGetNextPick.

TidyOption.readOnly

Indicates whether the property is read-only.

Wraps tidyOptIsReadOnly.

TidyOption.toString()

Returns the name of the option.

TidyOption.type

Returns the type of the option, as a string. Will be one of "boolean", "integer", "string". Note that enumerated options, including those of type AutoBool, will be represented as type "integer".

Wraps tidyOptGetType.

compat

Elements of the compat namespace offer compatibility with other libtidy bindings for node.

compat.htmltidy

This offers a drop-in replacement for htmltidy and htmltidy2.

-var htmltidy = require("htmltidy2");
+var htmltidy = require("libtidy").compat.htmltidy;

compat.htmltidy.tidy(input, [opts], cb)

Asynchronous function.

Similar to tidyBuffer, but the arguments to the callback are different. In case of a non-serious error, the first argument will contain any diagnostic messages as a string, while the second argument holds the output, again as a string. If the show-warnings option is false (which is the default for this function), then in case of a successfully generated output an empty diagnostics string will be returned.

  • input – anything except a buffer will be converted to String and then turned into a buffer.
  • opts – a dictionary of libtidy options.
  • cb – callback with signature function(err, output), where err is an Error in case of a serious error, or a diagnostic string in case of less serious problems.

The function applies the following libtidy options by default:

  • show-warnings = no
  • tidy-mark = no
  • force-output = yes
  • quiet = no