libvips · jcupitt · Jun 10, 2018 · Jun 9, 2018 · Jun 9, 2018 · kleisauke
diff --git a/.travis.yml b/.travis.yml
@@ -12,7 +12,7 @@ env:
   global:
     - VIPS_VERSION_MAJOR=8
     - VIPS_VERSION_MINOR=6
-    - VIPS_VERSION_MICRO=0
+    - VIPS_VERSION_MICRO=3
     - PATH=$HOME/vips/bin:$PATH
     - LD_LIBRARY_PATH=$HOME/vips/lib:$LD_LIBRARY_PATH
     - PKG_CONFIG_PATH=$HOME/vips/lib/pkgconfig:$PKG_CONFIG_PATH

diff --git a/composer.json b/composer.json
@@ -19,12 +19,12 @@
     "require": {
         "php": ">=7.0.11",
         "ext-vips": ">=0.1.2",
-        "psr/log": "^1.0.1"
+        "psr/log": "^1.0.2"
     },
     "require-dev": {
-        "phpunit/phpunit": "^6.3",
+        "phpunit/phpunit": "^6.5",
         "phpdocumentor/phpdocumentor" : "^2.9",
-        "jakub-onderka/php-parallel-lint": "^0.9.2",
+        "jakub-onderka/php-parallel-lint": "^1.0.0",
         "squizlabs/php_codesniffer": "3.*"
     },
     "autoload": {

diff --git a/examples/generate_phpdoc.py b/examples/generate_phpdoc.py
@@ -0,0 +1,331 @@
+#!/usr/bin/env python
+
+from pyvips import Image, Operation, GValue, Error, \
+    ffi, values_for_enum, vips_lib, gobject_lib, \
+    type_map, type_name, type_from_name, nickname_find
+
+# This file generates the phpdoc comments for the magic methods and properties.
+# It's in Python, since we use the whole of FFI, not just the
+# small bit exposed by php-vips-ext.
+
+# Regenerate docs with something like:
+#
+#   cd src
+#   python ../examples/generate_phpdoc.py
+
+# this needs pyvips
+#
+#   pip install --user pyvips
+
+# map a Python gtype to PHP argument type names
+gtype_to_php_arg = {
+    GValue.gbool_type: 'bool',
+    GValue.gint_type: 'integer',
+    GValue.gdouble_type: 'float',
+    GValue.gstr_type: 'string',
+    GValue.refstr_type: 'string',
+    GValue.genum_type: 'string',
+    GValue.gflags_type: 'integer',
+    GValue.gobject_type: 'string',
+    GValue.image_type: 'Image',
+    GValue.array_int_type: 'integer[]|integer',
+    GValue.array_double_type: 'float[]|float',
+    GValue.array_image_type: 'Image[]|Image',
+    GValue.blob_type: 'string'
+}
+
+# php result type names are different, annoyingly, and very restricted
+gtype_to_php_result = {
+    GValue.gbool_type: 'bool',
+    GValue.gint_type: 'integer',
+    GValue.gdouble_type: 'float',
+    GValue.gstr_type: 'string',
+    GValue.refstr_type: 'string',
+    GValue.genum_type: 'string',
+    GValue.gflags_type: 'integer',
+    GValue.gobject_type: 'string',
+    GValue.image_type: 'Image',
+    GValue.array_int_type: 'array',
+    GValue.array_double_type: 'array',
+    GValue.array_image_type: 'array',
+    GValue.blob_type: 'string'
+}
+
+# values for VipsArgumentFlags
+_REQUIRED = 1
+_INPUT = 16
+_OUTPUT = 32
+_DEPRECATED = 64
+_MODIFY = 128
+
+# for VipsOperationFlags
+_OPERATION_DEPRECATED = 8
+
+
+def gtype_to_php(gtype, result=False):
+    """Map a gtype to PHP type name we use to represent it.
+    """
+
+    fundamental = gobject_lib.g_type_fundamental(gtype)
+
+    gtype_map = gtype_to_php_result if result else gtype_to_php_arg
+
+    if gtype in gtype_map:
+        return gtype_map[gtype]
+    if fundamental in gtype_map:
+        return gtype_map[fundamental]
+    return '<unknown type>'
+
+
+def remove_prefix(enum_str):
+    prefix = 'Vips'
+
+    if enum_str.startswith(prefix):
+        return enum_str[len(prefix):]
+
+    return enum_str
+
+
+def generate_operation(operation_name):
+    op = Operation.new_from_name(operation_name)
+
+    # we are only interested in non-deprecated args
+    args = [[name, flags] for name, flags in op.get_args()
+            if not flags & _DEPRECATED]
+
+    # find the first required input image arg, if any ... that will be self
+    member_x = None
+    for name, flags in args:
+        if ((flags & _INPUT) != 0 and
+                (flags & _REQUIRED) != 0 and
+                op.get_typeof(name) == GValue.image_type):
+            member_x = name
+            break
+
+    required_input = [name for name, flags in args
+                      if (flags & _INPUT) != 0 and
+                      (flags & _REQUIRED) != 0 and
+                      name != member_x]
+
+    required_output = [name for name, flags in args
+                       if ((flags & _OUTPUT) != 0 and
+                           (flags & _REQUIRED) != 0) or
+                       ((flags & _INPUT) != 0 and
+                        (flags & _REQUIRED) != 0 and
+                        (flags & _MODIFY) != 0)]
+
+    result = ' * @method '
+    if member_x is None:
+        result += 'static '
+    if len(required_output) == 0:
+        result += 'void '
+    elif len(required_output) == 1:
+        result += '{0} '.format(gtype_to_php(op.get_typeof(required_output[0]), True))
+    else:
+        # we generate a Returns: block for this case, see below
+        result += 'array '
+
+    result += '{0}('.format(operation_name)
+    for name in required_input:
+        gtype = op.get_typeof(name)
+        result += '{0} ${1}, '.format(gtype_to_php(gtype), name)
+
+    result += 'array $options = []) '
+
+    description = op.get_description()
+    result += description[0].upper() + description[1:] + '.\n'
+
+    # find any Enums we've referenced and output @see lines for them
+    for name in required_output + required_input:
+        gtype = op.get_typeof(name)
+        fundamental = gobject_lib.g_type_fundamental(gtype)
+
+        if fundamental != GValue.genum_type:
+            continue
+
+        result += ' *     @see {0} for possible values for ${1}\n'.format(remove_prefix(type_name(gtype)), name)
+
+    if len(required_output) > 1:
+        result += ' *     Return array with: [\n'
+        for name in required_output:
+            gtype = op.get_typeof(name)
+            blurb = op.get_blurb(name)
+            result += ' *         \'{0}\' => @type {1} {2}\n'.format(name, gtype_to_php(gtype),
+                                                                     blurb[0].upper() + blurb[1:])
+        result += ' *     ];\n'
+
+    result += ' *     @throws Exception\n'
+
+    return result
+
+
+preamble = """<?php
+
+/**
+ * This file was generated automatically. Do not edit!
+ *
+ * PHP version 7
+ *
+ * LICENSE:
+ *
+ * Copyright (c) 2016 John Cupitt
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * @category  Images
+ * @package   Jcupitt\\Vips
+ * @author    John Cupitt <jcupitt@gmail.com>
+ * @copyright 2016 John Cupitt
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/jcupitt/php-vips
+ */
+"""
+
+class_header = """ * @category  Images
+ * @package   Jcupitt\\Vips
+ * @author    John Cupitt <jcupitt@gmail.com>
+ * @copyright 2016 John Cupitt
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/jcupitt/php-vips
+"""
+
+
+def generate_auto_doc(filename):
+    all_nicknames = []
+
+    def add_nickname(gtype, a, b):
+        nickname = nickname_find(gtype)
+        try:
+            # can fail for abstract types
+            op = Operation.new_from_name(nickname)
+
+            # we are only interested in non-deprecated operations
+            if (op.get_flags() & _OPERATION_DEPRECATED) == 0:
+                all_nicknames.append(nickname)
+        except Error:
+            pass
+
+        type_map(gtype, add_nickname)
+
+        return ffi.NULL
+
+    type_map(type_from_name('VipsOperation'), add_nickname)
+
+    # add 'missing' synonyms by hand
+    all_nicknames.append('crop')
+
+    # make list unique and sort
+    all_nicknames = list(set(all_nicknames))
+    all_nicknames.sort()
+
+    # these have hand-written methods, don't autodoc them
+    no_generate = [
+        'bandjoin',
+        'bandrank',
+        'ifthenelse',
+        'add',
+        'subtract',
+        'multiply',
+        'divide',
+        'remainder'
+    ]
+    all_nicknames = [x for x in all_nicknames if x not in no_generate]
+
+    print('Generating {0} ...'.format(filename))
+
+    with open(filename, 'w') as f:
+        f.write(preamble)
+        f.write('\n')
+        f.write('namespace Jcupitt\\Vips;\n')
+        f.write('\n')
+        f.write('/**\n')
+        f.write(' * Autodocs for the Image class.\n')
+        f.write(class_header)
+        f.write(' *\n')
+
+        for nickname in all_nicknames:
+            f.write(generate_operation(nickname))
+
+        f.write(' *\n')
+
+        # all magic properties
+        tmp_file = Image.new_temp_file('%s.v')
+        all_properties = tmp_file.get_fields()
+        for name in all_properties:
+            php_name = name.replace('-', '_')
+            gtype = tmp_file.get_typeof(name)
+            fundamental = gobject_lib.g_type_fundamental(gtype)
+
+            f.write(' * @property {0} ${1} {2}\n'.format(gtype_to_php(gtype), php_name, tmp_file.get_blurb(name)))
+
+            if fundamental == GValue.genum_type:
+                f.write(' *     @see {0} for possible values\n'.format(remove_prefix(type_name(gtype))))
+
+        f.write(' */\n')
+        f.write('abstract class ImageAutodoc\n')
+        f.write('{\n')
+        f.write('}\n')
+
+
+def generate_enums():
+    # otherwise we're missing some enums
+    vips_lib.vips_token_get_type()
+    vips_lib.vips_saveable_get_type()
+    vips_lib.vips_image_type_get_type()
+
+    all_enums = []
+
+    def add_enum(gtype, a, b):
+        nickname = type_name(gtype)
+        all_enums.append(nickname)
+
+        type_map(gtype, add_enum)
+
+        return ffi.NULL
+
+    type_map(type_from_name('GEnum'), add_enum)
+
+    for name in all_enums:
+        gtype = type_from_name(name)
+        php_name = remove_prefix(name)
+
+        print('Generating {0}.php ...'.format(php_name))
+
+        with open('{0}.php'.format(php_name), 'w') as f:
+            f.write(preamble)
+            f.write('\n')
+            f.write('namespace Jcupitt\\Vips;\n')
+            f.write('\n')
+            f.write('/**\n')
+            f.write(' * The {0} enum.\n'.format(php_name))
+            f.write(class_header)
+            f.write(' */\n')
+            f.write('abstract class {0}\n'.format(php_name))
+            f.write('{\n')
+
+            for value in values_for_enum(gtype):
+                php_name = value.replace('-', '_').upper()
+                f.write('    const {0} = \'{1}\';\n'.format(php_name, value))
+
+            f.write('}\n')
+
+
+generate_auto_doc('ImageAutodoc.php')
+generate_enums()