diff --git a/README.md b/README.md index 98b1e4a..355a508 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# [@xslet/xslutil][repo-url] ![Version][ver-image] [![Github.io][io-image]][io-url] [![MIT License][mit-image]][mit-url] +# [@xslet/xslutil][repo-url] [![Version][ver-image]][api-url] [![Github.io][io-image]][io-url] [![MIT License][mit-image]][mit-url] A set of utilities for XSLT programs on Web browsers. @@ -12,222 +12,9 @@ This program is written in XSLT 1.0. The API document of this program is [here][api-url]. -## List - -* [`ut:count`](#usage_count) -* [`ut:ends_with`](#usage_ends_with) -* [`ut:get_dir_from_url`](#usage_get_dir_from_url) -* [`ut:get_namespace_uri`](#usage_get_namespace_uri) -* [`ut:get_xsl_url`](#usage_get_xsl_url) -* [`ut:is_absolute_url`](#usage_is_absolute_url) -* [`ut:repeat`](#usage_repeat) -* [`ut:replace`](#usage_replace) -* [`ut:trim`](#usage_trim) -* [`ut:trim_start`](#usage_trim_start) -* [`ut:trim_end`](#usage_trim_end) -* [`ut:validate`](#usage_validate) - ## Usage - -### `ut:count` - -Counts a *target* substring in a *string*. -This function returns a positive number or zero. - -``` - - - ABAABCA - AB - -``` - - -### `ut:ends_with` - -Tests that a *string* ends with a *suffix* substring. -This function returns `$ut:true` (=`'true'`) or empty. - -``` - - - ABC - BC - -``` - - -### `ut:get_dir_from_url` - -Returns a parent url of *url*. -This function returns a url string or `'.'`. - -``` - - - https://domain/dir/file - -``` - - -### `ut:get_namespace_uri` - -Returns the namespace URI of *prefix*. -This function returns a URI string, or `$ut:unknown_namespace`. - -``` - - - ut - -``` - - -**NOTE:** -Firefox does not support the XPath's namespace axis: `namespace::*`. -So, on Firefox, this function finds an element using the target namespace then applys `namespace-uri()` to it. -If such an element is not found, this function returns `$ut:unknown_namespace`. - - - -### `ut:get_xsl_url` - -Returns the XSL URL from the processing instruction or the specified *pi*. - -``` - - -... - - - - - - - -``` - - -### `ut:is_absolute_url` - -Tests that a *url* string is an absolute URL. -This function returns `$ut:true` (= `'true'`) or empty. - -``` - - - https://aaa/bbb/ccc - - - - - aaa/bbb/ccc - -``` - - -### `ut:repeat` - -Repeats a *string* *count* times. - -``` - - - ABC - 3 - -``` - - -### `ut:replace` - -Replaces all *target* substrings to *replacement* in a *string*. - -``` - - - ABCABC - BC - de - -``` - - -### `ut:trim` - -Trims *target* substrings in both side of *string*. - -``` - - - ABC - - - - - ## ABC ### - # - -``` - - -### `ut:trim_start` - -Trims *target* substrings in start of *string*. - -``` - - - ABC - - - - - ## ABC ### - # - -``` - - -### `ut:trim_end` - -Trims *target* substrings in end of *string*. - -``` - - - ABC - - - - - ## ABC ### - # - -``` - - -### `ut:validate` - -Tests a *string* contains one of character in *forbidden*. If *forbidden* substrings are contained, this function returns a *default* string. Otherwise this function returns the tested *string*. - -``` - - - abc - c - def - - - - - abc - z - def - -``` +The document about usage of xslutil is [here][usage-url]. ## License @@ -245,3 +32,4 @@ See the file LICENSE in this distribution for more details. [mit-image]: https://img.shields.io/badge/license-MIT-green.svg [mit-url]: https://opensource.org/licenses/MIT [api-url]: https://xslet.github.io/xslutil/api/xslutil.xml +[usage-url]: https://xslet.github.io/xslutil/#usage diff --git a/docs/index.css b/docs/index.css index e327b47..505e359 100644 --- a/docs/index.css +++ b/docs/index.css @@ -89,14 +89,14 @@ section > h2 { section > h3 { font-size: 1.2rem; padding: 0.5rem 0rem 0.5rem 1rem; - margin: 2rem 0rem 0rem; + margin: 0rem; } section > p { margin-left: 1.3rem; } -section > ul { - margin-left: 2.3rem; +section > ol, section > ul { + margin-left: 2.5rem; padding: 0rem; } @@ -186,3 +186,15 @@ a#sass::after { background-size: auto 0.9rem; background-repeat: no-repeat; } + +section.call > h4 { + font-size: 1rem; + padding: 1rem 0rem 0rem 1rem; + margin: 0rem; +} +section.call > p { + margin-left: 1.8rem; +} +section.call > div.code { + margin-left: 1.8rem; +} diff --git a/docs/index.html b/docs/index.html index 2963cf2..c818b02 100644 --- a/docs/index.html +++ b/docs/index.html @@ -45,45 +45,242 @@

About xslutil

Usage

-To import xslutil.xsl into your XSL application or library, the following handworks are needed. +This section explains how to import xslutil and call its templates in your XSL application or library.

-
    -
  1. -

    + +

    +

    Import xslutil

    +

    +To import xslutil.xsl into another XSL file, the following handworks are needed. +

    +
      +
    1. +

      Add the namespace declaration of xslutil in a XSL file. The namespace of xslutil is "https://github.com/xslet/2020/xslutil". -

      -
      +

      +
      <xsl:stylesheet version="1.0"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:ut="https://github.com/xslet/2020/xslutil"> <!-- This! -->
        ...
      -
      -
    2. -
    3. -

      + +

    4. +
    5. +

      Add a import element of xslutil in the XSL file. -

      -
      +

      +
        ...
        <xsl:import href="./xslutil.xsl"/>
        ...
      +
      +
    6. +
    +
    + +
    +

    Call templates

    +

    +xslutil provides the following named-templates: +

    + + +
    + +

    ut:count

    +

    +Counts a target substring in a string. This function returns a positive number or zero. +

    +
    +
    <!-- Counts 'AB' in 'ABAAABCA' then return 2 -->
    +
    <xsl:call-template name="ut:count">
    +
      <xsl:with-param name="string">ABAABCA</xsl:with-param>
    +
      <xsl:with-param name="target">AB</xsl:with-param>
    +
    </xsl:call-template>
    -
  2. -
  3. + + +

    ut:ends_with

    -Then, you can use named-templates of xslutil in the XSL file with xsl:call-template. +Tests that a string ends with a suffix substring. This function returns $ut:true (='true') or empty.

    -
      ...
    -
      <xsl:call-template name="ut:count"> -
        <xsl:with-param name="string" select="..."/> -
        <xsl:with-param name="target" select="..."/> -
      </xsl:call-template> -
      ...
    +
    <!-- Tests that 'ABC' ends with 'BC' then return 'true' -->
    +
    <xsl:call-template name="ut:ends_with">
    +
      <xsl:with-param name="string">ABC</xsl:with-param>
    +
      <xsl:with-param name="suffix">BC</xsl:with-param>
    +
    </xsl:call-template>
    -
  4. -
+ +

ut:get_dir_from_url

+

+Returns a parent url of url. This function returns a url string or '.'. +

+
+
<!-- Returns 'https://domain/dir/' from 'https://domain/dir/file' -->
+
<xsl:call-template name="ut:get_dir_from_url">
+
  <xsl:with-param name="url">https://domain/dir/file</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:get_namespace_url

+

+Returns the namespace URI of prefix. This function returns a URI string, or $ut:unknown_namespace. +

+
+
<!-- Returns 'https://github.com/xslet/2020/xslutil' which is the namespace URI of the prefix 'ut'. -->
+
<xsl:call-template name="ut:get_namespace_uri">
+
  <xsl:with-param name="prefix">ut</xsl:with-param>
+
</xsl:call-template>
+
+

+NOTE: Firefox does not support the XPath's namespace axis: `namespace::*`. So, on Firefox, this function finds an element using the target namespace then applys `namespace-uri()` to it. If such an element is not found, this function returns `$ut:unknown_namespace`. +

+ +

ut:get_xsl_url

+

+Returns the XSL URL from the processing instruction or the specified pi. +

+
+
<?xml version="1.0" encoding="utf-8"?>
+
<?xml-styesheet type="application/xml" href="https://domain/path/to/file.xsl"?>
+
...
+
<!-- Returns 'https://domain/path/to/file.xsl' -->
+
<xsl:call-template name="ut:get_xsl_url"/>
+
 
+
<!-- Returns 'path/to/file.xsl' -->
+
<xsl:call-template name="ut:get_xsl_url">
+
  <xsl:with-param name="pi" select='<?xml-stylesheet type="text/xsl" href="path/to/file.xsl"?>'/>
+
</xsl:call-template>
+
+ +

ut:is_absolute_url

+

+Tests that a url string is an absolute URL. This function returns $ut:true (= 'true') or empty. +

+
+
<!-- Tests if 'https://aaa/bbb/ccc' is absolute, then returns 'true' -->
+
<xsl:call-template name="ut:is_absolute_url">
+
  <xsl:with-param name="url">https://aaa/bbb/ccc</xsl:with-param>
+
</xsl:call-template>
+
 
+
<!-- Tests if 'aaa/bbb/ccc' is absolute, then returns empty -->
+
<xsl:call-template name="ut:is_absolute_url">
+
  <xsl:with-param name="url">aaa/bbb/ccc</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:repeat

+

+Repeats string count times. +

+
+
<!-- Returns 'ABCABCABC' -->
+
<xsl:call-template name="ut:repeat">
+
  <xsl:with-param name="string">ABC</xsl:with-param>
+
  <xsl:with-param name="count">3</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:replace

+

+Replaces all target substrings to replacement in string. +

+
+
<!-- Returns 'AdeAde' -->
+
<xsl:call-template name="ut:replace">
+
  <xsl:with-param name="string">ABCABC</xsl:with-param>
+
  <xsl:with-param name="target">BC</xsl:with-param>
+
  <xsl:with-param name="target">de</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:trim

+

+Trims target substrings in both side of string. +

+
+
<!-- Returns 'ABC' -->
+
<xsl:call-template name="ut:trim">
+
  <xsl:with-param name="string"> ABC </xsl:with-param>
+
</xsl:call-template>
+
 
+
<!-- Returns ' ABC ' -->
+
<xsl:call-template name="ut:trim">
+
  <xsl:with-param name="string">## ABC ###</xsl:with-param>
+
  <xsl:with-param name="target">#</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:trim_start

+

+Trims target substrings in start of string. +

+
+
<!-- Returns 'ABC ' -->
+
<xsl:call-template name="ut:trim_start">
+
  <xsl:with-param name="string"> ABC </xsl:with-param>
+
</xsl:call-template>
+
 
+
<!-- Returns ' ABC ###' -->
+
<xsl:call-template name="ut:trim_start">
+
  <xsl:with-param name="string">## ABC ###</xsl:with-param>
+
  <xsl:with-param name="target">#</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:trim_end

+

+Trims target substrings in end of string. +

+
+
<!-- Returns ' ABC' -->
+
<xsl:call-template name="ut:trim_end">
+
  <xsl:with-param name="string"> ABC </xsl:with-param>
+
</xsl:call-template>
+
 
+
<!-- Returns '## ABC ' -->
+
<xsl:call-template name="ut:trim_end">
+
  <xsl:with-param name="string">## ABC ###</xsl:with-param>
+
  <xsl:with-param name="target">#</xsl:with-param>
+
</xsl:call-template>
+
+ +

ut:validate

+

+Tests string contains one of character in forbidden. If forbidden substrings are contained, this function returns a default string. Otherwise this function returns the tested string. +

+
+
<!-- Returns 'def' -->
+
<xsl:call-template name="ut:validate">
+
  <xsl:with-param name="string">abc</xsl:with-param>
+
  <xsl:with-param name="forbidden">c</xsl:with-param>
+
  <xsl:with-param name="default">def</xsl:with-param>
+
</xsl:call-template>
+
 
+
<!-- Returns 'abc' -->
+
<xsl:call-template name="ut:validate">
+
  <xsl:with-param name="string">abc</xsl:with-param>
+
  <xsl:with-param name="forbidden">z</xsl:with-param>
+
  <xsl:with-param name="default">def</xsl:with-param>
+
</xsl:call-template>
+
+
+