Metadata-Version: 2.1
Name: dmengine
Version: 0.2.4
Summary: Distributed Morphology calculator
Home-page: https://github.com/xflr6/dmengine
Author: Sebastian Bank
Author-email: sebastian.bank@uni-leipzig.de
License: MIT
Description: dmengine
        ========
        
        |PyPI version| |License| |Supported Python| |Format|
        
        DM-engine is a Python implementation of **Distributed Morphology** (DM_).
        
        Distributed Morphology is a framework from theoretical linguistics that is used
        to describe the morphology (word structure) of natural languages. This package
        provides an engine that calculates the word forms that are generated by a given
        DM analysis.
        
        Analyses are entered as plain-text files in the human-friendly YAML_ format.
        Minimally, they consist of a **title**, an inventory of **feature values**, a
        list of insertable **vocabulary items** (VIs), and a list of **inputs** to be
        processed (see the example below). The ``dmengine`` command-line tool calculates
        the results and generates a detailed transcript of all calculations for later
        inspection. The resulting YAML file can be converted into a LaTeX-based report
        that can directly be compiled into a PDF file.
        
        
        Links
        -----
        
        - GitHub: https://github.com/xflr6/dmengine
        - PyPI: https://pypi.org/project/dmengine/
        - Issue Tracker: https://github.com/xflr6/dmengine/issues
        - Download: https://pypi.org/project/dmengine/#files
        
        
        Installation
        ------------
        
        This package runs under Python 2.7 and 3.4+, use pip_ to install:
        
        .. code:: bash
        
            $ pip install dmengine
        
        This will also install the PyYAML_ and oset_ packages from PyPI as required
        dependencies.
        
        Converting the results to a **PDF report** also requires a **LaTeX
        distribution** (`TeX Live`_ and MikTeX_ should work). Make sure its executables
        are on your systems' path.
        
        
        Usage
        -----
        
        Create a **plain text file** that defines your analysis:
        
        .. code:: yaml
        
            # example.yaml - simple demonstration of the analysis definition syntax
            title: English verbal agreement
            features:
            - value: V
              category: pos
            - value: Nom
              category: case
            - value: +1
              category: person
            - value: +2
              category: person
            - value: +3
              category: person
            - value: -pl
              category: number
            - value: +pl
              category: number
            vis:
            - exponent: sleep
              features: [ V ]
            - exponent: -s
              features: [ Nom, +3, -pl ]
            - exponent: -Ø
              features: [ Nom ]
            paradigms:
            - name: Intransitive paradigm
              headers: [ [1, 2, 3], [sg, pl] ]
              inputs:
              - [ [V], [Nom, +1, -pl] ]
              - [ [V], [Nom, +1, +pl] ]
              - [ [V], [Nom, +2, -pl] ]
              - [ [V], [Nom, +2, +pl] ]
              - [ [V], [Nom, +3, -pl] ]
              - [ [V], [Nom, +3, +pl] ]
        
        Save your analysis definition to a file ending with ``.yaml`` (e.g.
        ``example.yaml``).
        
        Open a shell (command line window) and navigate to the directory of your
        definition file.
        
        Calculate the results of the analyis with the ``dmengine`` command creating a
        PDF report:
        
        .. code:: bash
        
            $ dmengine example.yaml --pdf
        
        This will create three files:
        
        - ``example-results.yaml`` |--| plain-text file with the results in YAML format
        - ``example-results.tex`` |--| LaTeX source for the result report
        - ``example-results.pdf`` |--| PDF output of the report compiled with ``pdflatex``
        
        
        Results
        -------
        
        Go to the **outputs section** of the report. It provides a **paradigm table**
        of the calculated results:
        
        .. image:: https://raw.github.com/xflr6/dmengine/master/docs/example-outputs.png
        
        The **log section** of the report contains detailed information about each
        individual input and the **derivation of the output**.
        
        .. image:: https://raw.github.com/xflr6/dmengine/master/docs/example-log.png
        
        
        Invocation options
        ------------------
        
        Check the **usage** of the ``dmengine`` command:
        
        .. code:: bash
        
            $ dmengine --help
            
            usage: dmengine [-h] [--version] [--report] [--pdf] [--view]
                            filename [directory]
            
            Calculates a given Distributed Morphology (DM) analysis
            
            positional arguments:
              filename    dm analysis .yaml definition file
              directory   analysis results output directory
            
            optional arguments:
              -h, --help  show this help message and exit
              --version   show program's version number and exit
              --report    create a LaTeX report from the results
              --pdf       render the report to PDF (implies --report)
              --view      open the report in viewer app (implies --pdf)
        
        
        Rules
        -----
        
        Analyses can use the following types of **rules** that manipulate the input
        *before* insertion:
        
        - ``impoverishment`` |--| feature deletion
        - ``obliteration`` |--| head removal
        - ``fission`` |--| head feature extraction
        - ``fusion`` |--| head merging
        - ``copy`` |--| head duplication
        - ``add`` |--| features addition
        - ``metathesis`` |--| head position swapping
        
        
        The following types of **readjustment rules** are supported (manipulating  the
        output *after* insertion):
        
        - ``delete`` |--| exponent removal
        - ``copy`` |--| exponent duplication
        - ``metathesis`` |--| exponent position swapping
        - ``transform`` |--| regular expression search & replace
        
        
        Contexts
        --------
        
        The insertion of vocabulary items and the application of pre-insertion rules can
        be restricted to the following context types:
        
        - ``this_head`` |--| the processed head must have the features
        - ``left_head`` |--| the left-adjacent head must have the features
        - ``right_head`` |--| the right-adjacent head must have the features
        - ``any_head`` |--| any input head must have the features
        - ``anywhere`` |--| features must be matched somewhere in the input
        
        
        See also
        --------
        
        Raphael Finkel provides `web-based engines`_ for calculating Paradigm Function
        Morphology and Network Morphology analyses.
        
        
        License
        -------
        
        ``dmengine`` is distributed under the `MIT license`_.
        
        
        .. _DM: https://www.ling.upenn.edu/~rnoyer/dm/
        
        .. _YAML: https://en.wikipedia.org/wiki/YAML
        .. _pip: https://pip.readthedocs.io
        .. _PyYAML: https://pypi.org/project/PyYAML/
        .. _oset: https://pypi.org/project/oset/
        .. _TeX Live: https://www.tug.org/texlive/
        .. _MikTeX: https://miktex.org
        
        .. _web-based engines: https://www.cs.uky.edu/~raphael/linguistics/claw.html
        
        .. _MIT license: https://opensource.org/licenses/MIT
        
        
        .. |--| unicode:: U+2013
        
        
        .. |PyPI version| image:: https://img.shields.io/pypi/v/dmengine.svg
            :target: https://pypi.org/project/dmengine/
            :alt: Latest PyPI Version
        .. |License| image:: https://img.shields.io/pypi/l/dmengine.svg
            :target: https://pypi.org/project/dmengine/
            :alt: License
        .. |Supported Python| image:: https://img.shields.io/pypi/pyversions/dmengine.svg
            :target: https://pypi.org/project/dmengine/
            :alt: Supported Python Versions
        .. |Format| image:: https://img.shields.io/pypi/format/dmengine.svg
            :target: https://pypi.org/project/dmengine/
            :alt: Format
        
Keywords: DM Halle Marantz impoverishment fission linguistics
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Provides-Extra: test
Provides-Extra: dev
