| <!DOCTYPE html> |
| |
| |
| |
| |
| <html class="no-js"> |
| |
| <head lang="en-us"> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,user-scalable=no,initial-scale=1,maximum-scale=1"> |
| <meta http-equiv="X-UA-Compatible" content="IE=10" /> |
| <title>Packages - Eclipse Mita</title> |
| <meta name="generator" content="Hugo 0.42.1" /> |
| |
| |
| <meta name="description" content="The documentation of Eclipse Mita."> |
| |
| <link rel="canonical" href="../../language/packages/"> |
| |
| |
| <meta property="og:url" content="/language/packages/"> |
| <meta property="og:title" content="Eclipse Mita"> |
| <meta property="og:image" content="/images/mita.svg"> |
| <meta name="apple-mobile-web-app-title" content="Eclipse Mita"> |
| <meta name="apple-mobile-web-app-capable" content="yes"> |
| <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"> |
| |
| <link rel="shortcut icon" type="image/x-icon" href="../../images/favicon.ico"> |
| <link rel="icon" type="image/x-icon" href="../../images/favicon.ico"> |
| |
| <style> |
| @font-face { |
| font-family: 'Icon'; |
| src: url('/fonts/icon.eot'); |
| src: url('/fonts/icon.eot') |
| format('embedded-opentype'), |
| url('/fonts/icon.woff') |
| format('woff'), |
| url('/fonts/icon.ttf') |
| format('truetype'), |
| url('/fonts/icon.svg') |
| format('svg'); |
| font-weight: normal; |
| font-style: normal; |
| } |
| </style> |
| |
| <link rel="stylesheet" href="../../stylesheets/application.css"> |
| <link rel="stylesheet" href="../../stylesheets/temporary.css"> |
| <link rel="stylesheet" href="../../stylesheets/palettes.css"> |
| <link rel="stylesheet" href="../../stylesheets/highlight/highlight.css"> |
| |
| |
| |
| |
| <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Ubuntu:400,700|Ubuntu+Mono"> |
| <style> |
| body, input { |
| font-family: 'Ubuntu', Helvetica, Arial, sans-serif; |
| } |
| pre, code { |
| font-family: 'Ubuntu Mono', 'Courier New', 'Courier', monospace; |
| } |
| </style> |
| |
| |
| <link rel="stylesheet" href="../../css/custom.css"> |
| |
| <script src="../../javascripts/modernizr.js"></script> |
| |
| |
| |
| </head> |
| <body class="palette-primary-blue-grey palette-accent-light-blue"> |
| |
| |
| |
| |
| <div class="backdrop"> |
| <div class="backdrop-paper"></div> |
| </div> |
| |
| <input class="toggle" type="checkbox" id="toggle-drawer"> |
| <input class="toggle" type="checkbox" id="toggle-search"> |
| <label class="toggle-button overlay" for="toggle-drawer"></label> |
| |
| <header class="header"> |
| <nav aria-label="Header"> |
| <div class="bar default"> |
| <div class="button button-menu" role="button" aria-label="Menu"> |
| <label class="toggle-button icon icon-menu" for="toggle-drawer"> |
| <span></span> |
| </label> |
| </div> |
| <div class="stretch"> |
| <div class="title"> |
| Packages |
| </div> |
| </div> |
| |
| |
| <div class="button button-twitter" role="button" aria-label="Twitter"> |
| <a href="https://twitter.com/eclipse_mita" title="@eclipse_mita on Twitter" target="_blank" class="toggle-button icon icon-twitter"></a> |
| </div> |
| |
| |
| |
| <div class="button button-github" role="button" aria-label="GitHub"> |
| <a href="https://github.com/eclipse/mita" title="@eclipse/mita on GitHub" target="_blank" class="toggle-button icon icon-github"></a> |
| </div> |
| |
| |
| |
| </div> |
| <div class="bar search"> |
| <div class="button button-close" role="button" aria-label="Close"> |
| <label class="toggle-button icon icon-back" for="toggle-search"></label> |
| </div> |
| <div class="stretch"> |
| <div class="field"> |
| <input class="query" type="text" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck> |
| </div> |
| </div> |
| <div class="button button-reset" role="button" aria-label="Search"> |
| <button class="toggle-button icon icon-close" id="reset-search"></button> |
| </div> |
| </div> |
| </nav> |
| </header> |
| |
| <main class="main"> |
| <div class="drawer"> |
| <nav aria-label="Navigation"> |
| <a href="../../" class="project"> |
| <div class="banner"> |
| |
| <div class="logo"> |
| <img src="../../images/mita.svg"> |
| </div> |
| |
| <div class="name"> |
| <strong>Eclipse Mita </strong> |
| |
| </div> |
| </div> |
| </a> |
| |
| <div class="scrollable"> |
| <div class="wrapper"> |
| |
| |
| <div class="toc"> |
| |
| <ul> |
| |
| |
| |
| |
| |
| <li> |
| |
| |
| |
| |
| |
| <a title="Download" href="http://github.com/eclipse/mita"> |
| |
| Download |
| </a> |
| |
| |
| |
| |
| </li> |
| |
| |
| |
| <li> |
| |
| |
| |
| |
| |
| <a title="Concepts" href="../../concepts/"> |
| |
| Concepts |
| </a> |
| |
| |
| |
| |
| </li> |
| |
| |
| |
| <li> |
| |
| <span class="section">Language</span> |
| <ul> |
| |
| |
| |
| |
| |
| |
| <a title="Introduction" href="../../language/introduction/"> |
| |
| Introduction |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Basics" href="../../language/basics/"> |
| |
| Basics |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a class="current" title="Packages" href="../../language/packages/"> |
| |
| Packages |
| </a> |
| |
| |
| <ul id="scrollspy"> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="System Setup" href="../../language/setup/"> |
| |
| System Setup |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Types" href="../../language/types/"> |
| |
| Types |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Arrays" href="../../language/arrays/"> |
| |
| Arrays |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Functions" href="../../language/functions/"> |
| |
| Functions |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Foreign Function Interface" href="../../language/foreignfunctioninterface/"> |
| |
| Foreign Function Interface |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Events" href="../../language/events/"> |
| |
| Events |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a title="Exceptions" href="../../language/exceptions/"> |
| |
| Exceptions |
| </a> |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| <li> |
| |
| <span class="section">Platforms</span> |
| <ul> |
| |
| |
| |
| |
| |
| |
| <a title="XDK110" href="../../platforms/xdk110/"> |
| |
| XDK110 |
| </a> |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| </ul> |
| |
| |
| |
| </div> |
| </div> |
| </div> |
| </nav> |
| |
| </div> |
| |
| <article class="article"> |
| <div class="wrapper"> |
| <h1>Packages </h1> |
| |
| |
| |
| <p>In Mita code is organized in packages, which serve multiple purposes:</p> |
| |
| <ul> |
| <li><strong>Divide the namespace</strong>: Mita programs have one global namespace per <code>.x</code> file. Unlike Java for example, there are no means to qualify the name of an element. Packages are used to keep this namespace clean. Only things which are explicitly imported from other packages are visible in that namespace. See <a href="#importing-packages">Importing Packages</a> for more details.</li> |
| <li><strong>Group code</strong>: packages are a formidable way to group code which conceptually belongs together. Where other languages have modules or classes, Mita uses packages.</li> |
| <li><strong>Hide information</strong>: in Mita visibility of functions, types and the likes is decided on a package level. There are only two levels of visibility: things are either visible outside a package or they are not. This is very similar to how NodeJS manages visibility (think <code>module.export</code>) or how Go does it (uppercase functions/structure members/types get exported). See <a href="#hiding-information-visibility">Hiding Information</a> for more details.</li> |
| </ul> |
| |
| <p>All Mita code belongs to a particular package. Thus, the first line in every <code>.x</code> file is the <code>package</code> statement. The main application logic, for example, by convention is in the <code>main</code> package:</p> |
| <div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span> |
| |
| <span class="p">...</span></code></pre></div> |
| <h2 id="naming-conventions">Naming Conventions</h2> |
| |
| <p>Just now we have seen the first naming convention: the core application logic and system setup are in the <code>main</code> package. |
| The platforms which we import – each Mita program needs to import a platform – are by convention found in the <code>platforms</code> package. |
| The <a href="{{ < ref "/platforms/xdk110.md" > }}">XDK110 platform</a> for example is in the <code>platforms.xdk110</code> package.</p> |
| |
| <p>All in all you are free to name your packages however you like. The files which constitute your package content can be located wherever in the project. However, it is a good idea to replicate the logical package structure in folders. For example:</p> |
| <div class="highlight"><pre class="chroma"><code class="language-Pre" data-lang="Pre"><span class="nx">algorithm</span><span class="o">/</span> |
| <span class="p">|</span><span class="o">-</span> <span class="nx">api</span><span class="p">.</span><span class="nx">x</span> <span class="kn">package</span> <span class="nx">algorithm</span> |
| <span class="p">|</span><span class="o">-</span> <span class="nx">statistics</span><span class="p">.</span><span class="nx">x</span> <span class="kn">package</span> <span class="nx">algorithm</span><span class="p">.</span><span class="nx">statistics</span> |
| <span class="err">\</span><span class="o">-</span> <span class="nx">structures</span><span class="p">.</span><span class="nx">x</span> <span class="kn">package</span> <span class="nx">algorithm</span><span class="p">.</span><span class="nx">structures</span> |
| <span class="nx">main</span><span class="p">.</span><span class="nx">x</span> <span class="kn">package</span> <span class="nx">main</span></code></pre></div> |
| <p>Notice how we use a dot <code>.</code> to indicate a sub-package relationship. |
| This is merely a convention and has no influence on visibility or any other implication.</p> |
| |
| <h2 id="importing-packages">Importing Packages</h2> |
| |
| <p>Packages divide the namespace, which is the space in which the names of functions and types have to be unique. |
| Within a package all type names and functions (save for <a href="{{ < ref "/platforms/xdk110.md" > }}">polymorphism</a>) have to be unique. |
| When we import a package, we import all names from that namespace into our local program. Consider the following example:</p> |
| <div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="c1">// file: mypackage.x |
| </span><span class="c1"></span><span class="kr">package</span> <span class="nx">mypackage</span><span class="p">;</span> |
| <span class="p">...</span> |
| |
| <span class="kr">export</span> <span class="nx">fn</span> <span class="nx">answerTheQuestion() {</span> |
| <span class="k">return</span> <span class="mi">42</span><span class="p">;</span> |
| <span class="p">}</span> |
| |
| <span class="c1">// file: application.x |
| </span><span class="c1"></span><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span> |
| <span class="kr">import</span> <span class="nx">mypackage</span><span class="p">;</span> |
| |
| <span class="nx">every</span> <span class="nx">XDK110</span><span class="p">.</span><span class="nx">startup</span> <span class="p">{</span> |
| <span class="nx">println</span><span class="p">(</span><span class="sb">`The answer: </span><span class="si">${</span><span class="nx">answerTheQuestion</span><span class="p">()</span><span class="si">}</span><span class="sb">`</span><span class="p">);</span> |
| <span class="p">}</span></code></pre></div> |
| <p>If it were not for the <code>import mypackage</code> statement, the <code>answerTheQuestion</code> function would not be visible in <code>application.x</code>.</p> |
| |
| <p>To import a package use the <code>import</code> statement. We have seen those in previous examples when we imported the platform, which is mandatory. Thus, every Mita program file must have at least one import: the platform import. |
| For example:</p> |
| <div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span> |
| <span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span> |
| |
| <span class="p">...</span></code></pre></div> |
| <p>You can shadow imported names within the current file. If in the example above <code>application.x</code> defined its own <code>answerTheQuestion()</code> function, all code within <code>application.x</code> would refer to that one instead of the imported function.</p> |
| |
| <h2 id="hiding-information-visibility">Hiding Information (Visibility)</h2> |
| |
| <p>By default nothing is visible outside a package, nothing is exported to the outside world. This way, if you want to make things available outside the package, that has to be a conscious decision. To do so, mark what you want to export with the <code>export</code> keyword. For example:</p> |
| <div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">utility</span><span class="p">;</span> |
| <span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span> |
| |
| <span class="nx">fn</span> <span class="nx">saturate</span><span class="p">(</span><span class="nx">config</span> : <span class="kt">PidController</span><span class="p">)</span> <span class="p">{</span> |
| <span class="p">...</span> |
| <span class="p">}</span> |
| |
| <span class="kr">export</span> <span class="nx">fn</span> <span class="nx">control</span><span class="p">(</span><span class="nx">config</span> : <span class="kt">PidController</span><span class="p">,</span> <span class="nx">input</span> : <span class="kt">int32</span><span class="p">)</span> <span class="o">:</span> <span class="nx">int32</span> <span class="p">{</span> |
| <span class="p">...</span> |
| <span class="nx">saturate</span><span class="p">(</span><span class="nx">config</span><span class="p">);</span> |
| <span class="p">...</span> |
| <span class="p">}</span></code></pre></div> |
| <p>In this example, the <code>saturate</code> function is not visible outside the <code>utility</code> package, but the <code>control</code> function is because it is marked with the <code>export</code> keyword. |
| This allows you to hide functions and types which are not meant for consumption outside of package and thus to provide a well defined API. |
| The generated C code will respect your export choices and mark non-exported objects as <code>static</code> which is “C speak” for <em>visible only within the same file</em>.</p> |
| |
| |
| <aside class="copyright" role="note"> |
| |
| © 2018 The Eclipse Mita Project – |
| |
| Documentation built with |
| <a href="https://www.gohugo.io" target="_blank">Hugo</a> |
| using the |
| <a href="http://github.com/digitalcraftsman/hugo-material-docs" target="_blank">Material</a> theme. |
| </aside> |
| |
| <footer class="footer"> |
| |
| |
| <nav class="pagination" aria-label="Footer"> |
| <div class="previous"> |
| |
| <a href="../../language/basics/" title="Basics"> |
| <span class="direction"> |
| Previous |
| </span> |
| <div class="page"> |
| <div class="button button-previous" role="button" aria-label="Previous"> |
| <i class="icon icon-back"></i> |
| </div> |
| <div class="stretch"> |
| <div class="title"> |
| Basics |
| </div> |
| </div> |
| </div> |
| </a> |
| |
| </div> |
| |
| <div class="next"> |
| |
| <a href="../../language/setup/" title="System Setup"> |
| <span class="direction"> |
| Next |
| </span> |
| <div class="page"> |
| <div class="stretch"> |
| <div class="title"> |
| System Setup |
| </div> |
| </div> |
| <div class="button button-next" role="button" aria-label="Next"> |
| <i class="icon icon-forward"></i> |
| </div> |
| </div> |
| </a> |
| |
| </div> |
| </nav> |
| |
| |
| |
| |
| |
| </footer> |
| </div> |
| </article> |
| |
| <div class="results" role="status" aria-live="polite"> |
| <div class="scrollable"> |
| <div class="wrapper"> |
| <div class="meta"></div> |
| <div class="list"></div> |
| </div> |
| </div> |
| </div> |
| </main> |
| |
| <script> |
| |
| var base_url = ''; |
| var repo_id = ''; |
| |
| </script> |
| |
| <script src="../../javascripts/application.js"></script> |
| |
| |
| <script> |
| /* Add headers to scrollspy */ |
| var headers = document.getElementsByTagName("h2"); |
| var scrollspy = document.getElementById('scrollspy'); |
| |
| if(scrollspy) { |
| if(headers.length > 0) { |
| for(var i = 0; i < headers.length; i++) { |
| var li = document.createElement("li"); |
| li.setAttribute("class", "anchor"); |
| |
| var a = document.createElement("a"); |
| a.setAttribute("href", "#" + headers[i].id); |
| a.setAttribute("title", headers[i].innerHTML); |
| a.innerHTML = headers[i].innerHTML; |
| |
| li.appendChild(a) |
| scrollspy.appendChild(li); |
| } |
| } else { |
| scrollspy.parentElement.removeChild(scrollspy) |
| } |
| |
| |
| /* Add permanent link next to the headers */ |
| var headers = document.querySelectorAll("h1, h2, h3, h4, h5, h6"); |
| |
| for(var i = 0; i < headers.length; i++) { |
| var a = document.createElement("a"); |
| a.setAttribute("class", "headerlink"); |
| a.setAttribute("href", "#" + headers[i].id); |
| a.setAttribute("title", "Permanent link") |
| a.innerHTML = "#"; |
| headers[i].appendChild(a); |
| } |
| } |
| </script> |
| |
| |
| |
| <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.8.0/highlight.min.js"></script> |
| <script>hljs.initHighlightingOnLoad();</script> |
| </body> |
| </html> |
| |
