| 1 |
- (window.webpackJsonp=window.webpackJsonp||[]).push([[12],{113:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return l})),n.d(t,"metadata",(function(){return o})),n.d(t,"rightToc",(function(){return s})),n.d(t,"default",(function(){return p}));var a=n(2),i=n(6),r=(n(0),n(117)),l={id:"05-u-extending-tool",title:"Extending the tool",sidebar_label:"Extending the tool"},o={id:"05-u-extending-tool",isDocsHomePage:!1,title:"Extending the tool",description:"Want to enable a new metric or a language, need advanced post-analysis tool? Please, check the plugin development tutorial.",source:"@site/docs/05-u-extending-tool.md",permalink:"/docs/05-u-extending-tool",editUrl:"https://metrixplusplus.github.io/docs/05-u-extending-tool.md",sidebar_label:"Extending the tool",sidebar:"someSidebar",previous:{title:"Workflow",permalink:"/docs/04-u-workflow"},next:{title:"Feeback and contribute",permalink:"/docs/06-u-feeback-contribute"}},s=[{value:"Create plugin",id:"create-plugin",children:[]},{value:"Metric plugin",id:"metric-plugin",children:[{value:"Create placeholder for new plugin",id:"create-placeholder-for-new-plugin",children:[]},{value:"Toogle option for the plugin",id:"toogle-option-for-the-plugin",children:[]},{value:"Subscribe to notifications from parent plugins (or code parsers)",id:"subscribe-to-notifications-from-parent-plugins-or-code-parsers",children:[]},{value:"Implement simple metric based on regular expression pattern",id:"implement-simple-metric-based-on-regular-expression-pattern",children:[]},{value:"Extend regular expression incremental counting by smarter logic",id:"extend-regular-expression-incremental-counting-by-smarter-logic",children:[]},{value:"Language specific regular expressions",id:"language-specific-regular-expressions",children:[]},{value:"Store only non-zero metric values",id:"store-only-non-zero-metric-values",children:[]},{value:"Additional per metric configuration options",id:"additional-per-metric-configuration-options",children:[]},{value:"Summary",id:"summary",children:[]}]},{value:"Analysis tool plugin",id:"analysis-tool-plugin",children:[{value:"New Metrix++ command / action",id:"new-metrix-command--action",children:[]},{value:"Access data file loader and its interfaces",id:"access-data-file-loader-and-its-interfaces",children:[]},{value:"Identify added, modified files/regions and read metric data",id:"identify-added-modified-filesregions-and-read-metric-data",children:[]},{value:"Summary",id:"summary-1",children:[]}]},{value:"Language parser plugin",id:"language-parser-plugin",children:[]}],c={rightToc:s};function p(e){var t=e.components,n=Object(i.a)(e,["components"]);return Object(r.b)("wrapper",Object(a.a)({},c,n,{components:t,mdxType:"MDXLayout"}),Object(r.b)("p",null,"Want to enable a new metric or a language, need advanced post-analysis tool? Please, check the plugin development tutorial."),Object(r.b)("h2",{id:"create-plugin"},"Create plugin"),Object(r.b)("p",null,"There are 3 types of plugins considered in this chapter:"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"Metric plugin"),Object(r.b)("li",{parentName:"ul"},"Language parser"),Object(r.b)("li",{parentName:"ul"},"Post-processing / Analysis tool")),Object(r.b)("p",null,"Tutorial for metric plugin is generic at the beginning and large portion of this is applied to all other plugins. You need to know python and python regular expressions library to write Metrix++ extensions."),Object(r.b)("h2",{id:"metric-plugin"},"Metric plugin"),Object(r.b)("p",null,"The tutorial will explain how to create a plugin to count magic numbers in source code. It will be relatively simple at first and will be extended with additional configuration options and smarter counting logic."),Object(r.b)("h3",{id:"create-placeholder-for-new-plugin"},"Create placeholder for new plugin"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"All plugins are loaded by Metrix++ from standard places within the tool installation directory and from custom places specified in the METRIXPLUSPLUS_PATH environment variable. METRIXPLUSPLUS_PATH has got the same format as system PATH environment variable. So, the first step in plugin development is to set the METRIXPLUSPLUS_PATH to point out to the directory (or directories) where plugin is located."),Object(r.b)("li",{parentName:"ol"},"Create new python package 'myext', python lib 'magic.py' and 'magic.ini' file.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"+ working_directory (set in METRIXPLUSPLUS_PATH variable)\n\\--+ myext\n \\--- __init__.py\n \\--- magic.py\n \\--- magic.ini\n")),Object(r.b)("ol",{start:3},Object(r.b)("li",{parentName:"ol"},Object(r.b)("p",{parentName:"li"},"_","_init","_","_.py is empty file to make myext considered by python as a package.")),Object(r.b)("li",{parentName:"ol"},Object(r.b)("p",{parentName:"li"},"Edit magic.py to have the following content:"))),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),'import mpp.api\n \nclass Plugin(mpp.api.Plugin):\n \n def initialize(self):\n print "Hello world"\n')),Object(r.b)("p",null,'mpp.api package include Metrix++ API classes. mpp.api.Plugin is the base class, which can be loaded by Metrix++ engine and does nothing by default. In the code sample above it is extended to print "Hello world" on initialization.'),Object(r.b)("ol",{start:5},Object(r.b)("li",{parentName:"ol"},"Edit magic.ini to have the following content:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"[Plugin]\nversion: 1.0\npackage: myext\nmodule: magic\nclass: Plugin\ndepends: None\nactions: collect\nenabled: True\n")),Object(r.b)("p",null,"This file is a manifest for Metrix++ plugin loader. The fields in Plugin section are:"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"version")," -\na string representing the version, step up it every time when behaviour of a plugin or backward compatibility in api or data scope is changed"),Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"package")," -\npython package name where to load from"),Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"module")," -\npython module name (filename of *.py file) to load"),Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"class")," -\nname of a plugin class to instanciate"),Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"depends")," -\nlist of plugin names to load, if it this plugin is loaded"),Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"actions")," -\nlist of Metrix++ actions affected by this plugin"),Object(r.b)("li",{parentName:"ul"},Object(r.b)("strong",{parentName:"li"},"enabled")," -\nTrue or False, working status of a plugin")),Object(r.b)("ol",{start:6},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to see how this new plugin works:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"Hello world\n")),Object(r.b)("h3",{id:"toogle-option-for-the-plugin"},"Toogle option for the plugin"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"It is recommended to follow the convention for all plugins: 'run only if enabled'. So, let's extend the magic.py file to make it configurable.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),'import mpp.api\n \nclass Plugin(mpp.api.Plugin,\n # make this instance configurable...\n mpp.api.IConfigurable):\n # ... and implement 2 interfaces\n \n def declare_configuration(self, parser):\n parser.add_option("--myext.magic.numbers", "--mmn",\n action="store_true", default=False,\n help="Enables collection of magic numbers metric [default: %default]")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__[\'myext.magic.numbers\']\n \n def initialize(self):\n # use configuration option here\n if self.is_active_numbers == True:\n print "Hello world"\n')),Object(r.b)("p",null,"parser argument is an instance of optparse.OptionParser class. It has got an extension to accept multiple options of the same argument. Check std.tools.limit to see how to declare multiopt options, if you need."),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to see how this works:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"Hello world\n")),Object(r.b)("h3",{id:"subscribe-to-notifications-from-parent-plugins-or-code-parsers"},"Subscribe to notifications from parent plugins (or code parsers)"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"Every plugin works in a callback functions called by parent plugins. Callback receives a reference to parent plugin, data object where to store metrics data, and a flag indicating if there are changes in file or parent's settings since the previous collection.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),'import mpp.api\n \nclass Plugin(mpp.api.Plugin,\n mpp.api.IConfigurable,\n # declare that it can subscribe on notifications\n mpp.api.Child):\n \n def declare_configuration(self, parser):\n parser.add_option("--myext.magic.numbers", "--mmn",\n action="store_true", default=False,\n help="Enables collection of magic numbers metric [default: %default]")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__[\'myext.magic.numbers\']\n \n def initialize(self):\n if self.is_active_numbers == True:\n # subscribe to notifications from all code parsers\n self.subscribe_by_parents_interface(mpp.api.ICode, \'callback\')\n \n # parents (code parsers) will call the callback declared\n def callback(self, parent, data, is_updated):\n print parent.get_name(), data.get_path(), is_updated\n')),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to see how this works. Try to do iterative scans (--db-file-prev option) to see how the state of arguments is changed")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),"std.code.cpp ./test.cpp True\n")),Object(r.b)("h3",{id:"implement-simple-metric-based-on-regular-expression-pattern"},"Implement simple metric based on regular expression pattern"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"Callback may execute counting, searcing and additional parsing and store results, using data argument. 'data' argument is an instance of mpp.api.FileData class. However, most metrics can be implemented simplier, if mpp.api.MetricPluginMixin routines are used. MetricPluginMixin implements declarative style for metrics based on searches by regular expression. It cares about initialisation of database fields and properties. It implements default callback which counts number of matches by regular expression for all active declared metrics. So, let's utilise that:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\nimport re\n \nclass Plugin(mpp.api.Plugin,\n mpp.api.IConfigurable,\n mpp.api.Child,\n # reuse by inheriting standard metric facilities\n mpp.api.MetricPluginMixin):\n \n def declare_configuration(self, parser):\n parser.add_option(\"--myext.magic.numbers\", \"--mmn\",\n action=\"store_true\", default=False,\n help=\"Enables collection of magic numbers metric [default: %default]\")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__['myext.magic.numbers']\n \n def initialize(self):\n # declare metric rules\n self.declare_metric(\n self.is_active_numbers, # to count if active in callback\n self.Field('numbers', int), # field name and type in the database\n re.compile(r'''\\b[0-9]+\\b'''), # pattern to search\n marker_type_mask=mpp.api.Marker.T.CODE, # search in code\n region_type_mask=mpp.api.Region.T.ANY) # search in all types of regions\n \n # use superclass facilities to initialize everything from declared fields\n super(Plugin, self).initialize(fields=self.get_fields())\n \n # subscribe to all code parsers if at least one metric is active\n if self.is_active() == True:\n self.subscribe_by_parents_interface(mpp.api.ICode)\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to count numbers in code files.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("ol",{start:3},Object(r.b)("li",{parentName:"ol"},"Now view the results. At this stage it is fully working simple metric.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" view\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),":: info: Overall metrics for 'myext.magic:numbers' metric\n Average : 2.75\n Minimum : 0\n Maximum : 7\n Total : 11.0\n Distribution : 4 regions in total (including 0 suppressed)\n Metric value : Ratio : R-sum : Number of regions\n 0 : 0.250 : 0.250 : 1 |||||||||||||||||||||||||\n 1 : 0.250 : 0.500 : 1 |||||||||||||||||||||||||\n 3 : 0.250 : 0.750 : 1 |||||||||||||||||||||||||\n 7 : 0.250 : 1.000 : 1 |||||||||||||||||||||||||\n\n:: info: Directory content:\n Directory : .\n")),Object(r.b)("h3",{id:"extend-regular-expression-incremental-counting-by-smarter-logic"},"Extend regular expression incremental counting by smarter logic"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"At this stage the metric counts every number in source code. However, we indent to spot only 'magic' numbers. Declared constant is not a magic number, so it is better to exclude constants from counting. It is easy to change default counter behaviour by implementing a function with name '_<metric_name>_count'.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\nimport re\n \nclass Plugin(mpp.api.Plugin,\n mpp.api.IConfigurable,\n mpp.api.Child,\n mpp.api.MetricPluginMixin):\n \n def declare_configuration(self, parser):\n parser.add_option(\"--myext.magic.numbers\", \"--mmn\",\n action=\"store_true\", default=False,\n help=\"Enables collection of magic numbers metric [default: %default]\")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__['myext.magic.numbers']\n \n def initialize(self):\n # improve pattern to find declarations of constants\n pattern_to_search = re.compile(\n r'''((const(\\s+[_a-zA-Z][_a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n self.declare_metric(self.is_active_numbers,\n self.Field('numbers', int),\n # give a pair of pattern + custom counter logic class\n (pattern_to_search, self.NumbersCounter),\n marker_type_mask=mpp.api.Marker.T.CODE,\n region_type_mask=mpp.api.Region.T.ANY)\n \n super(Plugin, self).initialize(fields=self.get_fields())\n \n if self.is_active() == True:\n self.subscribe_by_parents_interface(mpp.api.ICode)\n \n # implement custom counter behavior:\n # increments counter by 1 only if single number spotted,\n # but not declaration of a constant\n class NumbersCounter(mpp.api.MetricPluginMixin.IterIncrementCounter):\n def increment(self, match):\n if match.group(0).startswith('const'):\n return 0\n return 1\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Initialy counter is initialized by zero, but it is possible to change it as well by implementing a function with name '_<metric_name>_count_initialize'. "),Object(r.b)("li",{parentName:"ol"},"Plugin we are implementing does not require this.\nNow run Metrix++ to collect and view the results.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" view\n')),Object(r.b)("h3",{id:"language-specific-regular-expressions"},"Language specific regular expressions"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"In the previous step we added matching of constants assuming that identifiers may have symbols '_', 'a-z', 'A-Z' and '0-9'. It is true for C++ but it is not complete for Java. Java identifier may have '$' symbol in the identifier. So, let's add language specific pattern in the declaration of the metric:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\nimport re\n \nclass Plugin(mpp.api.Plugin,\n mpp.api.IConfigurable,\n mpp.api.Child,\n mpp.api.MetricPluginMixin):\n \n def declare_configuration(self, parser):\n parser.add_option(\"--myext.magic.numbers\", \"--mmn\",\n action=\"store_true\", default=False,\n help=\"Enables collection of magic numbers metric [default: %default]\")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__['myext.magic.numbers']\n \n def initialize(self):\n # specialized pattern for java\n pattern_to_search_java = re.compile(\n r'''((const(\\s+[_$a-zA-Z][_$a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n # pattern for C++ and C# languages\n pattern_to_search_cpp_cs = re.compile(\n r'''((const(\\s+[_a-zA-Z][_a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n # pattern for all other languages\n pattern_to_search = re.compile(\n r'''\\b[0-9]+\\b''')\n self.declare_metric(self.is_active_numbers,\n self.Field('numbers', int),\n # dictionary of pairs instead of a single pair\n {\n 'std.code.java': (pattern_to_search_java, self.NumbersCounter),\n 'std.code.cpp': (pattern_to_search_cpp_cs, self.NumbersCounter),\n 'std.code.cs': (pattern_to_search_cpp_cs, self.NumbersCounter),\n '*': pattern_to_search\n },\n marker_type_mask=mpp.api.Marker.T.CODE,\n region_type_mask=mpp.api.Region.T.ANY)\n \n super(Plugin, self).initialize(fields=self.get_fields())\n \n if self.is_active() == True:\n self.subscribe_by_parents_interface(mpp.api.ICode)\n \n class NumbersCounter(mpp.api.MetricPluginMixin.IterIncrementCounter):\n def increment(self, match):\n if match.group(0).startswith('const'):\n return 0\n return 1\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Keys in the dictionary of patterns are names of parent plugins (references to code parsers). The key '*' refers to any parser."),Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to collect and view the results.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" view\n')),Object(r.b)("h3",{id:"store-only-non-zero-metric-values"},"Store only non-zero metric values"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"Most functions have the metric, which we are implemneting, equal to zero. However, we are interested in finding code blocks having this metric greater than zero. Zeros consumes the space in the data file. So, we can optimise the size of a data file, if we exclude zero metric values. Let's declare this behavior for the metric.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\nimport re\n \nclass Plugin(mpp.api.Plugin,\n mpp.api.IConfigurable,\n mpp.api.Child,\n mpp.api.MetricPluginMixin):\n \n def declare_configuration(self, parser):\n parser.add_option(\"--myext.magic.numbers\", \"--mmn\",\n action=\"store_true\", default=False,\n help=\"Enables collection of magic numbers metric [default: %default]\")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__['myext.magic.numbers']\n \n def initialize(self):\n pattern_to_search_java = re.compile(\n r'''((const(\\s+[_$a-zA-Z][_$a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n pattern_to_search_cpp_cs = re.compile(\n r'''((const(\\s+[_a-zA-Z][_a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n pattern_to_search = re.compile(\n r'''\\b[0-9]+\\b''')\n self.declare_metric(self.is_active_numbers,\n self.Field('numbers', int,\n # optimize the size of datafile:\n # store only non-zero results\n non_zero=True),\n {\n 'std.code.java': (pattern_to_search_java, self.NumbersCounter),\n 'std.code.cpp': (pattern_to_search_cpp_cs, self.NumbersCounter),\n 'std.code.cs': (pattern_to_search_cpp_cs, self.NumbersCounter),\n '*': pattern_to_search\n },\n marker_type_mask=mpp.api.Marker.T.CODE,\n region_type_mask=mpp.api.Region.T.ANY)\n \n super(Plugin, self).initialize(fields=self.get_fields())\n \n if self.is_active() == True:\n self.subscribe_by_parents_interface(mpp.api.ICode)\n \n class NumbersCounter(mpp.api.MetricPluginMixin.IterIncrementCounter):\n def increment(self, match):\n if match.group(0).startswith('const'):\n return 0\n return 1\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to collect and view the results.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" view\n')),Object(r.b)("h3",{id:"additional-per-metric-configuration-options"},"Additional per metric configuration options"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"It is typical that most numbers counted by the metric are equal to 0, -1 or 1. They are not necessary magic numbers. 0 or 1 are typical variable initializers. -1 is a typical negative return code. So, let's implement simplified version of the metric, which does not count 0, -1 and 1, if the specific new option is set.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\nimport re\n \nclass Plugin(mpp.api.Plugin,\n mpp.api.IConfigurable,\n mpp.api.Child,\n mpp.api.MetricPluginMixin):\n \n def declare_configuration(self, parser):\n parser.add_option(\"--myext.magic.numbers\", \"--mmn\",\n action=\"store_true\", default=False,\n help=\"Enables collection of magic numbers metric [default: %default]\")\n # Add new option\n parser.add_option(\"--myext.magic.numbers.simplier\", \"--mmns\",\n action=\"store_true\", default=False,\n help=\"Is set, 0, -1 and 1 numbers are not counted [default: %default]\")\n \n def configure(self, options):\n self.is_active_numbers = options.__dict__['myext.magic.numbers']\n # remember the option here\n self.is_active_numbers_simplier = options.__dict__['myext.magic.numbers.simplier']\n \n def initialize(self):\n pattern_to_search_java = re.compile(\n r'''((const(\\s+[_$a-zA-Z][_$a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n pattern_to_search_cpp_cs = re.compile(\n r'''((const(\\s+[_a-zA-Z][_a-zA-Z0-9]*)+\\s*[=]\\s*)[-+]?[0-9]+\\b)|(\\b[0-9]+\\b)''')\n pattern_to_search = re.compile(\n r'''\\b[0-9]+\\b''')\n self.declare_metric(self.is_active_numbers,\n self.Field('numbers', int,\n non_zero=True),\n {\n 'std.code.java': (pattern_to_search_java, self.NumbersCounter),\n 'std.code.cpp': (pattern_to_search_cpp_cs, self.NumbersCounter),\n 'std.code.cs': (pattern_to_search_cpp_cs, self.NumbersCounter),\n '*': pattern_to_search\n },\n marker_type_mask=mpp.api.Marker.T.CODE,\n region_type_mask=mpp.api.Region.T.ANY)\n \n super(Plugin, self).initialize(fields=self.get_fields(),\n # remember option settings in data file properties\n # in order to detect changes in settings on iterative re-run\n properties=[self.Property('number.simplier', self.is_active_numbers_simplier)])\n \n if self.is_active() == True:\n self.subscribe_by_parents_interface(mpp.api.ICode)\n \n class NumbersCounter(mpp.api.MetricPluginMixin.IterIncrementCounter):\n def increment(self, match):\n if (match.group(0).startswith('const') or\n (self.plugin.is_active_numbers_simplier == True and\n match.group(0) in ['0', '1', '-1', '+1'])):\n return 0\n return 1\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to collect and view the results.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" collect --myext.magic.numbers\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" view\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),":: info: Overall metrics for 'myext.magic:numbers' metric\n Average : 2.5 (excluding zero metric values)\n Minimum : 2\n Maximum : 3\n Total : 5.0\n Distribution : 2 regions in total (including 0 suppressed)\n Metric value : Ratio : R-sum : Number of regions\n 2 : 0.500 : 0.500 : 1 ||||||||||||||||||||||||||||||||||||||||||||||||||\n 3 : 0.500 : 1.000 : 1 ||||||||||||||||||||||||||||||||||||||||||||||||||\n\n:: info: Directory content:\n Directory : .\n")),Object(r.b)("h3",{id:"summary"},"Summary"),Object(r.b)("p",null,"We have finished with the tutorial. The tutorial explained how to implement simple and advanced metric plugins. We used built-in Metrix++ base classes. If you need to more advanced plugin capabilities, override in your plugin class functions inherited from mpp.api base classes. Check code of standard plugins to learn more techniques."),Object(r.b)("h2",{id:"analysis-tool-plugin"},"Analysis tool plugin"),Object(r.b)("p",null,"This tutorial will explain how to build custom Metrix++ command, which is bound to custom post-analysis tool. We will implement the tool, which identifies all new and changed regions and counts number of added lines. We skip calculating number of deleted lines, but it is easy to extend from what we get finally in the tutorial."),Object(r.b)("h3",{id:"new-metrix-command--action"},"New Metrix++ command / action"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"As in the tutorial for metric plugin, set the environment and create new python package 'myext', python lib 'compare.py' and 'compare.ini' file.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"+ working_directory (set in METRIXPLUSPLUS_PATH variable)\n\\--+ myext\n \\--- __init__.py\n \\--- compare.py\n \\--- compare.ini\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},Object(r.b)("p",{parentName:"li"},Object(r.b)("strong",{parentName:"p"},"init"),".py is empty file to make myext considered by python as a package.")),Object(r.b)("li",{parentName:"ol"},Object(r.b)("p",{parentName:"li"},"Edit compare.py to have the following content:"))),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\n \nclass Plugin(mpp.api.Plugin, mpp.api.IRunable):\n \n def run(self, args):\n print args\n return 0\n")),Object(r.b)("p",null,"Inheritance from mpp.api.IRunable declares that the plugin is runable and requires implementation of 'run' interface."),Object(r.b)("ol",{start:4},Object(r.b)("li",{parentName:"ol"},"Edit compare.ini to have the following content:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"[Plugin]\nversion: 1.0\npackage: myext\nmodule: compare\nclass: Plugin\ndepends: None\nactions: compare\nenabled: True\n")),Object(r.b)("p",null,"This file is a manifest for Metrix++ plugin loader. Actions field has got new value 'compare'. Metrix++ engine will automatically pick this action and will add it to the list of available commands. This plugin will be loaded on 'compare' action."),Object(r.b)("ol",{start:5},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to see how this new plugin works:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" compare -- path1 path2 path3\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),'["path1", "path2", "path3"]\n')),Object(r.b)("h3",{id:"access-data-file-loader-and-its-interfaces"},"Access data file loader and its interfaces"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"By default, all post-analysis tools have got --db-file and --db-file-prev options. It is because 'mpp.dbf' plugin is loaded for any action, including our new one 'compare'. In order to continue the tutorial, we need to have 2 data files with 'std.code.lines:total' metric collected. So, write to files by running:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> cd my_project_version_1\n> python "/path/to/metrix++.py" collect --std.code.lines.total\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> cd my_project_version_2\n> python "/path/to/metrix++.py" collect --std.code.lines.total\n')),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Edit compare.py file to get the loader and iterate collected file paths:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-py"}),"import mpp.api\n# load common utils for post processing tools\nimport mpp.utils\n \nclass Plugin(mpp.api.Plugin, mpp.api.IRunable):\n \n def run(self, args):\n # get data file reader using standard metrix++ plugin\n loader = self.get_plugin('mpp.dbf').get_loader()\n \n # iterate and print file length for every path in args\n exit_code = 0\n for path in (args if len(args) > 0 else [\"\"]):\n file_iterator = loader.iterate_file_data(path)\n if file_iterator == None:\n mpp.utils.report_bad_path(path)\n exit_code += 1\n continue\n for file_data in file_iterator:\n print file_data.get_path()\n return exit_code\n")),Object(r.b)("ol",{start:3},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to see how it works:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" compare --db-file=my_project_version_2/metrixpp.db --db-file-prev=my_project_version_1/metrixpp.db\n')),Object(r.b)("h3",{id:"identify-added-modified-filesregions-and-read-metric-data"},"Identify added, modified files/regions and read metric data"),Object(r.b)("ol",null,Object(r.b)("li",{parentName:"ol"},"Let's extend the logic of the tool to compare files and regions, read 'std.code.lines:total' metric and calcuate the summary of number of added lines. mpp.utils.FileRegionsMatcher is helper class which does matching and comparison of regions for 2 given mpp.api.FileData objects.")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),"import mpp.api\nimport mpp.utils\nimport mpp.cout\n \nclass Plugin(mpp.api.Plugin, mpp.api.IRunable):\n \n def run(self, args):\n loader = self.get_plugin('mpp.dbf').get_loader()\n # get previous db file loader\n loader_prev = self.get_plugin('mpp.dbf').get_loader_prev()\n \n exit_code = 0\n for path in (args if len(args) > 0 else [\"\"]):\n added_lines = 0\n file_iterator = loader.iterate_file_data(path)\n if file_iterator == None:\n mpp.utils.report_bad_path(path)\n exit_code += 1\n continue\n for file_data in file_iterator:\n added_lines += self._compare_file(file_data, loader, loader_prev)\n mpp.cout.notify(path, '', mpp.cout.SEVERITY_INFO,\n \"Change trend report\",\n [('Added lines', added_lines)])\n return exit_code\n \n def _compare_file(self, file_data, loader, loader_prev):\n # compare file with previous and return number of new lines\n file_data_prev = loader_prev.load_file_data(file_data.get_path())\n if file_data_prev == None:\n return self._sum_file_regions_lines(file_data)\n elif file_data.get_checksum() != file_data_prev.get_checksum():\n return self._compare_file_regions(file_data, file_data_prev)\n \n def _sum_file_regions_lines(self, file_data):\n # just sum up the metric for all regions\n result = 0\n for region in file_data.iterate_regions():\n result += region.get_data('std.code.lines', 'total')\n \n def _compare_file_regions(self, file_data, file_data_prev):\n # compare every region with previous and return number of new lines\n matcher = mpp.utils.FileRegionsMatcher(file_data, file_data_prev)\n result = 0\n for region in file_data.iterate_regions():\n if matcher.is_matched(region.get_id()) == False:\n # if added region, just add the lines\n result += region.get_data('std.code.lines', 'total')\n elif matcher.is_modified(region.get_id()):\n # if modified, add the difference in lines\n region_prev = file_data_prev.get_region(\n matcher.get_prev_id(region.get_id()))\n result += (region.get_data('std.code.lines', 'total') -\n region_prev.get_data('std.code.lines', 'total'))\n return result\n")),Object(r.b)("ol",{start:2},Object(r.b)("li",{parentName:"ol"},"Now run Metrix++ to see how it works:")),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{className:"language-bash"}),'> python "/path/to/metrix++.py" compare --db-file=my_project_version_2/metrixpp.db --db-file-prev=my_project_version_1/metrixpp.db\n')),Object(r.b)("pre",null,Object(r.b)("code",Object(a.a)({parentName:"pre"},{}),":: info: Change trend report\n Added lines : 7\n")),Object(r.b)("h3",{id:"summary-1"},"Summary"),Object(r.b)("p",null,"We have finished with the tutorial. The tutorial explained how to read Metrix++ data files and implement custom post-processing tools. Even if some existing Metrix++ code requires clean-up and refactoring, check code of standard tool plugins to learn more techniques."),Object(r.b)("h2",{id:"language-parser-plugin"},"Language parser plugin"),Object(r.b)("p",null,"Unfortunately, there is no good documentation at this stage for this part. Briefly, if metric plugin counts and stores data into FileData object, tool plugin reads this data, language plugin construct the original structure of FileData object. The orginal structure includes regions (like functions, classes, etc.) and markers (like comments, strings, preprocessor, etc.). Check code of existing parsers:"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"a language parser plugin is registered in the same way as a metric plugin"),Object(r.b)("li",{parentName:"ul"},"it registers parser's callback in 'std.tools.collect' plugin"),Object(r.b)("li",{parentName:"ul"},"parses a file in a callback, called by 'std.tools.collect'"),Object(r.b)("li",{parentName:"ul"},"parser needs to identify markers and regions and tell about this to file data object passed as an argument for the callback.")),Object(r.b)("p",null,"There are useful options and tools avaialble for trobuleshooting purposes during development:"),Object(r.b)("ul",null,Object(r.b)("li",{parentName:"ul"},"metrix++.py debug generates html code showing parsed code structures and their boundaries"),Object(r.b)("li",{parentName:"ul"},"--nest-regions for view tool forces the viewer to indent subregions."),Object(r.b)("li",{parentName:"ul"},"--log-level option is available for any command and is helpful to trace execution.")),Object(r.b)("p",null,"Finally, if there are any questions or enquires, please, feel free to ",Object(r.b)("a",Object(a.a)({parentName:"p"},{href:"https://github.com/metrixplusplus/metrixplusplus/issues/new"}),"submit new question"),"."))}p.isMDXComponent=!0},117:function(e,t,n){"use strict";n.d(t,"a",(function(){return m})),n.d(t,"b",(function(){return d}));var a=n(0),i=n.n(a);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function l(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function o(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?l(Object(n),!0).forEach((function(t){r(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):l(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function s(e,t){if(null==e)return{};var n,a,i=function(e,t){if(null==e)return{};var n,a,i={},r=Object.keys(e);for(a=0;a<r.length;a++)n=r[a],t.indexOf(n)>=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a<r.length;a++)n=r[a],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var c=i.a.createContext({}),p=function(e){var t=i.a.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},m=function(e){var t=p(e.components);return i.a.createElement(c.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return i.a.createElement(i.a.Fragment,{},t)}},b=i.a.forwardRef((function(e,t){var n=e.components,a=e.mdxType,r=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),m=p(n),b=a,d=m["".concat(l,".").concat(b)]||m[b]||u[b]||r;return n?i.a.createElement(d,o(o({ref:t},c),{},{components:n})):i.a.createElement(d,o({ref:t},c))}));function d(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var r=n.length,l=new Array(r);l[0]=b;var o={};for(var s in t)hasOwnProperty.call(t,s)&&(o[s]=t[s]);o.originalType=e,o.mdxType="string"==typeof e?e:a,l[1]=o;for(var c=2;c<r;c++)l[c]=n[c];return i.a.createElement.apply(null,l)}return i.a.createElement.apply(null,n)}b.displayName="MDXCreateElement"}}]);
|
