https://pluto-lang.org/assets/js/3ba36259.691dc0c6.js

1"use strict";(self.webpackChunkpluto=self.webpackChunkpluto||[]).push([[118],{5572:(e,s,i)=>{i.r(s),i.d(s,{assets:()=>c,contentTitle:()=>t,default:()=>h,frontMatter:()=>r,metadata:()=>l,toc:()=>d});const l=JSON.parse('{"id":"Compatibility","title":"Compatibility","description":"Pluto aims to be source- and bytecode-compatible with existing Lua code such that it can simply be used as a drop-in replacement for Lua, and Lua modules can simply be used in Pluto codebases. In the vast majority of cases, we do succeed, but there are a few things to be aware of.","source":"@site/docs/Compatibility.md","sourceDirName":".","slug":"/Compatibility","permalink":"/docs/Compatibility","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":11,"frontMatter":{"sidebar_position":11},"sidebar":"tutorialSidebar","previous":{"title":"Bindings","permalink":"/docs/Bindings"},"next":{"title":"For Integrators","permalink":"/docs/For Integrators"}}');var o=i(4848),n=i(8453);const r={sidebar_position:11},t=void 0,c={},d=[{value:"New Keywords",id:"new-keywords",level:2},{value:"Compatibility Mode",id:"compatibility-mode",level:3},{value:"Compile-time Configuration (pluto_use)",id:"compile-time-configuration-pluto_use",level:3},{value:"Compatible Keywords",id:"compatible-keywords",level:3}];function a(e){const s={a:"a",code:"code",div:"div",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",span:"span",strong:"strong",ul:"ul",...(0,n.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(s.p,{children:"Pluto aims to be source- and bytecode-compatible with existing Lua code such that it can simply be used as a drop-in replacement for Lua, and Lua modules can simply be used in Pluto codebases. In the vast majority of cases, we do succeed, but there are a few things to be aware of."}),"\n",(0,o.jsx)(s.h2,{id:"new-keywords",children:"New Keywords"}),"\n",(0,o.jsxs)(s.p,{children:["While Pluto does add a handful of new keywords (",(0,o.jsx)(s.code,{children:"switch"}),", ",(0,o.jsx)(s.code,{children:"continue"}),", ",(0,o.jsx)(s.code,{children:"enum"}),", ",(0,o.jsx)(s.code,{children:"new"}),", ",(0,o.jsx)(s.code,{children:"class"}),", ",(0,o.jsx)(s.code,{children:"parent"}),", ",(0,o.jsx)(s.code,{children:"export"}),", ",(0,o.jsx)(s.code,{children:"try"}),", ",(0,o.jsx)(s.code,{children:"catch"}),"), it can automatically infer when these are used as identifiers to preserve compatibility with Lua:"]}),"\n",(0,o.jsxs)(s.pre,{className:"shiki monokai",style:{backgroundColor:"#272822",color:"#F8F8F2"},children:[(0,o.jsx)(s.div,{className:"language-id",children:"lua"}),(0,o.jsx)(s.div,{className:"code-container",children:(0,o.jsxs)(s.code,{children:[(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"local"}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" class "}),(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"="}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#E6DB74"},children:'"supercar"'})]}),(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#66D9EF"},children:"print"}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:"("}),(0,o.jsx)(s.span,{style:{color:"#E6DB74"},children:'"it\'s a "'}),(0,o.jsx)(s.span,{style:{color:"#F92672"},children:".."}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:"class) "}),(0,o.jsx)(s.span,{style:{color:"#88846F"},children:"--\x3e it's a supercar"})]})]})})]}),"\n",(0,o.jsx)(s.p,{children:"However, if a script does actually end up using a feature, its respective keyword can no longer be used as an identifier:"}),"\n",(0,o.jsxs)(s.pre,{className:"shiki monokai",style:{backgroundColor:"#272822",color:"#F8F8F2"},children:[(0,o.jsx)(s.div,{className:"language-id",children:"pluto"}),(0,o.jsx)(s.div,{className:"code-container",children:(0,o.jsxs)(s.code,{children:[(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#66D9EF",fontStyle:"italic"},children:"class"}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#A6E22E"},children:"Vehicle"})]}),(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:"    "}),(0,o.jsx)(s.span,{style:{color:"#88846F"},children:"-- ..."})]}),(0,o.jsx)(s.div,{className:"line",children:(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"end"})}),(0,o.jsx)(s.div,{className:"line"}),(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"local"}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#66D9EF",fontStyle:"italic"},children:"class"}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"="}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#E6DB74"},children:'"supercar"'}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#88846F"},children:"-- Error: expected a class name, found '='"})]})]})})]}),"\n",(0,o.jsxs)(s.p,{children:["The only exception to this is short-hand table syntax and goto labels because Pluto ",(0,o.jsx)(s.a,{href:"QoL%20Improvements/Reserved%20Identifiers",children:"allows reserved keywords to be used in those contexts"}),"."]}),"\n",(0,o.jsx)(s.h3,{id:"compatibility-mode",children:"Compatibility Mode"}),"\n",(0,o.jsx)(s.p,{children:"Some users may wish for Pluto keywords to be off by default, for which we provide the following options:"}),"\n",(0,o.jsxs)(s.ul,{children:["\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.strong,{children:"For Integrators:"})," Check your ",(0,o.jsx)(s.code,{children:"luaconf.h"}),' file to find the relevant macros under the "Compatibility" heading.']}),"\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.strong,{children:"For Scripters:"})," Put ",(0,o.jsx)(s.code,{children:"-- @pluto_use * = false"})," at the top of your script."]}),"\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.strong,{children:"For Users:"})," Pass the ",(0,o.jsx)(s.code,{children:"-c"})," flag to ",(0,o.jsx)(s.code,{children:"pluto"})," or ",(0,o.jsx)(s.code,{children:"plutoc"}),"."]}),"\n"]}),"\n",(0,o.jsx)(s.p,{children:"Note that when keywords have been disabled like this, Pluto will not infer that a script requires them automatically, instead requiring explicit opt-in via pluto_use."}),"\n",(0,o.jsx)(s.h3,{id:"compile-time-configuration-pluto_use",children:"Compile-time Configuration (pluto_use)"}),"\n",(0,o.jsxs)(s.p,{children:["You can change the meaning of Pluto's reserved tokens at any point in y

1our scripts using the ",(0,o.jsx)(s.code,{children:"--@pluto_use"})," comment or ",(0,o.jsx)(s.code,{children:"pluto_use"})," statement."]}),"\n",(0,o.jsxs)(s.p,{children:["For example, to disable all non-compatible keywords except for ",(0,o.jsx)(s.code,{children:"switch"}),":"]}),"\n",(0,o.jsxs)(s.pre,{className:"shiki monokai",style:{backgroundColor:"#272822",color:"#F8F8F2"},children:[(0,o.jsx)(s.div,{className:"language-id",children:"pluto"}),(0,o.jsx)(s.div,{className:"code-container",children:(0,o.jsx)(s.code,{children:(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#88846F"},children:"-- "}),(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"@pluto_use"}),(0,o.jsx)(s.span,{style:{color:"#88846F"},children:" * = false, switch"})]})})})]}),"\n",(0,o.jsx)(s.p,{children:"It is also possible to specify a version number, which is a shorthand for the keywords available at that version:"}),"\n",(0,o.jsxs)(s.ul,{children:["\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.code,{children:'"0.2.0"'})," corresponds to ",(0,o.jsx)(s.code,{children:"* = false, switch, continue"})]}),"\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.code,{children:'"0.5.0"'})," corresponds to ",(0,o.jsx)(s.code,{children:"* = false, switch, continue, enum"})]}),"\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.code,{children:'"0.6.0"'})," corresponds to ",(0,o.jsx)(s.code,{children:"* = false, switch, continue, enum, new, class, parent, export"})]}),"\n"]}),"\n",(0,o.jsx)(s.p,{children:"So, writing a portable script that only makes use of Pluto 0.6.0's keywords requires this at the beginning:"}),"\n",(0,o.jsxs)(s.pre,{className:"shiki monokai",style:{backgroundColor:"#272822",color:"#F8F8F2"},children:[(0,o.jsx)(s.div,{className:"language-id",children:"pluto"}),(0,o.jsx)(s.div,{className:"code-container",children:(0,o.jsx)(s.code,{children:(0,o.jsxs)(s.div,{className:"line",children:[(0,o.jsx)(s.span,{style:{color:"#F92672"},children:"pluto_use"}),(0,o.jsx)(s.span,{style:{color:"#F8F8F2"},children:" "}),(0,o.jsx)(s.span,{style:{color:"#E6DB74"},children:'"0.6.0"'})]})})})]}),"\n",(0,o.jsxs)(s.p,{children:["For module developers and scripts which may be used in future versions of Pluto, we recommend you use ",(0,o.jsx)(s.code,{children:"pluto_use"})," for two reasons:"]}),"\n",(0,o.jsxs)(s.ul,{children:["\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.strong,{children:"Portability."})," This will override the compatibility mode settings compiled into Pluto so your script will be parsed identically in all Pluto environments."]}),"\n",(0,o.jsxs)(s.li,{children:[(0,o.jsx)(s.strong,{children:"Proactive compatibility."})," Any keywords added by future versions of Pluto will also be put in compatibility mode by these statements, so in the off-chance your script uses a future reserved keyword as a variable name, it would still parse as you intended when you wrote it."]}),"\n"]}),"\n",(0,o.jsx)(s.h3,{id:"compatible-keywords",children:"Compatible Keywords"}),"\n",(0,o.jsxs)(s.p,{children:["Another way of using Pluto's features regardless of compatibility mode is by prefixing the keyword with ",(0,o.jsx)(s.code,{children:"pluto_"}),". For example, ",(0,o.jsx)(s.code,{children:"switch"})," becomes ",(0,o.jsx)(s.code,{children:"pluto_switch"}),". These Compatibility Mode variants will always be valid, even when Compatibility Mode is disabled."]}),"\n",(0,o.jsx)(s.p,{children:"These are what they look like:"}),"\n",(0,o.jsxs)(s.ul,{children:["\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_switch"})}),"\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_continue"})}),"\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_enum"})}),"\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_new"})}),"\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_class"})}),"\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_parent"})}),"\n",(0,o.jsx)(s.li,{children:(0,o.jsx)(s.code,{children:"pluto_export"})}),"\n"]})]})}function h(e={}){const{wrapper:s}={...(0,n.R)(),...e.components};return s?(0,o.jsx)(s,{...e,children:(0,o.jsx)(a,{...e})}):a(e)}},8453:(e,s,i)=>{i.d(s,{R:()=>r,x:()=>t});

1var l=i(6540);const o={},n=l.createContext(o);function r(e){const s=l.useContext(n);return l.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function t(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),l.createElement(n.Provider,{value:s},e.children)}}}]);