DefinitelyTyped/he/he.d.ts

// Type definitions for he v0.5.0
// Project: https://github.com/mathiasbynens/he
// Definitions by: Simon Edwards <https://github.com/sedwards2009>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

// he - "HTML Entities" - A high quality pair of HTML encode and decode functions.

declare module "he" {
  
    var version: string;
    
    interface EncodeOptions {
        /**
        * The default value for the useNamedReferences option is false. This
        * means that encode() will not use any named character references
        * (e.g. &copy;) in the output — hexadecimal escapes (e.g. &#xA9;) will
        * be used instead. Set it to true to enable the use of named references.
        */
        useNamedReferences?: boolean;
        
        /**
        * The default value for the encodeEverything option is false. This means
        * that encode() will not use any character references for printable ASCII
        * symbols that don’t need escaping. Set it to true to encode every symbol
        * in the input string. When set to true, this option takes precedence over
        * allowUnsafeSymbols (i.e. setting the latter to true in such a case has
          * no effect).
        */
       encodeEverything?: boolean;
        
       /**
        * The default value for the strict option is false. This means that
        * encode() will encode any HTML text content you feed it, even if it
        * contains any symbols that cause parse errors. To throw an error when such
        * invalid HTML is encountered, set the strict option to true. This option
        * makes it possible to use he as part of HTML parsers and HTML validators.
        */
        strict?: boolean;
        
        /**
        * The default value for the allowUnsafeSymbols option is false. This means
        * that characters that are unsafe for use in HTML content (&, <, >, ", ',
        * and `) will be encoded. When set to true, only non-ASCII characters will
        * be encoded. If the encodeEverything option is set to true, this option
        * will be ignored.
        */
        allowUnsafeSymbols?: boolean;
    }
    
    interface Encode {
        /**
        * Encode a string of text
        *
        * This function takes a string of text and encodes (by default) any symbols
        * that aren’t printable ASCII symbols and &, <, >, ", ', and `, replacing
        * them with character references.
        *
        * As long as the input string contains allowed code points only, the return
        * value of this function is always valid HTML. Any (invalid) code points
        * that cannot be represented using a character reference in the input are
        * not encoded.
        */
        (text: string, options?: EncodeOptions): string;
        
        options: EncodeOptions;
    }
    var encode: Encode;
    
    interface DecodeOptions {
        /**
         * The default value for the isAttributeValue option is false. This means
         * that decode() will decode the string as if it were used in a text
         * context in an HTML document. HTML has different rules for parsing
         * character references in attribute values — set this option to true to
         * treat the input string as if it were used as an attribute value.
         */
        isAttributeValue?: boolean;
        
        /**
         * The default value for the strict option is false. This means that
         * decode() will decode any HTML text content you feed it, even if it
         * contains any entities that cause parse errors. To throw an error when
         * such invalid HTML is encountered, set the strict option to true. This
         * option makes it possible to use he as part of HTML parsers and HTML
         * validators.
         */
        strict?: boolean;
    }
    
    interface Decode {
        /**
         * Decode a string of HTML text
         *
         * This function takes a string of HTML and decodes any named and numerical
         * character references in it using the algorithm described in section
         * 12.2.4.69 of the HTML spec.
         */
        (html: string, options?: DecodeOptions): string;
        
        options: DecodeOptions;
    }
    var decode: Decode;
    
    /**
     * Escape XML entities
     *
     * This function takes a string of text and escapes it for use in text
     * contexts in XML or HTML documents. Only the following characters are
     * escaped: &, <, >, ", ', and `.
     */
    function escape(text: string): string;
    
    var unescape: Decode;
}