oj_windows 3.16.15

data/pages/Advanced.md

@@ -0,0 +1,38 @@
+# Advanced Features
+
+`oj_windows` is a high-performance JSON parser and serializer for Windows MSVC Ruby.
+It provides multiple serialization modes and alternative parsing APIs for different use cases.
+
+## Serialization Modes
+
+`oj_windows` has several `dump` modes which control how Ruby Objects are
+converted to JSON. These modes are set with the `:mode` option in either the
+default options or as one of the options to the `dump` method:
+
+- `:strict` - Strict JSON compliance
+- `:compat` - JSON gem compatibility
+- `:object` - Full Ruby object serialization
+- `:custom` - Customizable behavior
+- `:rails` - Rails/ActiveSupport integration
+- `:wab` - WAB format
+
+## Alternative Parser APIs
+
+### Oj::Doc API
+
+The fastest alternative parser API is the `Oj::Doc` API. It takes
+a completely different approach by opening a JSON document and providing calls
+to navigate around the JSON while it is open. This approach provides
+efficient access for large documents where only specific elements are needed.
+
+### Callback Parsers (SAJ/SCP)
+
+The `Oj::Saj` and `Oj::ScHandler` APIs are callback parsers that
+walk the JSON document depth first and make callbacks for each element.
+Both callback parsers are useful when only portions of the JSON are of
+interest, providing memory-efficient parsing of large documents.
+
+### Oj::Parser API
+
+The `Oj::Parser` API provides the best balance of performance and flexibility.
+See [Parser.md](Parser.md) for detailed benchmarks on Windows MSVC Ruby 3.4.8.

data/pages/Compatibility.md

@@ -0,0 +1,49 @@
+# Compatibility
+
+`oj_windows` is a **Windows-exclusive** fork optimized for the MSVC toolchain.
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Windows (MSVC) | ✅ Fully supported |
+| Windows (MinGW) | ❌ Not supported |
+| Linux | ❌ Not supported |
+| macOS | ❌ Not supported |
+
+## Ruby Version
+
+| Version | Status |
+|---------|--------|
+| Ruby 3.4.8+ (MSVC) | ✅ Fully supported |
+| Older Ruby versions | ❌ Not supported |
+
+## Requirements
+
+- **Ruby**: 3.4.8+ compiled with MSVC
+- **OS**: Windows 10/11 x64
+- **Compiler**: Visual Studio 2022+
+- **Architecture**: x64-mswin64_140
+
+## Rails Compatibility
+
+`oj_windows` is compatible with:
+
+| Rails Version | Status |
+|---------------|--------|
+| Rails 7.x | ✅ Supported |
+| Rails 8.x | ✅ Supported |
+
+Note: Rails projects may use [multi_json](https://github.com/intridea/multi_json) which will automatically prefer oj_windows if installed.
+
+## JSON Gem Compatibility
+
+`oj_windows` can serve as a drop-in replacement for the Ruby JSON gem:
+
+```ruby
+require 'oj_windows'
+
+Oj.mimic_JSON()
+```
+
+See [JsonGem.md](JsonGem.md) for full compatibility details.

data/pages/Custom.md

@@ -0,0 +1,37 @@
+# Custom Mode
+
+The `:custom` mode is the most configurable mode in `oj_windows` and honors almost all
+options. It provides maximum flexibility for JSON serialization and parsing.
+
+## Overview
+
+The `:custom` mode can be configured by:
+- Passing options to `Oj.dump()` and `Oj.load()` methods
+- Modifying the default options via `Oj.default_options`
+
+## Object Creation
+
+The ability to create Ruby objects from JSON object elements is supported via
+the `:create_additions` option.
+
+Special treatment is given to the `:create_id` option:
+
+| `:create_id` Value | Behavior |
+|--------------------|----------|
+| `"^o"` | Uses efficient internal encoding/decoding (recommended) |
+| Other values | Calls `to_json` and `create_json` methods (JSON gem compatible) |
+
+When using `"^o"`, the internal encoding is more efficient and does not require
+the target classes to implement `to_json` or `create_json` methods.
+
+## Configuration Example
+
+```ruby
+require 'oj_windows'
+
+Oj.default_options = {
+  mode: :custom,
+  create_additions: true,
+  create_id: '^o'
+}
+```

data/pages/Encoding.md

@@ -0,0 +1,61 @@
+# Object Mode Encoding
+
+Object mode in `oj_windows` provides fast Ruby object serialization and deserialization.
+In `:object` mode, JSON is generated following conventions that allow Class information
+and Object IDs for circular reference detection to be encoded in the JSON document.
+
+## Encoding Rules
+
+### Native Types
+JSON native types (`true`, `false`, `nil`, `String`, `Hash`, `Array`, `Number`) are
+encoded normally.
+
+### Symbols
+A Symbol is encoded as a JSON string with a preceding `':'` character.
+
+### Special Key Markers
+The `'^'` character denotes a special key value in a JSON Object sequence.
+
+| Key | Description |
+|-----|-------------|
+| `"^c"` | Ruby class. Example: `{"^c":"MyModule::MyClass"}` |
+| `"^t"` | Ruby Time. Example: `{"^t":1325775487.000000}` |
+| `"^o"` | Ruby Object with instance variables |
+| `"^O"` | Built-in/odd classes (Rational, Date, DateTime) |
+| `"^u"` | Ruby Struct. Example: `{"^u":["Range",1,7,false]}` |
+| `"^i"` | Object ID for circular reference detection |
+| `"^r"` | Reference to previously encoded Object |
+
+### Object Encoding Example
+
+```json
+{"^o":"MyClass","x":58,"y":"value"}
+```
+
+This represents an instance of `MyClass` with `@x = 58` and `@y = "value"`.
+
+### Circular References
+
+When `:circular` option is enabled:
+
+```json
+{"^o":"MyClass","^i":1,"x":3,"me":"^r1"}
+```
+
+The `"^i":1` assigns ID 1 to this object, and `"^r1"` references it.
+
+### Hash with Non-String Keys
+
+Hash entries with non-String/Symbol keys are encoded as:
+
+```json
+{"^#3":[2,5]}
+```
+
+Where the value is `[key, value]` and `^#3` is a hex identifier.
+
+### String Escaping
+
+Ruby Strings starting with `':'` or `'^'` are escaped:
+- `':'` becomes `'\u003a'`
+- `'^'` becomes `'\u005e'`

data/pages/InstallOptions.md

@@ -0,0 +1,20 @@
+# Oj Windows Install Options
+
+### Enable trace log
+
+```powershell
+gem install oj_windows -- --enable-trace-log
+```
+
+To enable Oj trace feature on Windows, use the `--enable-trace-log` option when installing the gem.
+Then, the trace logs will be displayed when `:trace` option is set to `true`.
+
+
+### Enable SIMD instructions
+
+```powershell
+gem install oj_windows -- --with-sse42
+```
+
+To enable the use of SIMD instructions in Oj, use the `--with-sse42` option when installing the gem.
+This will enable the use of the SSE4.2 instructions in the internal parser for improved performance.

data/pages/JsonGem.md

@@ -0,0 +1,60 @@
+# JSON Gem Compatibility
+
+`oj_windows` can serve as a drop-in replacement for the Ruby JSON gem with improved performance on Windows MSVC.
+
+## Quick Start
+
+To have `oj_windows` take over the `JSON` constant methods (`load`, `parse`, etc.):
+
+```ruby
+require 'oj_windows'
+
+Oj.mimic_JSON()
+```
+
+If your project already requires the `json` gem, call `Oj.mimic_JSON()` after the json gem has been loaded.
+
+## Optimized Type Encoding
+
+For faster encoding of common types, add them to Oj's optimized list:
+
+```ruby
+Oj.add_to_json(Array, BigDecimal, Complex, Date, DateTime, Exception, Hash, Integer, OpenStruct, Range, Rational, Regexp, Struct, Time)
+
+# Or add all available types:
+# Oj.add_to_json()
+```
+
+To revert a type to unoptimized encoding:
+
+```ruby
+Oj.remove_to_json(Rational)
+```
+
+## Supported Types
+
+The following types can be added for optimized encoding:
+
+| Type | Description |
+|------|-------------|
+| Array | Ruby arrays |
+| BigDecimal | Arbitrary precision decimals |
+| Complex | Complex numbers |
+| Date | Date objects |
+| DateTime | Date with time |
+| Exception | Exception objects |
+| Hash | Ruby hashes |
+| Integer | Integer values |
+| OpenStruct | OpenStruct objects |
+| Range | Range objects |
+| Rational | Rational numbers |
+| Regexp | Regular expressions |
+| Struct | Struct objects |
+| Time | Time objects |
+
+## Compatibility Notes
+
+- `oj_windows` in `:compat` mode mimics the json gem's `to_json(*)` method behavior
+- JSON.generate(), JSON.dump(), and JSON() functions are supported
+- NaN and Infinity handling matches the json gem's behavior
+- Compatibility target is json gem version 2.0.3

data/pages/Modes.md

@@ -0,0 +1,94 @@
+# Modes
+
+`oj_windows` provides multiple modes to control JSON serialization and parsing behavior.
+
+## Available Modes
+
+| Mode | Description |
+|------|-------------|
+| `:strict` | Strict JSON compliance, native types only |
+| `:null` | Like strict, but outputs null for unsupported types |
+| `:compat` / `:json` | JSON gem compatible |
+| `:rails` | ActiveSupport/Rails compatible |
+| `:object` | Full Ruby object serialization |
+| `:custom` | Maximum flexibility, honors all options |
+| `:wab` | WAB format for web applications |
+
+## Mode Details
+
+### :strict Mode
+
+Strict mode follows JSON specifications exactly. Only native JSON types are supported:
+- Boolean (`true`, `false`)
+- `nil`
+- String
+- Hash
+- Array
+- Numbers
+
+Non-native types raise an Exception. This is the safest mode for parsing untrusted input.
+
+### :null Mode
+
+Similar to `:strict`, but outputs JSON `null` for non-native types instead of raising an Exception.
+
+### :compat Mode
+
+Mimics the Ruby JSON gem. Uses `to_json(*)` methods for serialization.
+See [JsonGem.md](JsonGem.md) for details.
+
+```ruby
+Oj.mimic_JSON()  # Take over JSON module methods
+```
+
+### :rails Mode
+
+Mimics ActiveSupport's encoder. Uses `as_json(*)` methods for serialization.
+See [Rails.md](Rails.md) for details.
+
+```ruby
+Oj.optimize_rails()  # Full Rails integration
+```
+
+### :object Mode
+
+Full Ruby object serialization and deserialization. Encodes class information,
+circular references, and object IDs in the JSON output.
+See [Encoding.md](Encoding.md) for the encoding format.
+
+### :custom Mode
+
+Maximum flexibility with all options honored. Cannot exactly replicate other modes
+but provides the most control. See [Custom.md](Custom.md) for details.
+
+### :wab Mode
+
+Optimized for WAB (Web Application Builder) data exchange. Only honors the indent option.
+See [WAB.md](WAB.md) for details.
+
+## Setting the Mode
+
+```ruby
+require 'oj_windows'
+
+# Set default mode
+Oj.default_options = { mode: :compat }
+
+# Or per-call
+json = Oj.dump(data, mode: :strict)
+data = Oj.load(json, mode: :strict)
+```
+
+## Mode Consistency
+
+Use the same mode for both dumping and loading. Mixing modes may produce unexpected results.
+
+```ruby
+# Correct: same mode for dump and load
+json = Oj.dump(obj, mode: :object)
+obj2 = Oj.load(json, mode: :object)
+
+# Incorrect: mixed modes
+json = Oj.dump(obj, mode: :object)
+obj2 = Oj.load(json, mode: :strict)  # May fail or lose data
+```

data/pages/Options.md

@@ -0,0 +1,339 @@
+# Options
+
+`oj_windows` provides extensive configuration options for JSON serialization and parsing.
+
+## Setting Default Options
+
+```ruby
+require 'oj_windows'
+
+Oj.default_options = { mode: :compat }
+```
+
+Another way to make use of options when calling load or dump methods is to
+pass in a Hash with the options already set in the Hash. This is slightly less
+efficient than setting the globals for many smaller JSON documents but does
+provide a more thread safe approach to using custom options for loading and
+dumping.
+
+### Options for serializer and parser
+
+### :allow_blank [Boolean]
+
+If true a nil input to load will return nil and not raise an Exception.
+
+### :allow_gc [Boolean]
+
+Allow or prohibit GC during parsing, default is true (allow).
+
+### :allow_invalid_unicode [Boolean]
+
+Allow invalid unicode, default is false (don't allow).
+
+### :allow_nan
+
+Alias for the :nan option.
+
+### :array_class [Class]
+
+Class to use instead of Array on load.
+
+### :array_nl
+
+Trailer appended to the end of an array dump. The default is an empty
+string. Primarily intended for json gem compatibility. Using just indent as an
+integer gives better performance.
+
+### :ascii_only
+
+If true all non-ASCII character are escaped when dumping. This is the same as
+setting the :escape_mode options to :ascii and exists for json gem
+compatibility.
+
+### :auto_define [Boolean]
+
+Automatically define classes if they do not exist.
+
+### :bigdecimal_as_decimal [Boolean]
+
+If true dump BigDecimal as a decimal number otherwise as a String
+
+### :bigdecimal_load [Symbol]
+
+Determines how to load decimals.
+
+ - `:bigdecimal` convert all decimal numbers to BigDecimal.
+
+ - `:float` convert all decimal numbers to Float.
+
+ - `:auto` the most precise for the number of digits is used.
+
+ - `:fast` faster conversion to Float.
+
+ - `:ruby` convert to Float using the Ruby `to_f` conversion.
+
+This can also be set with `:decimal_class` when used as a load or
+parse option to match the JSON gem. In that case either `Float`,
+`BigDecimal`, or `nil` can be provided.
+
+### :cache_keys [Boolean]
+
+If true Hash keys are cached or interned. There are trade-offs with
+caching keys. Large caches will use more memory and in extreme cases
+(like over a million) the cache may be slower than not using
+it. Repeated parsing of similar JSON docs is where cache_keys shines
+especially with symbol keys.
+
+There is a maximum length for cached keys. Any key longer than 34
+bytes is not cached. Everything still works but the key is not cached.
+
+### :cache_strings [Int]
+
+Shorter strings can be cached for better performance. A limit,
+cache_strings, defines the upper limit on what strings are cached. As
+with cached keys only strings less than 35 bytes are cached even if
+the limit is set higher. Setting the limit to zero effectively
+disables the caching of string values.
+
+Note that caching for strings is for string values and not Hash keys
+or Object attributes.
+
+### :circular [Boolean]
+
+Detect circular references while dumping. In :compat mode raise a
+NestingError. For other modes except the :object mode place a null in the
+output. For :object mode place references in the output that will be used to
+recreate the looped references on load.
+
+### :class_cache [Boolean]
+
+Cache classes for faster parsing. This option should not be used if
+dynamically modifying classes or reloading classes then don't use this.
+
+### :compat_bigdecimal [Boolean]
+
+Determines how to load decimals when in `:compat` mode.
+
+ - `true` convert all decimal numbers to BigDecimal.
+
+ - `false` convert all decimal numbers to Float.
+
+### :create_additions
+
+A flag indicating that the :create_id key, when encountered during parsing,
+should create an Object matching the class name specified in the value
+associated with the key.
+
+### :create_id [String]
+
+The :create_id option specifies that key is used for dumping and loading when
+specifying the class for an encoded object. The default is `json_create`.
+
+In the `:custom` mode, setting the `:create_id` to nil will cause Complex,
+Rational, Range, and Regexp to be output as strings instead of as JSON
+objects.
+
+### :empty_string [Boolean]
+
+If true an empty or all whitespace input will not raise an Exception. The
+default_options will be honored for :null, :strict, and :custom modes. Ignored
+for :custom and :wab. The :compat has a more complex set of rules. The JSON
+gem compatibility is best described by examples.
+
+```
+JSON.parse('') => raise
+JSON.parse(' ') => raise
+JSON.load('') => nil
+JSON.load('', nil, allow_blank: false) => raise
+JSON.load('', nil, allow_blank: true) => nil
+JSON.load(' ') => raise
+JSON.load(' ', nil, allow_blank: false) => raise
+JSON.load(' ', nil, allow_blank: true) => raise
+```
+
+### :escape_mode [Symbol]
+
+Determines the characters to escape when dumping. Only the :ascii and
+:json modes are supported in :compat mode.
+
+ - `:newline` allows unescaped newlines in the output.
+
+ - `:json` follows the JSON specification. This is the default mode.
+
+ - `:slash` escapes `/` characters.
+
+ - `:xss_safe` escapes HTML and XML characters such as `&` and `<`.
+
+ - `:ascii` escapes all non-ascii or characters with the hi-bit set.
+
+ - `:unicode_xss` escapes a special unicodes and is xss safe.
+
+### :float_precision [Fixnum]
+
+The number of digits of precision when dumping floats, 0 indicates use Ruby directly.
+
+### :hash_class [Class]
+
+Class to use instead of Hash on load. This is the same as the :object_class.
+
+### :ignore [Array]
+
+Ignore all the classes in the Array when dumping. A value of nil indicates
+ignore nothing.
+
+### :indent [Fixnum]
+
+Number of spaces to indent each element in a JSON document, zero is no newline
+between JSON elements, negative indicates no newline between top level JSON
+elements in a stream.
+
+### :indent_str
+
+Indentation for each element when dumping. The default is an empty
+string. Primarily intended for json gem compatibility. Using just indent as an
+integer gives better performance.
+
+### :integer_range [Range]
+
+Dump integers outside range as strings.
+Note: range bounds must be Fixnum.
+
+### :match_string
+
+Provides a means to detect strings that should be used to create non-String
+objects. The value to the option must be a Hash with keys that are regular
+expressions and values are class names. For strict json gem compatibility a
+RegExp should be used. For better performance but sacrificing some regexp
+options a string can be used and the C version of regex will be used instead.
+
+### :max_nesting
+
+The maximum nesting depth on both dump and load that is allowed. This exists
+for json gem compatibility.
+
+### :mode [Symbol]
+
+Primary behavior for loading and dumping. The :mode option controls which
+other options are in effect. For more details see the {file:Modes.md} page. By
+default Oj uses the :custom mode which is provides the highest degree of
+customization.
+
+### :nan [Symbol]
+
+How to dump Infinity, -Infinity, and NaN in :null, :strict, and :compat
+mode. Default is :auto but is ignored in the :compat and :rails modes.
+
+ - `:null` places a null
+
+ - `:huge` places a huge number
+
+ - `:word` places Infinity or NaN
+
+ - `:raise` raises and exception
+
+ - `:auto` uses default for each mode which are `:raise` for `:strict`, `:null` for `:null`, and `:word` for `:compat`.
+
+### :nilnil [Boolean]
+
+If true a nil input to load will return nil and not raise an Exception.
+
+### :object_class
+
+The class to use when creating a Hash on load instead of the Hash class.
+
+### :object_nl
+
+Trailer appended to the end of an object dump. The default is an empty
+string. Primarily intended for json gem compatibility. Using just indent as an
+integer gives better performance.
+
+### :omit_nil [Boolean]
+
+If true, Hash and Object attributes with nil values are omitted.
+
+### :quirks_mode [Boolean]
+
+Allow single JSON values instead of documents, default is true (allow). This
+can also be used in :compat mode to be backward compatible with older versions
+of the json gem.
+
+### :safe
+
+The JSON gem includes the complete JSON in parse errors with no limit
+on size. To break from the JSON gem behavior for this case set `:safe`
+to true.
+
+### :second_precision [Fixnum]
+
+The number of digits after the decimal when dumping the seconds of time.
+
+### :skip_null_byte [Boolean]
+
+If true, null bytes in strings will be omitted when dumping.
+
+### :space
+
+String inserted after the ':' character when dumping a JSON object. The
+default is an empty string. Primarily intended for json gem
+compatibility. Using just indent as an integer gives better performance.
+
+### :space_before
+
+String inserted before the ':' character when dumping a JSON object. The
+default is an empty string. Primarily intended for json gem
+compatibility. Using just indent as an integer gives better performance.
+
+### :symbol_keys [Boolean]
+
+Use symbols instead of strings for hash keys.
+
+### :symbolize_names [Boolean]
+
+Like :symbol_keys has keys are made into symbols but only when
+mimicking the JSON gem and then only as the JSON gem honors it so
+JSON.parse honors the option but JSON.load does not.
+
+### :trace
+
+When true dump and load functions are traced by printing beginning and ending
+of blocks and of specific calls.
+
+### :time_format [Symbol]
+
+The :time_format when dumping.
+
+ - `:unix` time is output as a decimal number in seconds since epoch including fractions of a second.
+
+ - `:unix_zone` is similar to the `:unix` format but with the timezone encoded in
+   the exponent of the decimal number of seconds since epoch.
+
+ - `:xmlschema` time is output as a string that follows the XML schema definition.
+
+ - `:ruby` time is output as a string formatted using the Ruby `to_s` conversion.
+
+### :use_as_json [Boolean]
+
+Call `as_json()` methods on dump, default is false. The option is ignored in
+the :compat and :rails modes.
+
+
+### :use_raw_json [Boolean]
+
+Call `raw_json()` methods on dump, default is false. The option is
+accepted in the :compat and :rails modes even though it is not
+supported by other JSON gems. It provides a means to optimize dump or
+generate performance. The `raw_json(depth, indent)` method should be
+called only by Oj. It is not intended for any other use. This is meant
+to replace the abused `to_json` methods. Calling `Oj.dump` inside the
+`raw_json` with the object itself when `:use_raw_json` is true will
+result in an infinite loop.
+
+### :use_to_hash [Boolean]
+
+Call `to_hash()` methods on dump, default is false. The option is ignored in
+the :compat and :rails modes.
+
+### :use_to_json [Boolean]
+
+Call `to_json()` methods on dump, default is false. The option is ignored in
+the :compat and :rails modes.