{ "content": [ { "type": "text", "text": "# Inline::API (perldoc)\n\n## NAME\n\nInline-API - How to bind a programming language to Perl using Inline.pm\n\n## SYNOPSIS\n\n#!/usr/bin/perl\nuse Inline Foo;\nsayit('foo'); # Use Foo to print \"Hello, Foo\"\nFoo\nfoo-sub sayit {\nfoo-my $foo = foo-shift;\nfoo-print \"Hello, $foo\\n\";\n}\n\n## DESCRIPTION\n\nSo you think Inline C is pretty cool, but what you really need is for Perl to work with the\nbrand new programming language \"Foo\". Well you're in luck. \"Inline.pm\" has support for adding\nyour own Inline Language Support Module (ILSM), like \"Inline::Foo\".\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **A SKELETON**\n- **THE INLINE API**\n- **THE INLINE OBJECT**\n- **THE INLINE NAMESPACE**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Inline::API", "section": "", "mode": "perldoc", "summary": "Inline-API - How to bind a programming language to Perl using Inline.pm", "synopsis": "#!/usr/bin/perl\nuse Inline Foo;\nsayit('foo'); # Use Foo to print \"Hello, Foo\"\nFoo\nfoo-sub sayit {\nfoo-my $foo = foo-shift;\nfoo-print \"Hello, $foo\\n\";\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 11, "subsections": [] }, { "name": "DESCRIPTION", "lines": 23, "subsections": [] }, { "name": "A SKELETON", "lines": 136, "subsections": [] }, { "name": "THE INLINE API", "lines": 71, "subsections": [] }, { "name": "THE INLINE OBJECT", "lines": 58, "subsections": [] }, { "name": "THE INLINE NAMESPACE", "lines": 18, "subsections": [] }, { "name": "SEE ALSO", "lines": 10, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "Inline-API - How to bind a programming language to Perl using Inline.pm\n", "subsections": [] }, "SYNOPSIS": { "content": "#!/usr/bin/perl\n\nuse Inline Foo;\nsayit('foo'); # Use Foo to print \"Hello, Foo\"\n\nFoo\nfoo-sub sayit {\nfoo-my $foo = foo-shift;\nfoo-print \"Hello, $foo\\n\";\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "So you think Inline C is pretty cool, but what you really need is for Perl to work with the\nbrand new programming language \"Foo\". Well you're in luck. \"Inline.pm\" has support for adding\nyour own Inline Language Support Module (ILSM), like \"Inline::Foo\".\n\nInline has always been intended to work with lots of different programming languages. Many of\nthe details can be shared between implementations, so that \"Inline::Java\" has a similar\ninterface to \"Inline::ASM\". All of the common code is in \"Inline.pm\".\n\nLanguage specific modules like \"Inline::Python\" are subclasses of \"Inline.pm\". They can inherit\nas much of the common behaviour as they want, and provide specific behaviour of their own. This\nusually comes in the form of Configuration Options and language specific compilation.\n\nThe Inline C support is probably the best boilerplate to copy from. Since version 0.30 all C\nsupport was isolated into the module \"Inline::C\" and the parsing grammar is further broken out\ninto \"Inline::C::grammar\". All of these components come with the Inline distribution.\n\nThis POD gives you all the details you need for implementing an ILSM. For further assistance,\ncontact inline@perl.org See [\"SEE ALSO\"] below.\n\nWe'll examine the joke language Inline::Foo which is distributed with Inline. It actually is a\nfull functioning ILSM. I use it in Inline's test harness to test base Inline functionality. It\nis very short, and can help you get your head wrapped around the Inline API.\n", "subsections": [] }, "A SKELETON": { "content": "For the remainder of this tutorial, let's assume we're writing an ILSM for the ficticious\nlanguage \"Foo\". We'll call it \"Inline::Foo\". Here is the entire (working) implementation.\n\npackage Inline::Foo;\nuse strict;\n$Inline::Foo::VERSION = '0.01';\n@Inline::Foo::ISA = qw(Inline);\nrequire Inline;\nuse Carp;\n\n#===========================================================\n# Register Foo as an Inline Language Support Module (ILSM)\n#===========================================================\nsub register {\nreturn {\nlanguage => 'Foo',\naliases => ['foo'],\ntype => 'interpreted',\nsuffix => 'foo',\n};\n}\n\n#===========================================================\n# Error messages\n#===========================================================\nsub usageconfig {\nmy ($key) = @;\n\"'$key' is not a valid config option for Inline::Foo\\n\";\n}\n\nsub usageconfigbar {\n\"Invalid value for Inline::Foo config option BAR\";\n}\n\n#===========================================================\n# Validate the Foo Config Options\n#===========================================================\nsub validate {\nmy $o = shift;\n$o->{ILSM}{PATTERN} ||= 'foo-';\n$o->{ILSM}{BAR} ||= 0;\nwhile (@) {\nmy ($key, $value) = splice @, 0, 2;\nif ($key eq 'PATTERN') {\n$o->{ILSM}{PATTERN} = $value;\nnext;\n}\nif ($key eq 'BAR') {\ncroak usageconfigbar\nunless $value =~ /^[01]$/;\n$o->{ILSM}{BAR} = $value;\nnext;\n}\ncroak usageconfig($key);\n}\n}\n\n#===========================================================\n# Parse and compile Foo code\n#===========================================================\nsub build {\nmy $o = shift;\nmy $code = $o->{API}{code};\nmy $pattern = $o->{ILSM}{PATTERN};\n$code =~ s/$pattern//g;\n$code =~ s/bar-//g if $o->{ILSM}{BAR};\nsleep 1; # imitate compile delay\n{\npackage Foo::Tester;\neval $code;\n}\ncroak \"Foo build failed:\\n$@\" if $@;\nmy $path = \"$o->{API}{installlib}/auto/$o->{API}{modpname}\";\nmy $obj = $o->{API}{location};\n$o->mkpath($path) unless -d $path;\nopen FOOOBJ, \"> $obj\"\nor croak \"Can't open $obj for output\\n$!\";\nprint FOOOBJ $code;\nclose \\*FOOOBJ;\n}\n\n#===========================================================\n# Only needed for interpreted languages\n#===========================================================\nsub load {\nmy $o = shift;\nmy $obj = $o->{API}{location};\nopen FOOOBJ, \"< $obj\"\nor croak \"Can't open $obj for output\\n$!\";\nmy $code = join '', ;\nclose \\*FOOOBJ;\neval \"package $o->{API}{pkg};\\n$code\";\ncroak \"Unable to load Foo module $obj:\\n$@\" if $@;\n}\n\n#===========================================================\n# Return a small report about the Foo code.\n#===========================================================\nsub info {\nmy $o = shift;\nmy $text = <<'END';\nThis is a small report about the Foo code. Perhaps it contains\ninformation about the functions the parser found which will be\nbound to Perl. It will get included in the text produced by the\nInline 'INFO' command.\nEND\nreturn $text;\n}\n\n1;\n\nExcept for \"load()\", the subroutines in this code are mandatory for an ILSM. What they do is\ndescribed below. A few things to note:\n\n* \"Inline::Foo\" must be a subclass of Inline. This is accomplished with:\n\n@Inline::Foo::ISA = qw(Inline);\n\n* The line '\"require Inline;\"' is not necessary. But it is there to remind you not to say\n'\"use Inline;\"'. This will not work.\n\n* Remember, it is not valid for a user to say:\n\nuse Inline::Foo;\n\n\"Inline.pm\" will detect such usage for you in its \"import\" method, which is automatically\ninherited since \"Inline::Foo\" is a subclass.\n\n* In the build function, you normally need to parse your source code. Inline::C uses\nParse::RecDescent to do this. Inline::Foo simply uses eval. (After we strip out all\noccurrences of 'foo-').\n\nAn alternative parsing method that works well for many ILSMs (like Java and Python) is to\nuse the language's compiler itself to parse for you. This works as long as the compiler can\nbe made to give back parse information.\n", "subsections": [] }, "THE INLINE API": { "content": "This section is a more formal specification of what functionality you'll need to provide to\nimplement an ILSM.\n\nWhen Inline determines that some \"Foo\" code needs to be compiled it will automatically load your\nILSM module. It will then call various subroutines which you need to supply. We'll call these\nsubroutines \"callbacks\".\n\nYou will need to provide the following 5 callback subroutines.\n\nThe register() Callback\nThis subroutine receives no arguments. It returns a reference to a hash of ILSM meta-data.\nInline calls this routine only when it is trying to detect new ILSM-s that have been installed\non a given system. Here is an example of the has ref you would return for Foo:\n\n{\nlanguage => 'Foo',\naliases => ['foo'],\ntype => 'interpreted',\nsuffix => 'foo',\n};\n\nThe meta-data items have the following meanings:\n\nlanguage\nThis is the proper name of the language. It is usually implemented as \"Inline::X\" for a\ngiven language 'X'.\n\naliases\nThis is a reference to an array of language name aliases. The proper name of a language can\nonly contain word characters. A-Za-z0-9 An alias can contain any characters except\nwhitespace and quotes. This is useful for names like 'C++' and 'C#'.\n\ntype\nMust be set to 'compiled' or 'interpreted'. Indicates the category of the language.\n\nsuffix\nThis is the file extension for the cached object that will be created. For 'compiled'\nlanguages, it will probably be 'so' or 'dll'. The appropriate value is in \"Config.pm\".\n\nFor interpreted languages, this value can be whatever you want. Python uses \"pydat\". Foo\nuses \"foo\".\n\nThe validate() Callback\nThis routine gets passed all configuration options that were not already handled by the base\nInline module. The options are passed as key/value pairs. It is up to you to validate each\noption and store its value in the Inline object (which is also passed in). If a particular\noption is invalid, you should croak with an appropriate error message.\n\nNote that all the keywords this routine receives will be converted to upper- case by \"Inline\",\nwhatever case the program gave.\n\nThe build() Callback\nThis subroutine is responsible for doing the parsing and compilation of the Foo source code. The\nInline object is passed as the only argument. All pertinent information will be stored in this\nobject. \"build()\" is required to create a cache object of a specific name, or to croak with an\nappropriate error message.\n\nThis is the meat of your ILSM. Since it will most likely be quite complicated, it is probably\nbest that you study an existing ILSM like \"Inline::C\".\n\nThe load() Callback\nThis method only needs to be provided for interpreted languages. It's responsibility is to start\nthe interpreter.\n\nFor compiled languages, the load routine from \"Inline.pm\" is called which uses \"DynaLoader\" to\nload the shared object or DLL.\n\nThe info() Callback\nThis method is called when the user makes use of the \"INFO\" shortcut. You should return a string\ncontaining a small report about the Inlined code.\n", "subsections": [] }, "THE INLINE OBJECT": { "content": "\"Inline.pm\" creates a hash based Perl object for each section of Inlined source code it\nreceives. This object contains lots of information about the code, the environment, and the\nconfiguration options used.\n\nThis object is a hash that is broken into several subhashes. The only two subhashes that an ILSM\nshould use at all are $o->{API} and $o->{ILSM}. The first one contains all of the information\nthat Inline has gather for you in order for you to create/load a cached object of your design.\nThe second one is a repository where your ILSM can freely store data that it might need later\non.\n\nThis section will describe all of the Inline object \"API\" attributes.\n\nThe code Attribute\nThis the actual source code passed in by the user. It is stored as one long string.\n\nThe language Attribute\nThe proper name of the language being used.\n\nThe languageid Attribute\nThe language name specified by the user. Could be 'C++' instead of 'CPP'.\n\nThe module Attribute\nThis is the shared object's file name.\n\nThe modfname Attribute\nThis is the shared object's file name.\n\nThe modpname Attribute\nThis is the shared object's installation path extension.\n\nThe version Attribute\nThe version of \"Inline.pm\" being used.\n\nThe pkg Attribute\nThe Perl package from which this invocation pf Inline was called.\n\nThe installlib Attribute\nThis is the directory to write the shared object into.\n\nThe builddir Attribute\nThis is the directory under which you should write all of your build related files.\n\nThe script Attribute\nThis is the name of the script that invoked Inline.\n\nThe location Attribute\nThis is the full path name of the executable object in question.\n\nThe suffix Attribute\nThis is the shared library extension name. (Usually 'so' or 'dll').\n\nderiveminusI Method\nILSMs may need to run Perl subprocesses with a similar environment to the current one -\nparticularly @INC. This method can be called to return a list of absolute paths to pass to a\nPerl interpreter to recreate that environment. You will need to prepend \"-I\" to each one. This\nmethod omits from that list any paths that occur in $ENV{PERL5LIB} or the Perl default libraries\nsince those will be available already.\n", "subsections": [] }, "THE INLINE NAMESPACE": { "content": "\"Inline.pm\" has been set up so that anyone can write their own language support modules. It\nfurther allows anyone to write a different implementation of an existing Inline language, like C\nfor instance. You can distribute that module on the CPAN.\n\nIf you have plans to implement and distribute an Inline module, I would ask that you please work\nwith the Inline community. We can be reached at the Inline mailing list: inline@perl.org (Send\nmail to inline-subscribe@perl.org to subscribe). Here you should find the advice and assistance\nneeded to make your module a success.\n\nThe Inline community will decide if your implementation of COBOL will be distributed as the\nofficial \"Inline::COBOL\" or should use an alternate namespace. In matters of dispute, I (Ingy\ndöt Net) retain final authority. (and I hope not to need use of it :-) Actually modules@perl.org\nretains the final authority.\n\nBut even if you want to work alone, you are free and welcome to write and distribute Inline\nlanguage support modules on CPAN. You'll just need to distribute them under a different package\nname.\n", "subsections": [] }, "SEE ALSO": { "content": "For generic information about Inline, see Inline.\n\nFor information about using Inline with C see Inline::C.\n\nFor information on supported languages and platforms see Inline-Support.\n\nInline's mailing list is inline@perl.org\n\nTo subscribe, send email to inline-subscribe@perl.org\n", "subsections": [] }, "AUTHOR": { "content": "Ingy döt Net \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2000-2019. Ingy döt Net.\n\nCopyright 2008, 2010, 2011. Sisyphus.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nSee \n", "subsections": [] } } } }