You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: lang_php.adoc
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
= Kaitai Struct: PHP notes
2
2
3
-
The Kaitai Struct https://github.com/kaitai-io/kaitai_struct_php_runtime[runtime for PHP] requires PHP >= 7.0 and can be used in two different ways:
3
+
The Kaitai Struct https://github.com/kaitai-io/kaitai_struct_php_runtime[runtime library for PHP] requires PHP >= 7.0 and can be used in two different ways:
4
4
5
5
1) As part of Kaitai Struct (recommended approach)
Copy file name to clipboardExpand all lines: serialization.adoc
+20-91Lines changed: 20 additions & 91 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,9 @@ Kaitai Project
3
3
:toc: left
4
4
:tabs-sync-option:
5
5
6
-
NOTE: Serialization for Java and Python is made thanks to financial support https://nlnet.nl/project/Kaitai-Serialization[from the NLnet Foundation].
6
+
NOTE: Serialization for Java and Python was made thanks to financial support https://nlnet.nl/project/Kaitai-Serialization/[from the NLnet Foundation].
7
+
8
+
IMPORTANT: Feature available since v0.11.
7
9
8
10
For a long time, you could only use Kaitai Struct for parsing, not serialization (writing data to file). However, due to high user interest in this feature, we've added serialization support to Kaitai Struct.
9
11
@@ -19,40 +21,6 @@ While parsing allows you extract data from existing files or byte streams based
19
21
20
22
== Getting started
21
23
22
-
Once you have the .ksy specification of the format you want to serialize, you need a version of `kaitai-struct-compiler` that supports serialization. The latest 0.10 compiler doesn't have it yet; you need to build the compiler from source at the moment.
23
-
24
-
=== Building the compiler from source
25
-
26
-
Don't worry, it should be straightforward:
27
-
28
-
1. Install `sbt` by following the steps at https://www.scala-sbt.org/1.x/docs/Setup.html.
29
-
30
-
2. Clone the https://github.com/kaitai-io/kaitai_struct_compiler repository, checkout the https://github.com/kaitai-io/kaitai_struct_compiler/tree/serialization[*serialization*] branch.
3. Build the compiler using `sbt` that you installed earlier:
39
-
+
40
-
[source,shell]
41
-
----
42
-
sbt --error compilerJVM/stage
43
-
----
44
-
+
45
-
If no error is printed, there should be a compiler build in `jvm/target/universal/stage/bin/kaitai-struct-compiler`. If you run `jvm/target/universal/stage/bin/kaitai-struct-compiler --help`, you should see the `--read-write` option in the usage text:
@@ -155,82 +123,41 @@ with KaitaiStream(open("path/to/some.gif", 'rb')) as _io:
155
123
----
156
124
======
157
125
158
-
=== Installing the runtime library with serialization support
126
+
=== Installing the runtime library
159
127
160
-
As with the compiler, the latest released 0.10 KS runtime libraries don't have serialization capabilities yet.
128
+
You must add the Kaitai Struct runtime library for the selected target language to your project, as all generated modules depend on it.
161
129
162
130
[tabs]
163
131
======
164
132
Java::
165
133
+
166
134
--
167
-
In Java, you need to checkout the https://github.com/kaitai-io/kaitai_struct_java_runtime repo:
135
+
The Java runtime library is published https://central.sonatype.com/artifact/io.kaitai/kaitai-struct-runtime[in the Maven Central Repository]. The source code is available https://github.com/kaitai-io/kaitai_struct_java_runtime[on GitHub].
The runtime library is a dependency of all Java code generated by `kaitai-struct-compiler`, so you have to build it and make it available to your generated Java "format library" at compile time. If you use https://maven.apache.org/[Maven], run this command in the `kaitai_struct_java_runtime` directory to build it and install it to your local Maven repository:
176
-
177
-
[source,shell]
178
-
----
179
-
mvn install
180
-
----
181
-
182
-
[NOTE]
183
-
=====
184
-
If the `gpg` command isn't available on your system, `mvn install` will fail because of `maven-gpg-plugin` used to sign artifacts when publishing. In that case, comment this plugin in `pom.xml` like this:
185
-
186
-
[source,xml,highlight="2,9"]
187
-
----
188
-
</plugin>
189
-
<!-- <plugin>
190
-
<groupId>org.apache.maven.plugins</groupId>
191
-
<artifactId>maven-gpg-plugin</artifactId>
192
-
<version>1.5</version>
193
-
<executions>
194
-
...
195
-
</executions>
196
-
</plugin> -->
197
-
</plugins>
198
-
</build>
199
-
----
200
-
=====
137
+
After you install it, you can import the I/O stream classes defined in the runtime library like this (generated modules do it too):
201
138
202
-
Now you can include the serialization-capable Java runtime library in your project like this:
203
-
204
-
[source,xml]
139
+
[source,java]
205
140
----
206
-
<dependency>
207
-
<groupId>io.kaitai</groupId>
208
-
<artifactId>kaitai-struct-runtime</artifactId>
209
-
<version>0.11-SNAPSHOT</version>
210
-
</dependency>
141
+
import io.kaitai.struct.ByteBufferKaitaiStream;
142
+
import io.kaitai.struct.KaitaiStream;
211
143
----
212
144
213
-
But note that the `0.11-SNAPSHOT` version only exists in your local Maven repository (`~/.m2`) after you ran `mvn install` in the Java runtime library folder.
145
+
For brevity, these imports will be omitted from the code snippets later in this guide, but they're often needed.
214
146
--
215
147
216
148
Python::
217
149
+
218
150
--
219
-
In Python, you need to install the runtime library from the https://github.com/kaitai-io/kaitai_struct_python_runtime repo. You can do it with https://pypi.org/project/pip/[pip] (package installer for Python); you also need https://git-scm.com/[Git] while running the command because the installation involves cloning the source code from GitHub:
151
+
The Pythonruntime library is published https://pypi.org/project/kaitaistruct/[on PyPI]. The source code is available https://github.com/kaitai-io/kaitai_struct_python_runtime[on GitHub].
They have setters and their own `+_check{Inst}+` (`+_check_{inst}+`) method which you should call. Additionally, you can also use a special boolean `set{Inst}_ToWrite` setter (in Python you'd assign a boolean to a property `+{inst}__to_write+`), allowing you to disable writing of a specific instance (as `r.set{Inst}_ToWrite(false)` in Java, or `+r.{inst}__to_write = False+` in Python) in a particular KS object. This may be useful for C-style `union` members (several overlapping fields with different types, but only one applies in any object), lookaheads or other positional instances you don't want to write.
655
+
They have setters. Additionally, you can also use a special boolean `set{Inst}_ToWrite` setter (in Python you'd assign a boolean to a property `+{inst}__to_write+`), allowing you to disable writing of a specific instance (as `r.set{Inst}_ToWrite(false)` in Java, or `+r.{inst}__to_write = False+` in Python) in a particular KS object. This may be useful for C-style `union` members (several overlapping fields with different types, but only one applies in any object), lookaheads or other positional instances you don't want to write.
729
656
730
657
=== Parameters
731
658
@@ -745,7 +672,9 @@ Current serialization support relies on fixed-length streams, meaning that once
745
672
746
673
=== Enums
747
674
748
-
Enum values not present in the enum definition are not supported in Java or Python right now. An attempt to write them causes `NullPointerException` in Java, `AttributeError` in Python.
675
+
Currently, generated enum classes in Java can only represent known values defined in the enum. When converting an integer to an enum, integers that don't correspond to any defined enum member are mapped to `null`, which cannot be serialized (a `NullPointerException` will be thrown).
676
+
677
+
In Python, this limitation doesn't exist: all enum values (both defined and undefined) can be serialized.
0 commit comments