diff --git a/docs/source/config_reference/scripting/index.rst b/docs/source/config_reference/scripting/index.rst index 8f333d53..a28831b4 100644 --- a/docs/source/config_reference/scripting/index.rst +++ b/docs/source/config_reference/scripting/index.rst @@ -11,6 +11,7 @@ contain reference documentation for each built-in variable and scripting functio entry_variables override_variables scripting_functions + scripting_types How it Works ------------ @@ -42,7 +43,7 @@ We can use this instead of hard-coding it above: output_options: output_directory: "{subscription_name}" -The syntax for variable usage is brackets with the variable name within it. Assuming +The syntax for variable usage is curly-braces with the variable name within it. Assuming our subscription is actually named "Custom YTDL-SUB TV Show", then ``ytdl-sub`` will actually write to that directory. @@ -67,25 +68,6 @@ title in its name. We can do that using entry variables: file_name: "{title}.{ext}" thumbnail_name: "{title}.{thumbnail_ext}" -Sanitizing Variables -~~~~~~~~~~~~~~~~~~~~ - -For experienced ``yt-dlp`` scrapers, you may be thinking: - -- "what if the title has characters that do not play nice with my operating system?" - -``ytdl-sub`` is able to *sanitize* any variable, meaning it strips any bad characters out -and can be used for file names. We can ensure our file names and directories by using: - -.. code-block:: yaml - - output_options: - output_directory: "{subscription_name_sanitized}" - file_name: "{title_sanitized}.{ext}" - thumbnail_name: "{title_sanitized}.{thumbnail_ext}" - -Simply add a ``_sanitized`` suffix to any variable name to make it sanitized. - Creating Custom Variables ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -98,6 +80,27 @@ for creating and overriding custom variables. These are created in the ``overrides`` section. Let's take our above example and create a ``custom_file_name`` variable to use for the entry file and thumbnail fields: +.. code-block:: yaml + + output_options: + output_directory: "{subscription_name}" + file_name: "{custom_file_name}.{ext}" + thumbnail_name: "{custom_file_name}.{thumbnail_ext}" + + overrides: + custom_file_name: "{upload_date_standardized} {title}" + +Sanitizing Variables +~~~~~~~~~~~~~~~~~~~~ + +For experienced ``yt-dlp`` scrapers, you may be thinking: + +- What if the title has characters that do not play nice with my operating system? + +``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic characters +with safe alternatives that can be used in file names. We can ensure our file names and directories +are safe by using: + .. code-block:: yaml output_options: @@ -108,12 +111,21 @@ a ``custom_file_name`` variable to use for the entry file and thumbnail fields: overrides: custom_file_name: "{upload_date_standardized} {title_sanitized}" +Simply add a ``_sanitized`` suffix to any variable name to make it sanitized. + +.. note:: + + Make sure you do not sanitize custom variables that intentionally create directories, otherwise + they will... be sanitized and not resolve to directories! + + Using Scripting Functions ~~~~~~~~~~~~~~~~~~~~~~~~~ Let's suppose you are an avid command-line user, and like all of your file names to be -``snake_cased_with_no_spaces``. We can use *scripting functions* to create and use a snake-cased -title. +``snake_cased_with_no_spaces``. We can use the +`replace `_ +*scripting function* to create and use a snake-cased title. .. code-block:: yaml @@ -127,6 +139,24 @@ title. { %replace( title, ' ', '_' ) } - custom_file_name: "{upload_date_standardized} {snake_cased_title_sanitized}" + custom_file_name: "{upload_date_standardized}_{snake_cased_title_sanitized}" -You will notice that we use `>-`. This is YAML's way to say "allow a string to be multi-lined \ No newline at end of file +Scripting functions are similar to variables - they must be used within curly-braces. +It is good practice to use ``>-`` when defining variables that use functions. It is YAML's way of +saying: + +- Allow a string to be multi-lined, and do not include newlines before or after it. + +See for yourself `here `_. +Any whitespace within curly-braces is okay since it will be parsed out. This is needed to make +scripting function usage readable. + +.. important:: + + It is important to use ``>-`` over other YAML new-line directives like ``>`` because they + add newlines before or after curly-braces, and will be included in your variable's output string. + +Advanced Scripting +------------------ + +WIP! \ No newline at end of file diff --git a/docs/source/config_reference/scripting/scripting_types.rst b/docs/source/config_reference/scripting/scripting_types.rst new file mode 100644 index 00000000..3688ff87 --- /dev/null +++ b/docs/source/config_reference/scripting/scripting_types.rst @@ -0,0 +1,256 @@ + +Scripting Types +=============== + +Types +----- + +String +~~~~~~ + +Strings are a series of characters surrounded by quotes and can be defined in a few ways, including: + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + string_variable: "This is a String variable" + + .. tab-item:: In-Line + + .. code-block:: yaml + + string_variable: "{ %string('This is a String variable') }" + + .. tab-item:: Single Quote + + .. code-block:: yaml + + string_variable: >- + { + %string('This is a String variable') + } + + .. tab-item:: Double Quote + + .. code-block:: yaml + + string_variable: >- + { + %string("This is a String variable") + } + + .. tab-item:: Triple Quote + + .. code-block:: yaml + + string_variable: >- + { + %string('''This is a String variable''') + } + + .. tab-item:: Triple-Double Quote + + .. code-block:: yaml + + string_variable: >- + { + %string("""This is a String variable""") + } + +.. note:: + + For non-String types, they must be defined using scripting functions. This is because + anything in a variable definition that is not within curly-braces gets evaluated as a String. + +Integer +~~~~~~~ + +Integers are whole numbers with no decimal. + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + int_variable: >- + { + %int(2022) + } + + .. tab-item:: In-Line + + .. code-block:: yaml + + int_variable: "{ %int(2022) }" + +Float +~~~~~ + +Floats are floating-point decimals numbers. + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + float_variable: >- + { + %float(3.14) + } + + .. tab-item:: In-Line + + .. code-block:: yaml + + float_variable: "{ %float(3.14) }" + +Boolean +~~~~~~~ + +A type is considered boolean if it spells out ``True`` or ``False``, case-insensitive. + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + bool_variable: >- + { + %bool(True) + } + + .. tab-item:: In-Line + + .. code-block:: yaml + + bool_variable: "{ %bool(FALSE) }" + +Array +~~~~~ + +An Array contains multiple types of any kind, including nested Arrays and Maps. +Arrays are defined using brackets (``[ ]``), and are accessed using zero-based indexing. + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + array_variable: >- + { + [ + "element with index 0", + 1, + 2.0, + [ "Nested Array 3" ] + ] + } + element_0: >- + { + %array_at(array_variable, 0) + } + + .. tab-item:: In-Line + + .. code-block:: yaml + + array_variable: "{ ['element with index 0', 1, 2.0, ['Nested Array 3' ]] }" + element_0: "{ %array_at(array_variable, 0) }" + +Map +~~~ + +A Map is a key-value store, containing mappings between keys and values. +Maps are defined using curley-braces (``{ }``), and are accessed using their keys. + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + map_variable: >- + { + { + "string_key": "string_value", + 1: "int_key", + "list_value": [ "elem0", 1, 2.0 ] + } + } + string_value: >- + { + %map_get(map_variable, "string_key") + } + + .. tab-item:: In-Line + + .. code-block:: yaml + + map_variable: "{ {'string_key': 'string_value', 1: 'int_key', 'list_value': [ 'elem0', 1, 2.0 ]} }" + string_value: "{ %map_get(map_variable, 'string_key') }" + +Null +~~~~ +Null is represented by an empty String, and can be conveyed by spelling out ``null``, +case-insensitive. + +.. tab-set:: + + .. tab-item:: Literal + + .. code-block:: yaml + + null_variable: "" + + .. tab-item:: In-Line + + .. code-block:: yaml + + null_variable: "{ %string(null) }" + + +Union Types +----------- + +AnyArgument +~~~~~~~~~~~ +AnyArgument means any of the above Types are valid as input or output to a scripting function. + +Numeric +~~~~~~~ +Numeric refers to either an Integer or Float. + +Optional +~~~~~~~~ +Optional means a particular scripting function argument can be either provided or not included. + +Lambdas +------- + +Lambda +~~~~~~ +WIP + +LambdaTwo +~~~~~~~~~ + +LambdaThree +~~~~~~~~~~~ + +LambdaReduce +~~~~~~~~~~~~ + +ReturnableArguments +------------------- + +Returnable arguments are used in conditional functions like ``%if``, which implies the argument +passed into the function is the function's output. + +