dba/util  library module
UP

Summary

Utility functions.
Authors
  • Christian Grün, BaseX Team 2005-23, BSD License
Related documents
ViewDescriptionFormat
xqdocxqDoc xml file from the source modulexml
xqparsexqparse xml file from the source modulexml

Imports

This module is imported by 29 modules. It imports 2 modules.

dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/files 2 3 4 5 6 7 8
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/databases 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
dba/files 2 3 4 5 6 7 8
dba/files 2 3 4 5 6 7 8
dba/files 2 3 4 5 6 7 8
dba/users 2 3 4 5 6 7
dba/users 2 3 4 5 6 7
dba/users 2 3 4 5 6 7
dba/users 2 3 4 5 6 7
dba/users 2 3 4 5 6 7
imports
dba/util
imports

Variables

3.1 $util:BACKUP-REGEX

Summary
Regular expression for backups.
Type
Source ( 1 lines)
variable $util:BACKUP-REGEX := '^(.*)-(\d{4}-\d\d-\d\d)-(\d\d)-(\d\d)-(\d\d)$'

3.2 $util:BACKUP-ZIP-REGEX

Summary
Regular expression for backups.
Type
Source ( 1 lines)
variable $util:BACKUP-ZIP-REGEX := '^(.*)-(\d{4}-\d\d-\d\d)-(\d\d)-(\d\d)-(\d\d)\.zip$'

Functions

4.1 util:capitalize

Arities: #1

Summary
Capitalizes a string.
Signatures
util:capitalize ( $string as xs:string ) as xs:string
Parameters
  • string as xs:string string
Return
  • xs:string capitalized string
Invoked by 0 functions from 0 modules
    Source ( 5 lines)
    function util:capitalize(
      $string  as xs:string
    ) as xs:string {
      upper-case(substring($string, 1, 1)) || substring($string, 2)
    }

    4.2 util:chop

    Arities: #2

    Summary
    Chops a string result to the maximum number of allowed characters.
    Signatures
    util:chop ( $string as xs:string, $max as xs:integer ) as xs:string
    Parameters
    • string as xs:string string
    • max as xs:integer maximum number of characters
    Return
    • xs:string string
    Invoked by 0 functions from 0 modules
      Source ( 10 lines)
      function util:chop(
        $string  as xs:string,
        $max     as xs:integer
      ) as xs:string {
        if(string-length($string) > $max) then (
          substring($string, 1, $max) || '...'
        ) else (
          $string
        )
      }

      4.3 util:end

      Arities: #2

      Summary
      Returns the index of the last result to generate.
      Signatures
      util:end ( $page as xs:integer, $sort as xs:string ) as xs:integer
      Parameters
      • page as xs:integer current page
      • sort as xs:string sort key
      Return
      • xs:integer last result
      Invoked by 0 functions from 0 modules
        Source ( 10 lines)
        function util:end(
          $page  as xs:integer,
          $sort  as xs:string
        ) as xs:integer {
          if($page and not($sort)) then (
            $page * options:get($options:MAXROWS)
          ) else (
            999999999
          )
        }

        4.4 util:info

        Arities: #3

        Summary
        Returns a count info for the specified items.
        Signatures
        util:info ( $items as item()*, $name as xs:string, $action as xs:string ) as xs:string
        Parameters
        • items as item()* items
        • name as xs:string name of item (singular form)
        • action as xs:string action label (past tense)
        Return
        • xs:string result
        Invoked by 0 functions from 0 modules
          Source ( 8 lines)
          function util:info(
            $items   as item()*,
            $name    as xs:string,
            $action  as xs:string
          ) as xs:string {
            let $count := count($items)
            return $count || ' ' || $name || (if($count != 1) then 's were ' else ' was ') || $action || '.'
          }

          4.5 util:item-join

          Arities: #2

          Summary
          Joins sequence entries.
          Signatures
          util:item-join ( $items as item()*, $sep as item() ) as item()*
          Parameters
          • items as item()* items
          • sep as item() separator
          Return
          • item() * result
          Invoked by 0 functions from 0 modules
            Source ( 7 lines)
            function util:item-join(
              $items  as item()*,
              $sep    as item()
            ) as item()* {
              for $item at $pos in $items
              return ($sep[$pos > 1], $item)
            }

            4.6 util:query

            Arities: #2

            Summary
            Evaluates a query and returns the result.
            Signatures
            util:query ( $query as xs:string?, $context as item()? ) as xs:string
            Parameters
            • query as xs:string? query string
            • context as item()? initial context item (can be empty)
            Return
            • xs:string serialized result of query
            Invoked by 0 functions from 0 modules
              Source ( 8 lines)
              function util:query(
                $query    as xs:string?,
                $context  as item()?
              ) as xs:string {
                let $bindings := $context ! map { '': $context }
                let $result := xquery:eval($query, $bindings, util:query-options())
                return util:serialize($result)
              }

              4.7 util:query-options

              Arities: #0P

              Summary
              Returns the options for evaluating a query.
              Signatures
              util:query-options ( ) as map(*)
              Return
              • map(*) options
              Invoked by 0 functions from 0 modules
                Annotations (1)
                %private()
                Source ( 8 lines)
                function util:query-options() as map(*) {
                  map {
                    'timeout'   : options:get($options:TIMEOUT),
                    'memory'    : options:get($options:MEMORY),
                    'permission': options:get($options:PERMISSION),
                    'base-uri'  : config:directory() || '/' || config:query()
                  }
                }

                4.8 util:redirect

                Arities: #2U

                Summary
                Convenience function for redirecting to another page from update operations.
                Signatures
                util:redirect ( $url as xs:string, $params as map(*) ) as empty-sequence
                Parameters
                • url as xs:string URL
                • params as map(*) query parameters
                Return
                • empty-sequence
                Invoked by 0 functions from 0 modules
                  Annotations (1)
                  %updating()
                  Source ( 6 lines)
                  function util:redirect(
                    $url     as xs:string,
                    $params  as map(*)
                  ) as empty-sequence() {
                    update:output(web:redirect($url, $params))
                  }

                  4.9 util:serialize

                  Arities: #1

                  Summary
                  Finalizes the result of an evaluated query.
                  Signatures
                  util:serialize ( $result as item()* ) as xs:string
                  Parameters
                  • result as item()* query result
                  Return
                  • xs:string empty sequence
                  Invoked by 0 functions from 0 modules
                    Source ( 13 lines)
                    function util:serialize(
                      $result  as item()*
                    ) as xs:string {
                      (: serialize more characters than requested, because limit represents number of bytes :)
                      let $limit := options:get($options:MAXCHARS)
                      let $indent := options:get($options:INDENT)
                      let $string := serialize($result, map {
                        'limit': $limit * 2 + 1,
                        'method': 'basex',
                        'indent': $indent
                      })
                      return util:chop($string, $limit)
                    }

                    4.10 util:start

                    Arities: #2

                    Summary
                    Returns the index of the first result to generate.
                    Signatures
                    util:start ( $page as xs:integer, $sort as xs:string ) as xs:integer
                    Parameters
                    • page as xs:integer current page
                    • sort as xs:string sort key
                    Return
                    • xs:integer last result
                    Invoked by 0 functions from 0 modules
                      Source ( 10 lines)
                      function util:start(
                        $page  as xs:integer,
                        $sort  as xs:string
                      ) as xs:integer {
                        if($page and not($sort)) then (
                          ($page - 1) * options:get($options:MAXROWS) + 1
                        ) else (
                          1
                        )
                      }

                      4.11 util:update-query

                      Arities: #1U

                      Summary
                      Runs an updating query.
                      Signatures
                      util:update-query ( $query as xs:string? ) as empty-sequence
                      Parameters
                      • query as xs:string? query string
                      Return
                      • empty-sequence empty sequence
                      Invoked by 0 functions from 0 modules
                        Annotations (1)
                        %updating()
                        Source ( 8 lines)
                        function util:update-query(
                          $query  as xs:string?
                        ) as empty-sequence() {
                          xquery:eval-update($query, (), util:query-options()),
                          
                          let $result := update:cache(true())
                          return update:output(util:serialize($result))
                        }

                        Namespaces

                        The following namespaces are defined:

                        PrefixUri
                        configdba/config
                        optionsdba/options
                        updatehttp://basex.org/modules/update
                        utildba/util
                        webhttp://basex.org/modules/web
                        xqueryhttp://basex.org/modules/xquery
                        xshttp://www.w3.org/2001/XMLSchema

                        6 RestXQ

                        None

                        Source Code

                        (:~
                         : Utility functions.
                         :
                         : @author Christian Grün, BaseX Team 2005-23, BSD License
                         :)
                        module namespace util = 'dba/util';
                        
                        import module namespace options = 'dba/options' at 'options.xqm';
                        import module namespace config = 'dba/config' at 'config.xqm';
                        
                        (:~ Regular expression for backups. :)
                        declare variable $util:BACKUP-REGEX := '^(.*)-(\d{4}-\d\d-\d\d)-(\d\d)-(\d\d)-(\d\d)$';
                        (:~ Regular expression for backups. :)
                        declare variable $util:BACKUP-ZIP-REGEX := '^(.*)-(\d{4}-\d\d-\d\d)-(\d\d)-(\d\d)-(\d\d)\.zip$';
                        
                        (:~
                         : Evaluates a query and returns the result.
                         : @param  $query    query string
                         : @param  $context  initial context item (can be empty)
                         : @return serialized result of query
                         :)
                        declare function util:query(
                          $query    as xs:string?,
                          $context  as item()?
                        ) as xs:string {
                          let $bindings := $context ! map { '': $context }
                          let $result := xquery:eval($query, $bindings, util:query-options())
                          return util:serialize($result)
                        };
                        
                        (:~
                         : Runs an updating query.
                         : @param  $query  query string
                         : @return empty sequence
                         :)
                        declare %updating function util:update-query(
                          $query  as xs:string?
                        ) as empty-sequence() {
                          xquery:eval-update($query, (), util:query-options()),
                          
                          let $result := update:cache(true())
                          return update:output(util:serialize($result))
                        };
                        
                        (:~
                         : Finalizes the result of an evaluated query.
                         : @param  $result  query result
                         : @return empty sequence
                         :)
                        declare function util:serialize(
                          $result  as item()*
                        ) as xs:string {
                          (: serialize more characters than requested, because limit represents number of bytes :)
                          let $limit := options:get($options:MAXCHARS)
                          let $indent := options:get($options:INDENT)
                          let $string := serialize($result, map {
                            'limit': $limit * 2 + 1,
                            'method': 'basex',
                            'indent': $indent
                          })
                          return util:chop($string, $limit)
                        };
                        
                        (:~
                         : Returns the options for evaluating a query.
                         : @return options
                         :)
                        declare %private function util:query-options() as map(*) {
                          map {
                            'timeout'   : options:get($options:TIMEOUT),
                            'memory'    : options:get($options:MEMORY),
                            'permission': options:get($options:PERMISSION),
                            'base-uri'  : config:directory() || '/' || config:query()
                          }
                        };
                        
                        (:~
                         : Returns the index of the first result to generate.
                         : @param  $page  current page
                         : @param  $sort  sort key
                         : @return last result
                         :)
                        declare function util:start(
                          $page  as xs:integer,
                          $sort  as xs:string
                        ) as xs:integer {
                          if($page and not($sort)) then (
                            ($page - 1) * options:get($options:MAXROWS) + 1
                          ) else (
                            1
                          )
                        };
                        
                        (:~
                         : Returns the index of the last result to generate.
                         : @param  $page  current page
                         : @param  $sort  sort key
                         : @return last result
                         :)
                        declare function util:end(
                          $page  as xs:integer,
                          $sort  as xs:string
                        ) as xs:integer {
                          if($page and not($sort)) then (
                            $page * options:get($options:MAXROWS)
                          ) else (
                            999999999
                          )
                        };
                        
                        (:~
                         : Chops a string result to the maximum number of allowed characters.
                         : @param  $string  string
                         : @param  $max     maximum number of characters
                         : @return string
                         :)
                        declare function util:chop(
                          $string  as xs:string,
                          $max     as xs:integer
                        ) as xs:string {
                          if(string-length($string) > $max) then (
                            substring($string, 1, $max) || '...'
                          ) else (
                            $string
                          )
                        };
                        
                        (:~
                         : Joins sequence entries.
                         : @param  $items  items
                         : @param  $sep    separator
                         : @return result
                         :)
                        declare function util:item-join(
                          $items  as item()*,
                          $sep    as item()
                        ) as item()* {
                          for $item at $pos in $items
                          return ($sep[$pos > 1], $item)
                        };
                        
                        (:~
                         : Returns a count info for the specified items.
                         : @param  $items   items
                         : @param  $name    name of item (singular form)
                         : @param  $action  action label (past tense)
                         : @return result
                         :)
                        declare function util:info(
                          $items   as item()*,
                          $name    as xs:string,
                          $action  as xs:string
                        ) as xs:string {
                          let $count := count($items)
                          return $count || ' ' || $name || (if($count != 1) then 's were ' else ' was ') || $action || '.'
                        };
                        
                        (:~
                         : Capitalizes a string.
                         : @param  $string  string
                         : @return capitalized string
                         :)
                        declare function util:capitalize(
                          $string  as xs:string
                        ) as xs:string {
                          upper-case(substring($string, 1, 1)) || substring($string, 2)
                        };
                        
                        (:~
                         : Convenience function for redirecting to another page from update operations.
                         : @param  $url     URL
                         : @param  $params  query parameters
                         :)
                        declare %updating function util:redirect(
                          $url     as xs:string,
                          $params  as map(*)
                        ) as empty-sequence() {
                          update:output(web:redirect($url, $params))
                        };