pg_search 2.3.7 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 103352d5afaf431080a49411b6e7bce5c2d1edec6aa88da55913fb179ef02367
-  data.tar.gz: fea6642ba781bb1916f32d46fe25f829c34d27564c23674dde4c80f97a5a43db
+  metadata.gz: d337f465568b2cbd9bd1339db2800ebd9f8e36440c826128de97047221ff696a
+  data.tar.gz: 925270bc694ea367614dbf45988b88bd1e8fd33d8c9bee48e0a8cc286866a584
 SHA512:
-  metadata.gz: d550e544579fddb2ef4b2667a93624f9b293102db705e304b048bd0eaa328d908c3415028324a35e038353e7a47ac334e53e2a6f381abe2456de835c4d04c359
-  data.tar.gz: b896f972762290dda0d9e744680c707223188e6a5ceb05329cdc3479f302c1a18dd11b20bcd5ebffe66cc36143c182318b51e9e88e63463cfb55d7d0d8890d6b
+  metadata.gz: 652c592fe592367e820d0608f0e8d8108d8d4b734e09690d732d224414919b4f8aba80b54e100bc0d4c7e9c265c907ad7c425a4118070163981e2180bcf83723
+  data.tar.gz: c52bb869600f87bbecaa584eef713a3b34d55668d6e632277730209fc65999361a4d4d8f4e831ff4bfbb1d9d9d0a6f03127f6b5469ae7bca524b6d68d9e133f2

data/.github/workflows/ci.yml

@@ -6,15 +6,22 @@ on:
       - master
       - github-actions
   pull_request:
-    branches:
-      - master
   schedule:
     - cron: "0 18 * * 6" # Saturdays at 12pm CST
   workflow_dispatch:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   test:
+    name: Ruby ${{ matrix.ruby-version }} / Active Record ${{ matrix.active-record.label }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     services:
       postgres:
         image: postgres:latest
@@ -32,49 +39,43 @@ jobs:
       CI: true
       PGHOST: 127.0.0.1
       PGUSER: postgres
-      PGPASS: postgres
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2', '3.3']
-        active-record-version-env:
-          - ACTIVE_RECORD_VERSION="~> 6.1.0"
-          - ACTIVE_RECORD_VERSION="~> 7.0.0"
-          - ACTIVE_RECORD_VERSION="~> 7.1.0"
-          - ACTIVE_RECORD_VERSION="~> 7.2.0"
+        ruby-version: ["3.3", "3.4", "4.0"]
+        active-record:
+          - { label: "8.0", env: "ACTIVE_RECORD_VERSION=~> 8.0.0" }
+          - { label: "8.1", env: "ACTIVE_RECORD_VERSION=~> 8.1.0" }
         allow-failure: [false]
-        exclude:
-          - ruby-version: '3.0'
-            active-record-version-env: ACTIVE_RECORD_VERSION="~> 7.2.0"
         include:
-          - ruby-version: '3.3'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="main"
+          - ruby-version: "4.0"
+            active-record: { label: "main", env: "ACTIVE_RECORD_BRANCH=main" }
             allow-failure: true
-          - ruby-version: '3.3'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="7-2-stable"
+          - ruby-version: "4.0"
+            active-record: { label: "8-1-stable", env: "ACTIVE_RECORD_BRANCH=8-1-stable" }
             allow-failure: true
-          - ruby-version: '3.3'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="7-1-stable"
+          - ruby-version: "4.0"
+            active-record: { label: "8-0-stable", env: "ACTIVE_RECORD_BRANCH=8-0-stable" }
             allow-failure: true
-          - ruby-version: '3.3'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="7-0-stable"
-            allow-failure: true
-          - ruby-version: '3.3'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="6-1-stable"
+          - ruby-version: "ruby-head"
+            active-record: { label: "8.1", env: "ACTIVE_RECORD_VERSION=~> 8.1.0" }
             allow-failure: true
     continue-on-error: ${{ matrix.allow-failure }}
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true
-    - name: Set up test database
-      env:
-        PGPASSWORD: postgres
-      run: createdb pg_search_test
-    - name: Update bundle
-      run: ${{ matrix.active-record-version-env }} bundle update
-    - name: Run tests
-      run: ${{ matrix.active-record-version-env }} bundle exec rake
+      - uses: actions/checkout@v6
+      - name: Select ActiveRecord version
+        env:
+          ACTIVE_RECORD_ENV: ${{ matrix.active-record.env }}
+        run: echo "$ACTIVE_RECORD_ENV" >> "$GITHUB_ENV"
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+          cache-version: ${{ matrix.active-record.env }}
+      - name: Set up test database
+        env:
+          PGPASSWORD: postgres
+        run: createdb pg_search_test
+      - name: Run tests
+        run: bundle exec rake

data/.github/workflows/codeql.yml

@@ -0,0 +1,86 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+  schedule:
+    - cron: '28 0 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ubuntu-latest
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: ruby
+          build-mode: none
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

data/.gitignore

@@ -7,5 +7,4 @@
 /pkg/*
 /tmp/
 Gemfile.lock
-doc
 tags

data/.standard.yml

@@ -1,6 +1,6 @@
-ruby_version: 3.0
+ruby_version: 3.3
 
 plugins:
   - standard-performance
   - standard-rails:
-      target_rails_version: 6.1
+      target_rails_version: 8.0

data/CHANGELOG.md

@@ -1,6 +1,23 @@
 # pg_search changelog
 
-## 2.3.7
+## 2.4.0 - 2026-09-07
+
+* Drop support for Active Record 7.2
+* Replace internal SQL-string manipulation with composable Arel operations while preserving all existing use cases
+
+## 2.3.8 - 2026-08-10
+
+* Drop support for Ruby 3.0, 3.1, and 3.2
+* Drop support for Active Record 6.1, 7.0, and 7.1
+* Support Ruby 3.4 and 4.0
+* Support Active Record 8.0 and 8.1
+* Fix ordered searches and associated ordering that use the internal rank join (fatkodima)
+* Sanitize query characters introduced by unaccent normalization (Misha Doronin)
+* Support keyword arguments for dynamic rank and highlight accessors (Manuel Meurer)
+* Quote custom primary key and inheritance column identifiers in multisearch rebuild SQL
+* Improve documentation (Olli)
+
+## 2.3.7 - 2024-08-11
 
 * Drop support for Ruby 2.6 and 2.7
 * Drop support for Active Record 6.0 and earlier
@@ -11,7 +28,7 @@
 * add support for Arel::Nodes::SqlLiteral columns (Kyle Fazzari)
 * Improve documentation (Prima Aulia Gusta, Ross Baird, Andy Atkinson)
 
-## 2.3.6
+## 2.3.6 - 2022-01-07
 
 * Drop support for Ruby 2.5
 * Support Ruby 3.1
@@ -20,186 +37,186 @@
 * Optionally disable transaction when rebuilding documents (Travis Hunter)
 * Preserve columns when chaining ::with_pg_search_highlight (jcsanti)
 
-## 2.3.5
+## 2.3.5 - 2020-11-16
 
 * Add table of contents to README (Barry Woolgar)
 * Add support for Active Record 6.1
 
-## 2.3.4
+## 2.3.4 - 2020-10-10
 
 * Fix issue when setting various options directly on the `PgSearch` module while
   running with a threaded web server, such as Puma. (Anton Rieder)
 
-## 2.3.3
+## 2.3.3 - 2020-09-20
 
 * Drop support for Ruby < 2.5.
 * Use keyword argument for `clean_up` setting in `PgSearch::Multisearch.rebuild`.
 
-## 2.3.2
+## 2.3.2 - 2020-01-13
 
 * Autoload `PgSearch::Document` to prevent it from being loaded in projects that are not using multi-search.
 * Rebuilder should use `update_pg_search_document` if `additional_attributes` is set. (David Ramalho)
 
-## 2.3.1
+## 2.3.1 - 2019-12-22
 
 * Drop support for Active Record < 5.2.
 * Do not load railtie unless Rails::Railtie is defined, to avoid problem when loading alongside Action Mailer. (Adam Schwartz)
 
-## 2.3.0
+## 2.3.0 - 2019-07-13
 
 * Extract `PgSearch::Model` module.
 * Deprecate `include PgSearch`. Use `include PgSearch::Model` instead.
 
-## 2.2.0
+## 2.2.0 - 2019-05-26
 
 * Add `word_similarity` option to trigram search. (Severin Räz)
 
-## 2.1.7
+## 2.1.7 - 2019-04-20
 
 * Restore link to GitHub repository to original location.
 
-## 2.1.6
+## 2.1.6 - 2019-04-18
 
 * Update link to GitHub repository to new location.
 
-## 2.1.5
+## 2.1.5 - 2019-04-08
 
 * Drop support for Ruby < 2.4.
 
-## 2.1.4
+## 2.1.4 - 2019-01-26
 
 * Drop support for Ruby < 2.3.
 * Use `update` instead of deprecated `update_attributes`.
 * Remove explicit Arel dependency to better support Active Record 6 beta.
 
-## 2.1.3
+## 2.1.3 - 2018-12-09
 
 * Drop support for Ruby < 2.2
 * Disallow left/right single quotation marks in tsquery. (Fabian Schwahn) (#382)
 * Do not attempt to save an already-destroyed `PgSearch::Document`. (Oleg Dashevskii, Vokhmin Aleksei V) (#353)
 * Quote column name when rebuilding. (Jed Levin) (#379)
 
-## 2.1.2
+## 2.1.2 - 2017-12-25
 
 * Silence warnings in Rails 5.2.0.beta2. (Kevin Deisz)
 
-## 2.1.1
+## 2.1.1 - 2017-09-20
 
 * Support snake_case `ts_headline` options again. (with deprecation warning)
 
-## 2.1.0
+## 2.1.0 - 2017-07-29
 
 * Allow `ts_headline` options to be passed to `:highlight`. (Ian Heisters)
 * Wait to load `PgSearch::Document` until after Active Record has loaded. (Logan Leger)
 * Add Rails version to generated migrations. (Erik Eide)
 
-## 2.0.1
+## 2.0.1 - 2016-12-20
 
 * Remove require for generator that no longer exists. (Joshua Bartlett)
 
-## 2.0.0
+## 2.0.0 - 2016-12-19
 
 * Drop support for PostgreSQL < 9.2.
 * Drop support for Active Record < 4.2.
 * Drop support for Ruby < 2.1.
 * Improve performance of has_one and belongs_to associations. (Peter Postma)
 
-## 1.0.6
+## 1.0.6 - 2016-05-22
 
 * Add support for highlighting the matching portion of a search result. (Jose Galisteo)
 * Add `:update_if` option to control when PgSearch::Document gets updated. (Adam Becker)
 * Add `:additional_attributes` option for adding additional attributes to PgSearch::Document
 
-## 1.0.5
+## 1.0.5 - 2015-08-30
 
 * Clean up rank table aliasing. (Adam Milligan)
 * Fix issue when using `#with_pg_search_rank` across a join. (Reid Lynch)
 
-## 1.0.4
+## 1.0.4 - 2015-06-14
 
 * Assert valid options for features. (Janko Marohnić)
 * Enable chaining of pg_search scopes. (Nicolas Buduroi)
 
-## 1.0.3
+## 1.0.3 - 2015-05-11
 
 * Support STI models using a custom inheritance column. (Nick Doiron)
 
-## 1.0.2
+## 1.0.2 - 2015-05-04
 
 * Don’t use SQL to rebuild search documents when models are multisearchable against dynamic methods and not just columns. Iterate over each record with `find_each` instead.
 
-## 1.0.1
+## 1.0.1 - 2015-05-02
 
 * Call `.unscoped` on relation used to build subquery, to eliminate unnecessary JOINs. (Markus Doits)
 
-## 1.0.0
+## 1.0.0 - 2015-04-19
 
 * Support more `ActiveRecord::Relation` methods, such as `#pluck` and `#select` by moving search-related operations to subquery.
 * Generate index by default in migration for `pg_search_documents` table.
 * Start officially using [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html).
 
-## 0.7.9
+## 0.7.9 - 2015-02-04
 
 * Improve support for single table inheritance (STI) models. (Ewan McDougall)
 
-## 0.7.8
+## 0.7.8 - 2014-09-06
 
 * Stop inadvertently including binstubs for guard and rspec.
 
-## 0.7.7
+## 0.7.7 - 2014-09-05
 
 * Fix future compatibility with Active Record 4.2.
 
-## 0.7.6
+## 0.7.6 - 2014-07-16
 
 * Fix migration generator in Rails 3. (Andrew Marshall and Nora Lin)
 * Add `:only` option for limiting search fields per feature. (Jonathan Greenberg)
 
-## 0.7.5
+## 0.7.5 - 2014-07-15
 
 * Add option to make feature available only for sorting. (Brent Wheeldon)
 
-## 0.7.4
+## 0.7.4 - 2014-05-19
 
 * Fix which STI class name is used for searchable_type for PgSearch::Document. (Ewan McDougall)
 * Add support for non-standard primary keys. (Matt Beedle)
 
-## 0.7.3
+## 0.7.3 - 2014-01-26
 
 * Allow simultaneously searching using `:associated_against` and `:tsvector_column` (Adam Becker)
 
-## 0.7.2
+## 0.7.2 - 2013-11-20
 
 * Add :threshold option for configuring how permissive trigram searches are.
 
-## 0.7.1
+## 0.7.1 - 2013-11-20
 
 * Fix issue with {:using => :trigram, :ignoring => :accents} that generated
   bad SQL. (Steven Harman)
 
-## 0.7.0
+## 0.7.0 - 2013-07-05
 
 * Start requiring Ruby 1.9.2 or later.
 
-## 0.6.4
+## 0.6.4 - 2013-05-26
 
 * Fix issue with using more than two features in the same scope.
 
-## 0.6.3
+## 0.6.3 - 2013-05-12
 
 * Fix issues and deprecations for Active Record 4.0.0.rc1.
 
-## 0.6.2
+## 0.6.2 - 2013-04-20
 
 * Add workaround for issue with how ActiveRecord relations handle Arel OR
   nodes.
 
-## 0.6.1
+## 0.6.1 - 2013-04-08
 
 * Fix issue with Arel::InfixOperation that prevented #count from working,
   breaking pagination.
 
-## 0.6.0
+## 0.6.0 - 2013-04-02
 
 * Drop support for Active Record 3.0.
 * Address warnings in Ruby 2.0.
@@ -209,49 +226,49 @@
 * Support named schemas in pg_search:multisearch:rebuild. (Victor Olteanu)
 
 
-## 0.5.7
+## 0.5.7 - 2012-10-07
 
 * Fix issue with eager loading now that the Scope class has been removed.
   (Piotr Murach)
 
 
-## 0.5.6
+## 0.5.6 - 2012-09-29
 
 * PgSearch#multisearchable accepts :if and :unless for conditional inclusion
   in search documents table. (Francois Harbec)
 * Stop using array_to_string() in SQL since it is not indexable.
 
 
-## 0.5.5
+## 0.5.5 - 2012-09-16
 
 * Fix bug with single table inheritance.
 * Allow option for specifying an alternate function for unaccent().
 
 
-## 0.5.4
+## 0.5.4 - 2012-09-07
 
 * Fix bug in associated_against join clause when search scope is chained
   after other scopes.
 * Fix autoloading of PgSearch::VERSION constant.
 
 
-## 0.5.3
+## 0.5.3 - 2012-09-06
 
 * Prevent multiple attempts to create pg_search_document within a single
   transaction. (JT Archie & Trace Wax)
 
 
-## 0.5.2
+## 0.5.2 - 2012-09-06
 
 * Don't save twice if pg_search_document is missing on update.
 
 
-## 0.5.1
+## 0.5.1 - 2012-08-01
 
 * Add ability to override multisearch rebuild SQL.
 
 
-## 0.5
+## 0.5 - 2012-05-13
 
 * Convert migration rake tasks into generators.
 * Use rake task arguments for multisearch rebuild instead of environment
@@ -259,7 +276,7 @@
 * Always cast columns to text.
 
 
-## 0.4.2
+## 0.4.2 - 2012-05-09
 
 * Fill in timestamps correctly when rebuilding multisearch documents.
   (Barton McGuire)
@@ -269,7 +286,7 @@
 * Fix issue with :associated_against and non-text columns.
 
 
-## 0.4.1
+## 0.4.1 - 2012-02-13
 
 * Fix Active Record 3.2 deprecation warnings. (Steven Harman)
 
@@ -277,18 +294,18 @@
   defined.
 
 
-## 0.4
+## 0.4 - 2011-12-15
 
 * Add ability to search again tsvector columns. (Kris Hicks)
 
 
-## 0.3.4
+## 0.3.4 - 2011-11-25
 
 * Fix issue with {:using => {:tsearch => {:prefix => true}}} and hyphens.
 * Get tests running against PostgreSQL 9.1 by using CREATE EXTENSION
 
 
-## 0.3.3
+## 0.3.3 - 2011-10-22
 
 * Backport array_agg() aggregate function to PostgreSQL 8.3 and earlier.
   This fixes :associated_against searches.
@@ -298,18 +315,18 @@
   earlier.
 
 
-## 0.3.2
+## 0.3.2 - 2011-10-18
 
 * Fix :prefix search in PostgreSQL 8.x
 * Disable {:ignoring => :accents} in PostgreSQL 8.x
 
 
-## 0.3.1
+## 0.3.1 - 2011-09-08
 
 * Fix syntax error in generated dmetaphone migration. (Max De Marzi)
 
 
-## 0.3
+## 0.3 - 2011-09-06
 
 * Drop Active Record 2.0 support.
 * Add PgSearch.multisearch for cross-model searching.
@@ -319,16 +336,16 @@
 * Add :any_word option to :tsearch which uses OR between query terms instead
   of AND. (Fernando Espinosa)
 
-## 0.2.2
+## 0.2.2 - 2013-07-08
 
 * Fix a compatibility issue between Ruby 1.8.7 and 1.9.3 when using Rails 2
   (James Badger)
 
-## 0.2.1
+## 0.2.1 - 2011-12-15
 
 * Backport support for searching against tsvector columns (Kris Hicks)
 
-## 0.2
+## 0.2 - 2011-05-11
 
 * Set dictionary to :simple by default for :tsearch. Before it was unset,
   which would fall back to PostgreSQL's default dictionary, usually
@@ -337,22 +354,22 @@
 * Improve performance of :associated_against by only doing one INNER JOIN
   per association
 
-## 0.1.1
+## 0.1.1 - 2011-01-20
 
 * Fix a bug with dmetaphone searches containing " w " (which dmetaphone maps
   to an empty string)
 
-## 0.1
+## 0.1 - 2011-01-18
 
 * Change API to {:ignoring => :accents} from {:normalizing => :diacritics}
 * Improve documentation
 * Fix bug where :associated_against would not work without an :against
   present
 
-## 0.0.2
+## 0.0.2 - 2011-01-14
 
 * Fix gem ownership.
 
-## 0.0.1
+## 0.0.1 - 2011-01-14
 
 * Initial release.

data/CONTRIBUTING.md

@@ -12,7 +12,7 @@ Don't be discouraged if the maintainers ask you to change your code. We are alwa
 
 Our automated tests start by updating all gems to their latest version. This is by design, because we want to be proactive about compatibility with other libraries. You can do the same by running `bundle update` at any time. To test against a specific version of Active Record, you can set the `ACTIVE_RECORD_VERSION` environment variable.
 
-    $ ACTIVE_RECORD_VERSION=5.0 bundle update
+    $ ACTIVE_RECORD_VERSION="~> 8.0.0" bundle update
 
 Run the tests by running `bundle exec rake`, or `bin/rake` if you use Bundler binstubs. 
 

data/Gemfile

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source "https://rubygems.org", cooldown: 7
 
 gemspec
 
@@ -14,15 +14,17 @@ end
 
 gem "activerecord", ENV.fetch("ACTIVE_RECORD_VERSION", nil) if ENV["ACTIVE_RECORD_VERSION"] # standard:disable Bundler/DuplicatedGem
 
+gem "benchmark"
 gem "debug"
 gem "irb"
+gem "mutex_m"
 gem "rake"
 gem "rspec"
+gem "ruby-lsp"
 gem "simplecov"
 gem "simplecov-lcov"
 gem "standard", require: false
 gem "standard-rails", require: false
 gem "standard-rspec", require: false
-gem "undercover"
 gem "warning"
 gem "with_model"

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010–2022 Casebook, PBC <http://www.casebook.net>
+Copyright (c) 2010–2026 Casebook, PBC <http://www.casebook.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal